RCS Channel
Conversation API provides support for RCS channel through Sinch RCS API.
Note:
If you are unfamiliar with RCS, we encourage you to visit the RCS Knowledge Base on the Sinch Community site. There, you'll find articles that answer common questions and provide context for the information detailed below.
To start using RCS through Conversation API you need to first have a Sinch RCS bot - read more.
Warning
Both Conversation API and Sinch RCS API are regional. Your Conversation API App must be created in the same region that your RCS bot is provisioned. If your Conversation API App is created in a different region than the RCS bot is provisioned, the RCS channel will report errors and you won't receive your delivery receipts.
Configuring the Conversation API and RCS integration.
You can enable the RCS integration for your Conversation API app using either the Sinch Customer Dashboard or the API.
Enabling the RCS integration using the Sinch Customer Dashboard
When enabling the RCS channel through the Sinch Customer Dashboard, select your app and click SET UP CHANNEL next to the relevant RCS channel. Then, select your configured Sender Identity from the drop-down box and confirm the integration.
You must also configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. For more information on how to do this using the Customer Dashboard, see How to add a webhook to a Conversation API app.
Enabling the RCS integration using the API
To setup the RCS integration programmatically, use the following snippet to configure the channel credentials for the app with the RCS channel:
{
"channel_credentials": [
{
"channel": "RCS",
"static_bearer": {
"claimed_identity": "{{RCS_BOT_ID}}",
"token": "{{RCS_BEARER_TOKEN}}"
}
}
]
}Replace {{RCS_BOT_ID}} with your Sinch RCS bot ID and {{RCS_BEARER_TOKEN}} with the bot's access token.
You must also configure at least one Conversation API webhook which will trigger POST callbacks to the callback URL. For more information on how to do this programmatically, click here.
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.
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
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.
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": ""
}
}
