# 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](/docs/sms/resources/message-info/character-support/#long-messages).

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? |
|  --- | --- |
| Text Message | Yes, this type of message is natively supported. For example: ![Text Message](/assets/sms_text_message_isolated.a25973e4a614e65e4e41bc6ea84fd101aecba68c44b38c054094b939cbc1df50.22f24fc4.png) |
| Media Message | Yes, this type of message is natively supported. For example: ![Media Message](/assets/sms_media_message_isolated.3ef19f02d0719c6d9d73af2199653270687a24e6f12bd304a2789d2cbd1bedcc.22f24fc4.png) |
| Choice Message | No, this type of message will be converted into plaintext. For example: ![Choice Message](/assets/sms_choice_message_isolated.acaefbfa217345ab4d2ab7b113ca05e5b72b637cadb3ee080ccccc1199d07b5e.22f24fc4.png) |
| Card Message | No, this type of message will be converted into plaintext. For example: ![Card Message](/assets/sms_card_message_isolated.dda0b0c9f2aba57022e67e4e9c773782e800193ea9f60d72672bf99d29a2ca92.22f24fc4.png) |
| Carousel Message | No, this type of message will be converted into plaintext. For example: ![Carousel Message](/assets/sms_carousel_message_isolated.a79fe110df1c9d773a59161d96d0e1c060a3eb05b4baaae864f9040bf8eed72c.22f24fc4.png) |
| Location Message | Yes, this type of message is natively supported. For example: ![Location Message](/assets/sms_location_message_isolated.d65f5e2c9d06627b23018d26270cabcea52159d00bd2e4566155956358099515.22f24fc4.png) |


### 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`.


```json
{
    "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](/docs/sms/resources/message-info/character-support/#long-messages).

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.


```json
{
    "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:


```json
{
  "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:


```json
{
  "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
  }
}
```