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.

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": "{\"operator\":\"310150\"}",
    "accept_time": "2020-04-24T08:02:50.179021Z"
  },
  "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:

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"
  }
}