Skip to Content
Mobile SoftphonesMessagingUse your own SMS service
Mobile Softphones

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:

PurposeExampleConfigured where
Outgoing SMS gatewayhttps://YOUR_HOST/sendApp’s outgoing Custom gateway settings; direct A&A sending is also supported
Provider’s inbound webhookhttps://YOUR_HOST/webhooks/twilioSMS provider’s control panel; choose the path for your provider below
Incoming message fetch URLhttps://YOUR_HOST/inboxApp’s Incoming messages settings
Push registration URLhttps://YOUR_HOST/devicesApp’s Incoming messages settings; this endpoint is on your bridge
SessionTalk push API URLhttps://SELECTED_RELAY/byo/webservice/pushSupplied 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.

ProviderWhere to send incoming messagesVerification in the example
A&ASMS Inbound: https://YOUR_HOST/webhooks/aa/YOUR_RANDOM_SECRETPrivate random URL credential and destination-number check
TwilioNumber’s incoming-message webhook: POST https://YOUR_HOST/webhooks/twilioTwilio SDK signature, Account SID and destination
TelnyxMessaging profile webhook: https://YOUR_HOST/webhooks/telnyxEd25519 signature, fresh timestamp and destination
CustomPOST https://YOUR_HOST/webhooks/customHMAC-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.py

The 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 .envApp fieldPurpose
SERVICE_USERNAMEService usernameLogin for the bridge; initially sms-user, editable by the administrator
SERVICE_PASSWORDService passwordGenerated service password; choose Username and password in the app
SERVICE_API_TOKENAPI tokenOptional 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

  1. Disable the SIP account and enable SMS in its advanced messaging settings.
  2. Configure and save HTTPS > Custom for outgoing SMS. With the example, use https://YOUR_HOST/send, SERVICE_USERNAME as the SMS username, SERVICE_PASSWORD as the SMS password, parameter names username, password, da, ud, and success prefix OK:. A&A users can keep the direct A&A outgoing preset instead.
  3. Open Advanced SIP settings > Messaging > Incoming messages. The service URL and authentication fields are shown directly; no mailbox setup code is needed.
  4. Enter these values from your server administrator:
App fieldExample server value
Incoming message fetch URLhttps://YOUR_HOST/inbox
Push registration URLhttps://YOUR_HOST/devices
SMS numberSMS_NUMBER, including + and country code
Service authenticationUsername and password for the sample’s default setup, or API token
Service username / Service passwordSERVICE_USERNAME / SERVICE_PASSWORD from the bridge’s .env
API tokenOnly 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:

CredentialWho supplies itHow it is used
Service credentialsYour service administrator; generated/configured by the sample’s setup scriptEnter 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 tokenSessionTalk’s relay, obtained automatically by the appThe 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.

ResponseMeaning and action
200 with {"ok":true}APNs/FCM accepted the submission; this does not confirm phone delivery or reading.
400Invalid message fields; correct the payload.
401Missing, invalid, expired or invalidated push token; wait for a fresh app registration. Retain the message for fetching.
404The registered push destination is unavailable; check account/device setup.
413Request exceeds the 96 KiB limit; send a short preview and retain the full text in the inbox.
429Rate limited; retry with backoff. The limit is 60 pushes per minute per device/profile on each relay process.
502 or 503Push 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.

Last updated on