How to set up an SMS Gateway

The SMS Gateway integration lets your organization deliver SMS through its own provider — any provider with an HTTP “send SMS” API — instead of MileApp’s default SMS service. You describe your provider as a plain HTTP request (an endpoint, a method, headers, and body or query fields), enter your own credentials directly into that request, and MileApp calls it for every SMS. Ready-made templates for common providers (such as Twilio and GoSMS) give you a head start, but any provider works. While a gateway is connected, MileApp substitutes just two placeholders at send time — {recipient} (the destination phone number) and {message} (the SMS text) — and sends everything else exactly as you entered it. Organizations that do not connect a gateway are unaffected: their SMS continues to go through MileApp’s default service.

​

Where it’s used

Once connected, your gateway delivers every SMS MileApp sends on your behalf:

• OTP component — the one-time-password SMS sent from a Flow’s OTP component.
• Automation notifications — the SMS sent by an Automation notification action.

Both are delivered through your own gateway using your provider’s credentials, so no MileApp SMS credits are deducted for either.

​

Before you begin

Check your provider’s “send SMS” API documentation and have these ready:

• The endpoint URL it exposes for sending an SMS, and the HTTP method it expects (usually POST, sometimes GET).
• Your credentials — an API token, an API key, or a username/password pair — and where each value belongs in the request (a header, the URL, or a request field).
• The names of the fields your provider expects for the recipient number and the message text (for example to/text, msisdn/message, To/Body).
• The sender number or sender ID your provider requires, if any.
• A test phone number (in international format, e.g. +6281234567890) that can receive one verification SMS.

​

Step 1: Open the SMS Gateway card

1. Go to Setting ➝ Integration.
2. Find the SMS Gateway card. When no gateway is connected, it shows a Connect button.
3. Click Connect to open the Configure SMS Gateway form.

The SMS Gateway card before a gateway is connected

​

Step 2: Choose a starting template and set the endpoint

The Provider dropdown offers ready-made templates — Twilio, GoSMS Gateway, and Other (set up manually). A template pre-fills the endpoint, method, and header and body rows with placeholder text (shown as XXXXX / YYYYY) that you replace with your own values. Pick the template closest to your provider, or Other to build the request from scratch. The template is only a starting point — every field stays fully editable.

1. Provider — pick a starting template (or Other for a fully manual setup).
2. Label — a name for this gateway, so you can recognise it later.
3. Endpoint URL — the URL MileApp calls to send each SMS. Enter it exactly as your provider’s API documents it. If your provider puts a credential or account identifier in the URL (some do), place it there and replace the placeholder with your value.
4. Method — the HTTP method your provider expects (commonly POST; some providers use GET).

Pick a Provider template (1), then set the Label (2), Endpoint URL (3), and Method (4) — replace every placeholder (XXXXX / YYYYY) with your own value

​

Step 3: Enter your credentials

Credentials go directly into the request — you type each value into the Headers and Body / Query rows, which are always visible in the form. There is no separate “authentication” section; you put each credential wherever your provider expects it, and tick Secret on any sensitive value so it is encrypted at rest and shown blank when you reopen the form.

​

Authentication

Most providers authenticate with an HTTP header. The templates pre-fill an Authorization header — replace its placeholder with your credential. MileApp sends every header exactly as you type it, so enter the value in the exact form your provider expects. Tick Secret on the credential value so it is encrypted at rest and shown blank when you reopen the form (the checkbox starts unticked, so remember to tick it once you’ve entered a real credential).

• Bearer token — Authorization: Bearer <your token>.
• Basic auth — Authorization: Basic <Base64 of username:password>. You Base64-encode the username:password (or, for Twilio, AccountSID:AuthToken) yourself — MileApp does not encode it for you.
• API-key header — a custom header such as X-API-Key: <your key>.
• Query-parameter auth — some providers (for example a GoSMS-style gateway on a GET request) pass credentials as query parameters instead of a header; enter those as Secret query rows in the Body / Query section.

The templates also pre-fill a Content-Type header at the top of the list — application/x-www-form-urlencoded for Twilio, application/json otherwise. Leave it as-is unless your provider expects a different content type; it is an ordinary editable header row.

The templates pre-fill a Content-Type header (1) and an Authorization header (2) — replace the Authorization placeholder with your credential and tick Secret

​

Recipient, message, and other fields

The Body parameters (shown as Query parameters when the method is GET) are the fields sent to your provider. Two rows are locked — {recipient} and {message} — because MileApp fills those at send time and needs both to deliver the SMS. You only set the key each one uses, to match your provider’s field names. Add your own rows below them for anything else the request needs.

1. {recipient} row — set its key to your provider’s recipient field (for example to, msisdn, or To). The value stays locked to {recipient}, and the row has no Secret checkbox.
2. {message} row — set its key to your provider’s message field (for example text, message, or Body). The value stays locked to {message}, and the row has no Secret checkbox.
3. Your own rows — click Add parameter to add any other fields your provider requires, such as a sender number. These rows are fully editable and can be removed; tick Secret on any that hold a sensitive value.

The recipient (1) and message (2) rows are locked — you only name their keys; use Add parameter for your own fields (3)

​

Step 4: Verify and save

1. Enter a Test phone number using the dial-code picker and local number. This field is required.
2. Click Save. MileApp sends one real SMS to that number through your gateway to verify it works.

Enter a test number (1), then click Save (2) to verify and connect the gateway

When verification succeeds, the card switches to the connected state and shows your gateway label and endpoint host, with Edit and Disconnect actions. There is no status badge.

A connected gateway shows its label and endpoint host, with Edit and Disconnect actions

​

If verification fails

Saving verifies and blocks on failure. If your provider rejects the test SMS, the save is blocked, nothing is saved, and a red toast shows the provider’s raw error. The form stays open so you can correct the value and save again.

When verification fails, the provider’s error is shown and the form stays open — nothing is saved

Common causes are a wrong credential in the endpoint or a header, an authentication value in the wrong format (for example an unencoded Basic-auth header), a recipient or message field named differently from what your provider expects, or a sender number your provider does not accept. Fix the offending field and click Save again.

​

Editing a gateway

Click the edit (pencil) icon on the connected card. The form reopens with your saved configuration. Any value marked Secret appears blank: leave it blank to keep the stored secret, or type a new value to replace it. Saving re-verifies the gateway exactly like the initial connection.

​

Disconnecting a gateway

Click Disconnect and confirm. Your SMS will be sent through MileApp’s default service again, and MileApp credits will be charged as usual.

​

Notes

1. Billing — while a gateway is connected, OTP and Automation SMS go through your endpoint and no MileApp credits are deducted. Organizations without a gateway are charged as usual.
2. No silent fallback — if your gateway is connected but a send fails, the SMS fails rather than reverting to MileApp’s default service. Fix the configuration or disconnect the gateway to return to the default service.
3. Security — the endpoint host must be publicly reachable (private, loopback, and link-local addresses are rejected) and the scheme must be http or https. Secret values are encrypted at rest and are never shown again after saving.