Use your own SMS service
This guide is for standalone SessionTalk Pro and Free. For a portal-provisioned SessionCloud app, use Customer-hosted messaging.
SessionTalk Pro and Free for Android 8.0.15 (build 736) or later use the setup below for incoming SMS through your own HTTPS service, without a SessionCloud portal project. Install a build that includes this feature; a Google Play submission is not confirmation that it is available in your country yet. iOS needs a separately built and released version containing this feature.
You or your provider must run a compatible HTTPS server (an SMS bridge). Deploying and operating this server requires an administrator. The standalone app purchase does not include a hosted bridge. If your provider operates a compatible service, they supply its URLs and service credentials. The sample bridge is optional.
The SMS provider sends its inbound webhook to that server. The server verifies the webhook, stores the message, calls SessionTalk’s push notifications API, and makes the message available for the app to fetch. A public webhook listener does not run on the phone. Outgoing SMS uses the app’s separate HTTPS gateway settings.
For example, the supplied bridge uses these distinct URLs:
| Purpose | Example | Configured where |
|---|---|---|
| Outgoing SMS gateway | https://YOUR_HOST/send | App’s outgoing Custom gateway settings; direct A&A sending is also supported |
| Provider’s inbound webhook | https://YOUR_HOST/webhooks/twilio | SMS provider’s control panel; choose the path for your provider below |
| Incoming message fetch URL | https://YOUR_HOST/inbox | App’s Incoming messages settings |
| Push registration URL | https://YOUR_HOST/devices | App’s Incoming messages settings; this endpoint is on your bridge |
| SessionTalk push API URL | https://SELECTED_RELAY/byo/webservice/push | Supplied automatically by the app to the bridge |
Download the working example
Download the Python SMS bridge and tests. The archive includes the server, persistent SQLite queue, Docker Compose setup, secure credential generator, webhook verification, tests and a complete README. It has adapters for A&A, Twilio, Telnyx and Custom HTTPS. It supports one number/mailbox per deployment and text SMS. The Custom adapter also has an optional MMS extension requiring an updated app and a downstream MMS adapter. Carrier delivery receipts are outside this example’s scope.
Read the complete setup and API contract or inspect the server source. The server implements the SessionTalk JSON contract below. The app fetches messages from your service and reports its account routing and push credentials automatically. Your service authenticates the app with a username/password or API token. If you adapt an existing server, implement the documented request and response formats; entering its URLs alone does not make a different API compatible.
Configure the server
Follow the downloaded README to deploy the bridge behind HTTPS. Generate fresh service and webhook credentials, set the carrier credentials, and run both the HTTP service and notification worker. Keep provider API keys on the server.
| Provider | Where to send incoming messages | Verification in the example |
|---|---|---|
| A&A | SMS Inbound: https://YOUR_HOST/webhooks/aa/YOUR_RANDOM_SECRET | Private random URL credential and destination-number check |
| Twilio | Number’s incoming-message webhook: POST https://YOUR_HOST/webhooks/twilio | Twilio SDK signature, Account SID and destination |
| Telnyx | Messaging profile webhook: https://YOUR_HOST/webhooks/telnyx | Ed25519 signature, fresh timestamp and destination |
| Custom | POST https://YOUR_HOST/webhooks/custom | HMAC-SHA256 signature, fresh timestamp and destination |
The A&A URL must not end with ? or &, which would select GET. Its callback is
not a signed webhook, so protect the secret URL and exclude it from logs. See the
A&A API . Twilio requires the exact public URL
for signature validation .
The README defines the example’s Custom schema; it differs from the portal’s
Custom integration.
Obtain service credentials
The administrator of your messaging service supplies its login or API token. Use the credentials for that service, which may differ from your SIP and carrier credentials. If the provider runs the service, obtain the login from them. If you write your own service, use your own account and authentication system.
With the downloaded example, run this once from the extracted bridge directory on the server, before starting the service:
python3 bootstrap.pyThe script generates fresh credentials and writes them to the server’s private
.env file without printing them. It refuses to overwrite an existing .env.
The administrator copies the service credentials into the app, or supplies them securely
to the user:
Value in the server’s .env | App field | Purpose |
|---|---|---|
SERVICE_USERNAME | Service username | Login for the bridge; initially sms-user, editable by the administrator |
SERVICE_PASSWORD | Service password | Generated service password; choose Username and password in the app |
SERVICE_API_TOKEN | API token | Optional alternative: choose API token instead of username/password |
The example’s generated INBOX_ID is a server-internal message namespace. Keep
it on the server and preserve it across upgrades; it is not an app setup field.
The app creates its own account routing identifier automatically. Neither value
is an authentication credential. A standalone app purchase does not create a
service account or require a SessionCloud portal account for this setup.
The SessionTalk push token is also automatic and separate from your service login. The app obtains it from our relay and reports it to the bridge. Users do not obtain a SessionTalk push API key manually.
Configure the standalone app
- Disable the SIP account and enable SMS in its advanced messaging settings.
- Configure and save HTTPS > Custom for outgoing SMS. With the example, use
https://YOUR_HOST/send,SERVICE_USERNAMEas the SMS username,SERVICE_PASSWORDas the SMS password, parameter namesusername,password,da,ud, and success prefixOK:. A&A users can keep the direct A&A outgoing preset instead. - Open Advanced SIP settings > Messaging > Incoming messages. The service URL and authentication fields are shown directly; no mailbox setup code is needed.
- Enter these values from your server administrator:
| App field | Example server value |
|---|---|
| Incoming message fetch URL | https://YOUR_HOST/inbox |
| Push registration URL | https://YOUR_HOST/devices |
| SMS number | SMS_NUMBER, including + and country code |
| Service authentication | Username and password for the sample’s default setup, or API token |
| Service username / Service password | SERVICE_USERNAME / SERVICE_PASSWORD from the bridge’s .env |
| API token | Only when that authentication method is selected: SERVICE_API_TOKEN or the token supplied by your service |
Choose Connect service, re-enable the account, enable account push and allow notifications. Keep the app open for initial device registration. Your SIP password is not copied to the bridge. Only the service credentials you explicitly enter are used. Protect them as passwords. URLs require HTTPS and cannot include credentials, query strings or fragments.
Upgrading from build 734 or 735: existing configurations remain connected.
Build 736 removes the standalone mailbox-code option and shows service settings
directly. Earlier service-enabled builds may show an additional switch before
these fields. Their
saved mailbox ID stays internal, and the former mailbox access token is shown
under API token. Saving the same URLs, number and authentication method
retains the routing identifier. Switching services or service usernames creates
a new identifier. Upgrade an older sample bridge before creating a new connection;
the new bridge also accepts its previous MAILBOX_ID / MAILBOX_TOKEN settings.
Authenticate with the SessionTalk push API
There are two separate credentials:
| Credential | Who supplies it | How it is used |
|---|---|---|
| Service credentials | Your service administrator; generated/configured by the sample’s setup script | Enter a username/password or API token in the app. Fetch and push-registration requests use Authorization: Basic BASE64_USERNAME_COLON_PASSWORD (UTF-8), or Authorization: Bearer SERVICE_API_TOKEN. |
| Scoped push token | SessionTalk’s relay, obtained automatically by the app | The app reports it to your bridge. Your bridge uses it as Authorization: Bearer PUSH_TOKEN when requesting a push from SessionTalk. |
The app first authenticates privately with its selected SessionTalk relay using its existing device push token. The relay checks the registered device/profile and issues a signed credential limited to that device, SIP account and mailbox. The bridge receives this scoped credential. It does not need the native FCM/APNs token, SIP password, or SessionTalk’s shared relay secret.
Receive the app’s push registration
Implement an authenticated PUT handler at the bridge’s configured Push registration URL. For the sample, the app sends:
PUT /devices
Authorization: Basic <BASE64_OF_SERVICE_USERNAME_COLON_PASSWORD>
Content-Type: application/json
{
"deviceId": "example-device",
"profileId": 22,
"mailboxId": "00000000-0000-4000-8000-000000000001",
"selector": "00000000-0000-4000-8000-000000000001",
"number": "+15555550101",
"username": "sms-user",
"pushUrl": "https://eupush.sessiontalk.co.uk/byo/webservice/push",
"pushToken": "<SCOPED_PUSH_TOKEN>",
"expiresAt": 1793404800
}The timestamp is illustrative; use the actual expiresAt supplied by the app.
Authenticate the service credentials before accepting the report. Use that
authenticated service account to select the inbox and check the assigned number.
selector is generated by the app; mailboxId carries the same value for
compatibility with the existing relay. Neither grants access to an inbox.
username is supplied with Basic authentication and omitted with Bearer.
Different devices can report different selectors for the same service inbox.
Store or update the route per device/profile, encrypt the push token at rest,
and return HTTP 200 with {"ok":true}. Keep credentials out of logs.
Use the reported pushUrl; the relay can change. Accept only approved HTTPS relay
hosts and the /byo/webservice/push path. The supplied example allows
eupush.sessiontalk.co.uk, uspush.sessiontalk.co.uk and
asiapush.sessiontalk.co.uk. Private push servers
require an explicit administrator-approved hostname and a compatible relay.
Never send a token to an arbitrary URL supplied in an unverified request.
Request a notification
After verifying the provider webhook and committing the full message to your bridge’s inbox, call the reported URL:
POST /byo/webservice/push
Host: eupush.sessiontalk.co.uk
Authorization: Bearer <SCOPED_PUSH_TOKEN>
Content-Type: application/json
{
"messageId": "00000000-0000-4000-8000-000000000002",
"remoteNumber": "+15555550102",
"text": "Hello"
}The host above is an example; use the host from pushUrl. messageId must be the
same stable UUID returned by your fetch API, including on retries. remoteNumber
is the sender’s international number or supported short alphanumeric sender ID.
text can be a short notification preview. The relay always tells the app to
fetch the full message from your configured fetch URL. The credential fixes the
destination account, device and mailbox; the bridge cannot select another one.
| Response | Meaning and action |
|---|---|
200 with {"ok":true} | APNs/FCM accepted the submission; this does not confirm phone delivery or reading. |
400 | Invalid message fields; correct the payload. |
401 | Missing, invalid, expired or invalidated push token; wait for a fresh app registration. Retain the message for fetching. |
404 | The registered push destination is unavailable; check account/device setup. |
413 | Request exceeds the 96 KiB limit; send a short preview and retain the full text in the inbox. |
429 | Rate limited; retry with backoff. The limit is 60 pushes per minute per device/profile on each relay process. |
502 or 503 | Push delivery or service unavailable; retry with backoff. |
Keep the same message UUID across retries. Tokens last seven days, and the app refreshes the report about every five minutes while open and when push routing changes. The user needs to open the app within seven days to renew the grant. A changed device push token, SIP identity, app topic or permanently removed push profile invalidates it. Disconnecting a mailbox makes the app discard its pushes; remove the bridge’s stored route too. The issued credential otherwise remains valid until expiry. Store messages durably even when a push cannot be sent.
Push and synchronization
The app fetches full messages after a push and catches up when reopened. Fetching is non-destructive, with stable message UUIDs and a monotonic cursor, so retries and multiple devices do not delete each other’s inbox. If push is unavailable, foreground fetching still works. A successful push response does not prove the phone displayed or read the message.
Disconnecting keeps local conversation history and stops that mailbox’s messages being accepted by the app. Remove the device route from your bridge as well. Changing the SIP identity does not transfer the old mailbox to the new account.
Verify the complete setup
Run the sample’s automated tests, then send a real SMS with the app open and with the phone locked. Reply, repeat a callback, reconnect, and test both mobile platforms you will support. Check long Unicode messages and that the intended account receives them. The README covers backups, encrypted storage, credentials, retention, queue retries and production hardening.
SessionCloud continues to receive inbound/outbound messaging configuration through its portal. See Connect the app. Teams Hosted uses its separate messaging service.