Inbound SMS

8x8 SMS API exposes a webhook mechanism to let you receive Inbound SMS (SMS sent to your virtual numbers) on a callback URL of your choice.
Whenever you receive inbound SMS, the 8x8 SMS platform sends a POST request to the endpoint of your choice with a JSON body containing the inbound SMS and the associated data.

Requirements

To use inbound SMS capabilities, liaise with your account manager to activate the following:

  • A virtual mobile number where your user will send their SMS
  • An inbound SMS callback URL: set the URL, where 8x8 platform should forward the inbound messages addressed to your virtual number

πŸ“˜

You can configure your callback using Webhooks Configuration API

Inbound SMS flow

  1. A user sends an SMS to one of your virtual numbers
  2. 8x8 receives the SMS on your behalf
  3. 8x8 programmatically sends the SMS to the callback URL configured for your virtual number using POST request.
  4. The POST request body, in the JSON format contains the SMS body and all associated data (UMID, source, destination, encoding, timestamp)

Retry logic

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Webhook format

Request body description

Parameter nameParameter typeDescription
namespacestringA generic namespace for incoming webhook.
Equal to SMS for inbound SMS.
eventTypestringWebhook type.
Equals to inbound_message_received for inbound SMS.
descriptionstringHuman-readable description of the incoming event
payloadobjectInbound message information, see below.

Payload object description

Parameter nameParameter typeDescription
umiduuidUnique message ID for the inbound message
subAccountIdstringId of the sub-account which owns the virtual number.
timestampstringUTC date and time when the message was received expressed in ISO 8601 format.
sourcestringOriginating address of the SMS (sender number)
destinationstringThe destination address of the SMS (virtual number)
bodystringContent of the SMS
encodingstringThe encoding used in the SMS body (GSM7 / UCS2)
smsCountintegerNumber of SMS segment in the message
priceobjectPrice information of the message, please see Price object reference for details

❗️

If the request you receive has a different structure from described in this document, please contact our support to activate the latest format for your account.

Sample inbound SMS callback body:

{
  "namespace": "SMS",
  "eventType": "inbound_message_received",
  "description": "SMS inbound message",
  "payload": {
    "umid": "9e09ac86-bd74-5465-851d-1eb5a5fdbb9a",
    "subAccountId": "SubAccount-1",
    "timestamp": "2016-01-01T14:34:56.017Z",
    "source": "+6581968289",
    "destination": "+4534735477",
    "body": "Test MO message",
    "encoding": "GSM7",
    "smsCount": 2,
    "price": {
      "total": 0.0446592,
      "perSms": 0.0446592,
      "currency": "EUR"
    }
  }
}