Android SMS Gateway setup

1. Requirements

Before you start, make sure you have the following.

• ■Android device. Phone or tablet running Android 5.0 (Lollipop) or higher. Android 8.0+ is recommended for all features.
• ■SIM card. A SIM with an active SMS plan. The device will send and receive SMS using this SIM.
• ■Network. Mobile data or Wi‑Fi so the device can reach the dashboard and receive API requests. Wi‑Fi or USB tethering is often used so the phone stays online.
• ■Account. You will need to register or log in to the SMS Gateway service (via the app or web dashboard) to get an API key.

For app download and optional tools (e.g. Always ON, ADB), see Downloads. For how the gateway works end-to-end, see Android SMS Gateway.

2. Android device setup

Install the SMS Gateway app on the Android device.

1. Download the APK from Downloads (SMS Gateway Android App). Or use the official link provided there.
2. On the device, allow installation from unknown sources if you are sideloading the APK (Settings → Security or Apps → Install unknown apps).
3. Open the APK and complete the installation. Grant the permissions the app requests when prompted (see section 4).
4. Ensure the device has a stable connection: Wi‑Fi or mobile data. For 24/7 use, many users keep the device plugged in and use an app like Always ON to reduce sleep (optional, see Downloads).

The app runs in the background and exposes an API that your backend will call. Do not force-stop the app if you want it to receive send requests and deliver SMS.

3. SIM configuration

The SIM is used by the device modem to send and receive SMS.

• ■Insert the SIM into the device (tray or slot as per the device manual). Power on or restart if needed.
• ■Confirm the SIM is active: check that the device shows signal and can send/receive SMS manually (e.g. via the default messaging app).
• ■Ensure the plan includes SMS. Some data-only SIMs cannot send SMS.
• ■If the app supports multiple SIMs, choose which SIM slot to use for sending in the app settings.

Coverage and cost depend on the carrier and plan. For regional deliverability (e.g. local numbers), see SMS gateway by country.

4. App permissions

The SMS Gateway app needs certain permissions to send and receive SMS and to run reliably.

• ■SMS. Required to read and send SMS. Grant when the app asks.
• ■Phone. Often required to access the modem/SIM state. Grant if prompted.
• ■Storage (optional). May be used for logs or attachments. Grant if you need those features.
• ■Battery / background. On some devices, you must allow the app to run in the background or disable battery optimization for it so it can receive API calls and send SMS at any time.

If the app is killed or restricted by the system, it will not receive send requests until it is running again. Check device-specific settings (e.g. Samsung, Xiaomi) for “allow background activity” or similar.

5. Connecting to dashboard / API

You need an account and an API key to send SMS from your backend.

1. Open the SMS Gateway app (or go to the web dashboard, e.g. https://app.sms-gateway.app).
2. Register or log in. Complete any verification required.
3. In the app or under Settings / API in the dashboard, find your API key. Copy and store it securely. You will pass this key on every API request.
4. Ensure the device is registered and online. The app normally registers the device automatically when it is running and connected. In the dashboard you should see the device listed.

API base URL and endpoints: Official API reference. Send Authorization: Bearer <key> on every request. Interactive docs also cover DLR (GET /messages/{id}) and webhooks.

Do not expose the API key in client-side code or public repos. Use environment variables or a secrets store on your server.

6. Sending your first SMS

After the device is online and you have your API key, send a test message.

1. Call POST https://app.sms-gateway.app/api/v1/messages with header Authorization: Bearer <key> and JSON { "to": ["+14155551234"], "text": "…" }. Numbers are E.164 with a leading +.
2. Check the response. On success you get a message ID. If you get an error (e.g. invalid key, device not found), fix the cause and retry.
3. Confirm delivery: use the message ID with the DLR endpoint or your webhook. See DLR (delivery reports).

Use cases and integration patterns: OTP verification, Transactional SMS, Bulk SMS. Full API reference: docs.sms-gateway.app.

7. Common issues and fixes

Message not sending / “Device doesn’t exist” (500)

The device may not be registered or the app may be stopped. Open the app, ensure it is running and has network access. Check the dashboard to see if the device appears. Restart the app or device if needed.

Invalid API key (401)

Confirm you are using the correct API key from the app or dashboard. Copy it again; ensure there are no extra spaces. If you rotated the key, update your code or config.

SMS stuck as Pending

The message is queued or with the carrier. Check device signal and that the SIM can send SMS. See DLR for status meanings. If the device was offline, messages are sent when it comes back online.

App stops receiving requests (background killed)

Disable battery optimization for the SMS Gateway app. Allow “run in background” (wording varies by manufacturer). Optionally use an “Always ON” style app to reduce sleep (see Downloads).

Missing parameters (400)

Send requests need header Authorization: Bearer and JSON to plus text. Numbers are E.164 with a leading +. See API reference.

Rate limit (429)

You exceeded the allowed requests per minute. Wait and retry with backoff. For higher limits, check your plan or Pricing.