Skip to content
Conversation API/Channels/
/
Message support
Last updated

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 TypeNatively Supported?
Text MessageYes, this type of message is natively supported. For example:
Text Message
Media MessageYes, this type of message is natively supported. For example:
Media Message
Choice MessageNo, this type of message will be converted into plaintext. For example:
Choice Message
Card MessageNo, this type of message will be converted into plaintext. For example:
Card Message
Carousel MessageNo, this type of message will be converted into plaintext. For example:
Carousel Message
Location MessageYes, this type of message is natively supported. For example:
Location Message

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
  }
}
Previous page
Next page