SMS channel message support

When using an SMS channel with the Conversation API, you get the largest possible coverage at the cost of limited rich content features.

Sending messages

Generally, SMS is not considered a rich channel and, while some rich message types are natively supported, several other message types are converted into plaintext.

Note:

Long SMS messages may be split into and sent as multiple, distinct SMS messages. For more information on SMS message splitting, click here.

The following table details the mapping between the Conversation API generic message format and how SMS renders the messages on mobile devices.

Message Type Natively Supported? Special Instructions
Text Message Yes, this type of message is natively supported. For example:
Text Message

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Message Yes, this type of message is natively supported. For example:
Media Message

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Message No, this type of message will be converted into plaintext. For example:
Choice Message

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Message No, this type of message will be converted into plaintext. For example:
Card Message

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Message No, this type of message will be converted into plaintext. For example:
Carousel Message

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Message Yes, this type of message is natively supported. For example:
Location Message

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Delivery receipts

Messages sent on the SMS channel can have one of two statuses: DELIVERED or FAILED. Below is an example of a Conversation API POST to the MESSAGE_DELIVERY webhook with a DELIVERED receipt; a FAILED receipt would have a different status and reason.

Copy
Copied
{
    "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
    "accepted_time": "2022-02-07T20:01:04.598Z",
    "event_time": "2022-02-07T20:01:09.892757478Z",
    "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
    "message_delivery_report": {
        "message_id": "01FVAWD1JP5PPB3KEZCBKGN0ES",
        "conversation_id": "01FNV9VKCVZ6S6FVGKF62QBZ75",
        "status": "DELIVERED",
        "channel_identity": {
            "channel": "SMS",
            "identity": "46702571492",
            "app_id": ""
        },
        "contact_id": "01FNV9VK83AMY60JPNHZ7YE9X6",
        "metadata": "",
        "processing_mode": "CONVERSATION"
    },
    "message_metadata": "{\"sms_batch_id\":\"01FVAWD2ZDEQXF17WV6VMX0HS8\"}"
}

When sending a message on the SMS channel, the user may define the channel property SMS_MAX_NUMBER_OF_MESSAGE_PARTS, which limits the number of SMS messages that may be used to send long messages.

Note:

For more information on long messages and SMS message splitting, click here.

When this channel property is defined, the message_metadata included with the delivery receipt will detail the number of SMS messages used to send the original message, along with the SMS batch id.

Copy
Copied
{
    "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
    "accepted_time": "2022-02-07T15:00:13.843Z",
    "event_time": "2022-02-07T15:00:17.572503675Z",
    "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
    "message_delivery_report": {
        "message_id": "01FVAB65WKCWSGXKH4Z48EZCE4",
        "conversation_id": "01FNV9VKCVZ6S6FVGKF62QBZ75",
        "status": "DELIVERED",
        "channel_identity": {
            "channel": "SMS",
            "identity": "46702571492",
            "app_id": ""
        },
        "contact_id": "01FNV9VK83AMY60JPNHZ7YE9X6",
        "metadata": "",
        "processing_mode": "CONVERSATION"
    },
    "message_metadata": "{\"sms_batch_id\":\"01FVAB66G64XG510PJQZSM056M\",\"number_of_message_parts\":2}"
}

The message_metadata will also contain information about the operator that was used to deliver the message (if enabled on the account by Sinch).

Receiving messages

The SMS channel supports contact-initiated messages and choice responses.

Text message response webhook example

Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a text message response:

Copy
Copied
{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-24T08:02:50.184581Z",
  "message": {
    "id": "01E6NKBV63YG6K01ENEW7S1N80",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Hi from contact"
      }
    },
    "channel": "SMS",
    "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
    "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
    "metadata": "",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  }
}

Choice message response webhook

Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a choice message response:

Copy
Copied
{
  "app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
  "accepted_time": "2020-04-24T08:02:50.184581Z",
  "message": {
    "id": "01E6NKBV63YG6K01ENEW7S1N80",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "01EKJ2SWHGDMYA0F0F1PQJ09WQ",
        "postback_data": "postback"
      }
    },
    "channel": "SMS",
    "conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
    "contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
    "metadata": "",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  }
}
Was this page helpful?