RCS channel message support
The RCS channel of the Conversation API supports some message types natively and transcodes others.
Sending Messages
Some rich messages are natively supported by RCS channel while others must be transcoded. The following sections demonstrate the mapping between the Conversation API generic message format and the way RCS renders the messages on mobile devices.
Text Messages
The RCS channel natively supports text messages. You can include a maximum of 2000 characters in the text message. The following image gives an example of a 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 Messages
RCS channel natively supports Media Messages. Send a media message by specifying the URL to the media. Conversation API will automatically detect what type of RCS message to use - image or video.
Note:
When a mobile terminated (MT) media message is sent on the RCS channel of the Conversation API, the media located at the corresponding URL may be cached for up to 28 days. If you change the media stored at the URL, the new media may not be reflected in MT messages referencing that URL that are sent within that 28-day period. To force an update of the media cache, rename the file referenced by the URL.
The following image gives an example of a 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 Messages
RCS channel natively supports Choice Messages. You can configure a choice message from the following four choice types:
- Text Choice (text length limit is 25 characters)
- URL Choice (title length limit is 25 characters, url length limit is 2048 characters)
- Call Choice (title length limit is 25 characters)
- Location Choice (title length limit is 25 characters, label length limit is 1000 characters)
The following image gives an example of a 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 Messages
RCS natively supports card messages that meet the following conditions:
- Maximum title length of 200 characters
- Maximum description length of 2000 characters
- Maximum of 4 choices included in the card message
Note:
Choices included in the card message have the same limitations as choices included in choice messages on the RCS channel.
- The media message included in the card should point to an image or a video
Note:
When a mobile terminated (MT) media message is sent on the RCS channel of the Conversation API, the media located at the corresponding URL may be cached for up to 28 days. If you change the media stored at the URL, the new media may not be reflected in MT messages referencing that URL that are sent within that 28-day period. To force an update of the media cache, rename the file referenced by the URL.
The following image gives an example of a 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 Messages
RCS natively supports Carousel Messages. You can put from 1 to 10 cards in one message. Each card can consist of the elements described in the "Card Messages" section. If you send only one card, the message will be rendered as a normal Card Message. Additionally, RCS channel supports a maximum of 3 outer choices. You can put outer choices into the carousel_message.choices array field, and these choices will be rendered right after the displayed cards.
Note the following:
- The height of the cards in the carousel can impact the amount of content displayed to your recipient. In some cases, the cards may be truncated if display constraints aren't met or if the content of a card does not fit within the height of the cards within the carousel. This can include description truncation, title truncation, or the removal of choices from cards.
- When a mobile terminated (MT) media message is sent on the RCS channel of the Conversation API, the media located at the corresponding URL may be cached for up to 28 days. If you change the media stored at the URL, the new media may not be reflected in MT messages referencing that URL that are sent within that 28-day period. To force an update of the media cache, rename the file referenced by the URL.
The following image gives an example of a 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 Messages
RCS channel doesn't natively support Location Messages. You can simply put your coordinates in a message body and Conversation API transcodes it into a text message with one Location Choice.
The following image gives an example of a location message.
The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.
Receiving Messages
RCS channel supports various kinds of receiving messages - text, media, location as well as quick replies.
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.
All of these are delivered by Conversation API with POST to MESSAGE_INBOUND webhook:
Example text reply message:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-01T19:52:11.495283Z",
"event_time": "2020-10-01T19:52:11.390725Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message": {
"id": "01EKJVHPW7M6E50FAN02B91CW3",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "test"
}
},
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"metadata": "",
"accept_time": "2020-10-01T19:52:11.483787Z"
}
}Example media reply message:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-01T20:05:15.031962Z",
"event_time": "2020-10-01T20:05:14.983131Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message": {
"id": "01EKJW9M3B7X131JKXM3W6025H",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://rcs-cnt.s3.amazonaws.com/9bcef194-02c6-4765-992e-d55ec16b474d/NTkyMzAyZjNkZTUyMTNlNjdkMGM1NWQx.png"
}
},
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"metadata": "",
"accept_time": "2020-10-01T20:05:15.019657Z"
}
}Example location reply message:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-01T19:57:46.142424Z",
"event_time": "2020-10-01T19:57:46.087756Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message": {
"id": "01EKJVVXQEKQ4Y12ZJSC8M0SP7",
"direction": "TO_APP",
"contact_message": {
"location_message": {
"title": "Location",
"coordinates": {
"latitude": 55.61018,
"longitude": 13.00106
},
"label": ""
}
},
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"metadata": "",
"accept_time": "2020-10-01T19:57:46.125490Z"
}
}Example quick reply message:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-01T20:09:28.535558Z",
"event_time": "2020-10-01T20:09:28.490771Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message": {
"id": "01EKJWHBNH9AHD0QQ5Z8B715MF",
"direction": "TO_APP",
"contact_message": {
"choice_response_message": {
"message_id": "01EKJWGGMA53D91CS7GTDW0BAE",
"postback_data": "Suggested Reply Text"
}
},
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"metadata": "",
"accept_time": "2020-10-01T20:09:28.518771Z"
}
}Receiving Delivery Receipts
Messages sent through RCS channel can have three statuses: DELIVERED, READ and FAILED.
In case of FAILED status you can find more information about the failure in a reason field.
Below you can see examples of all status messages.
Conversation API delivers all receipts by a POST to MESSAGE_DELIVERY webhook:
Example of DELIVERED receipt:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-01T20:09:00.810Z",
"event_time": "2020-10-01T20:09:06Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message_delivery_report": {
"message_id": "01EKJWGGMA53D91CS7GTDW0BAE",
"conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
"status": "DELIVERED",
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"metadata": ""
}
}Example of READ receipt:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-01T20:09:00.810Z",
"event_time": "2020-10-01T20:09:07Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message_delivery_report": {
"message_id": "01EKJWGGMA53D91CS7GTDW0BAE",
"conversation_id": "01EKJTF1FPKMZD1KGCXDM80N9M",
"status": "READ",
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"metadata": ""
}
}Example of FAILED receipt:
{
"app_id": "01EKHWVV2VJQEF0SA1GZFZ04RF",
"accepted_time": "2020-10-02T13:19:13.737Z",
"event_time": "2020-10-02T13:19:16Z",
"project_id": "040f9128-5bed-40bc-bab2-9436101ae77a",
"message_delivery_report": {
"message_id": "01EKMQEWT985EB0QNFA4CY17F9",
"conversation_id": "01EKMQEWVF07XH0849C05B1XK2",
"status": "FAILED",
"channel_identity": {
"channel": "RCS",
"identity": "14700000000",
"app_id": ""
},
"contact_id": "01EKJTC5PS68RZ1GHZ47441VSB",
"reason": {
"code": "RECIPIENT_NOT_REACHABLE",
"description": "The underlying channel reported: Unable to find rcs support for the given recipient"
},
"metadata": ""
}
}
