Set up Custom HTTPS messaging
Custom HTTPS supports providers with a compatible outgoing form API and incoming POST callbacks containing top-level JSON or URL-encoded form fields. A provider using a different authentication method, nested payload or media protocol needs a specific integration.
Create the connection
- Open your BYO PBX project at Provisioning > Advanced > Messaging, enable SMS and save.
- Under Incoming and outgoing SMS, open Custom HTTPS.
- Enter SMS username, SMS password, and the provider’s Outbound HTTPS URL.
- Set the outgoing username, password, destination and message field names to match the provider’s form API.
- Set Success response prefix if the provider reports acceptance in its response text. An empty prefix treats any HTTP 2xx response as accepted, including a response body that reports an error. Set a success prefix when the provider signals success or failure in its response text.
The outbound endpoint must be HTTPS, resolve to a public IPv4 address, and have no URL credentials, query string or fragment. Outgoing JSON, bearer-token authentication, extra form fields and automatic redirects are not supported by this preset.
Map incoming fields
Set these fields before saving the connection:
| Portal setting | Default field | Expected value |
|---|---|---|
| Incoming message ID field | id | Stable string ID, unique within this provider connection |
| Incoming sender field | from | International sender number or supported alphanumeric sender |
| Incoming destination field | to | The number assigned in SessionCloud, preferably with + and country code |
| Incoming text field | text | UTF-8 message text |
| Incoming timestamp field | timestamp | ISO8601 timestamp, needed when no message ID is supplied |
Names identify literal top-level fields, not paths into nested JSON. Use distinct names. If the provider has no ID, clear Incoming message ID field and configure its timestamp field. Prefer a timestamp with Z or an explicit time-zone offset. Without an ID, retries are identified by timestamp, sender, destination and text; identical messages with identical timestamps cannot be distinguished.
This is a synthetic example using the default mappings:
{
"id": "example-sms-001",
"from": "+447700900001",
"to": "+447700900002",
"text": "Example incoming message",
"timestamp": "2026-10-23T12:00:00Z"
}Use your assigned number when testing; the example numbers do not identify a working mailbox.
Configure the provider’s callback
Enable and save the connection, then copy its Webhook URL into the provider’s incoming SMS callback setting. Select HTTP POST with application/json or application/x-www-form-urlencoded as appropriate.
The generated URL includes a private token query parameter. Keep the complete URL unchanged. If your provider supports custom headers, you may instead remove that query parameter and send the credential in X-SessionTalk-Webhook-Token. The credential is the generated webhook token, not your SMS password or app setup code.
Do not remove authentication to make an incompatible provider work. A provider that cannot preserve the URL credential or send the header needs another integration method.
Assign and verify
Under Assign a number, select this connection and map the receiving number to the exact SIP username and domain used by the app. Follow Connect the app.
Test foreground receipt, locked-phone notification, tapping the notification and an outgoing reply. Redeliver the same callback ID to confirm the message appears once. See Webhook security and responses.
Custom HTTPS supports text SMS. MMS and delivery reports are not implemented. Changing field mappings or replacing the webhook credential requires updating the provider’s settings and retesting.