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: |
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: |
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: |
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: |
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: |
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: |
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.
{
"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.
{
"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.
Note:
Please note that the media URLs included in the contact messages are valid for 7 days. After that the media is deleted from Conversation API storage.
Text message response webhook example
Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a text message response:
{
"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_identity": {
"channel": "SMS",
"identity": "FROM_NUMBER",
"app_id": ""
},
"conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
"contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
"metadata": "{\"operator\":\"310150\"}",
"accept_time": "2020-04-24T08:02:50.179021Z",
"sender_id": "",
"processing_mode": "CONVERSATION",
"injected": false
},
"message_metadata": "{\"arbitrary\": \"json object stringify as metadata\" }"
}The metadata field of the message object includes the MCC/MNC of the sender's operator, if known.
Choice message response webhook
Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a choice message response:
{
"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_identity": {
"channel": "SMS",
"identity": "FROM_NUMBER",
"app_id": ""
},
"conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
"contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
"metadata": "",
"accept_time": "2020-04-24T08:02:50.179021Z",
"sender_id": "",
"processing_mode": "CONVERSATION",
"injected": false
}
}
