Send a Rich Card Carousel Message with Chiplist
POST Method
The Send a Rich Card Carousel Message with Chiplist API sends a rich card carousel message using RCS, enhanced with a chiplist (interactive reply buttons). Each card in the carousel includes media, title, description, and suggestions (actions or replies). The chiplist provides additional quick-reply options for user engagement.
Prerequisites
- After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
- Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
- Before sending the RCS, you must configure the RCS channel in the Kaleyra platform. To configure the RCS channel in your account, please contact your local Kaleyra representative.
- You must have an approved AgentID or a specific number to be used as AgentID.
Base URL
https://rcs-api.<pod>.kaleyra.ai
- For North America (NA).
https://rcs-api.<pod>.kaleyra.io
- For rest of the world.
API Domain and Value
api_domain | Value |
---|---|
IN pod | https://rcs-api.in.kaleyra.io |
NA pod | https://rcs-api.na.kaleyra.ai |
API request to send a Rich Card Carousel Message with Chiplist
To send a rich card carousel message with chiplist, use the https://rcs-api.<pod>.kaleyra.ai/v1/<sid>/rcs/messages
endpoint with the following request method:
The following is the request format to send a rich card carousel message with chiplist:
curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/messages'\
--header 'Content-Type:<Content-Type>' \
--header 'api-key: <api-key>' \
--data {
"from": "<from>",
"to": ["<to>"],
"richCardCarousel": {
"cardWidth": "<cardWidth>",
"cardContents": [
{
"title": "<title>",
"description": "<description>",
"media": {
"height": "<height>",
"file": {
"fileUrl": "<fileUrl>",
"thumbnailUrl": "<thumbnailUrl>",
"contentDescription": "<contentDescription>"
}
}
}
]
},
"suggestions": [
{
"action": {
"text": "<actionText>",
"postbackData": "<postbackData>",
"buttonId": "<buttonId>",
"openUrlAction": {
"url": "<openUrl>"
}
}
},
{
"action": {
"text": "<actionText>",
"postbackData": "<postbackData>",
"buttonId": "<buttonId>",
"createCalendarEventAction": {
"startTime": "<startTime>",
"endTime": "<endTime>",
"title": "<eventTitle>",
"description": "<eventDescription>"
}
}
},
{
"action": {
"text": "<actionText>",
"postbackData": "<postbackData>",
"buttonId": "<buttonId>",
"askLocationAction": {}
}
},
{
"action": {
"text": "<actionText>",
"postbackData": "<postbackData>",
"buttonId": "<buttonId>",
"dialAction": {
"phoneNumber": "<phoneNumber>"
}
}
},
{
"action": {
"text": "<actionText>",
"postbackData": "<postbackData>",
"buttonId": "<buttonId>",
"viewLocationAction": {
"label": "<locationLabel>",
"latLng": {
"latitude": <latitude>,
"longitude": <longitude>
}
}
}
},
{
"action": {
"text": "<actionText>",
"postbackData": "<postbackData>",
"buttonId": "<buttonId>",
"viewLocationAction": {
"query": "<locationQuery>"
}
}
}
]
}
The following is the sample request format to send a rich card carousel message with chiplist:
curl --location --request POST 'https://rcs-api.na.kaleyra.ai/v1/xxxxx6913850xxxx/rcs/messages'\
--header 'Content-Type: application/json'\
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx'\
--data {
"from":"rcs-dev",
"to": ["[9191588XXXXX]"
],
"richCardCarousel":{
"cardWidth":"MEDIUM",
"cardContents":[
{
"title":"🎥 Tata Play Binge: 13 OTT Apps",
"description":"Choose any 3 apps + 10 complimentary.\nWatch on 4 devices: TV, Laptop & Mobile.\nIncludes Prime, Hotstar, Zee5 & more.",
"media":{
"height":"MEDIUM",
"file":{
"fileUrl":"https://i.pinimg.com/736x/2e/8c/ca/2e8cca9a565117d681ae29404cdba220.jpg",
"thumbnailUrl":"https://i.pinimg.com/736x/2e/8c/ca/2e8cca9a565117d681ae29404cdba220.jpg",
"contentDescription":"Tata Play 13 OTT App Pack"
}
},
"suggestions":[
{
"action":{
"text":"Explore Now!",
"postbackData":"13_plans",
"openUrlAction":{
"url":"https://manageapps.tataplaybinge.com/manage-app/check-value-plan/choose-plan"
}
}
},
{
"reply":{
"text":"Choose Your Apps",
"postbackData":"choose_13_apps"
}
}
]
},
{
"title":"🎥 Tata Play Binge: 13 OTT Apps",
"description":"Choose any 3 apps + 10 complimentary.\nWatch on 4 devices: TV, Laptop & Mobile.\nIncludes Prime, Hotstar, Zee5 & more.",
"media":{
"height":"MEDIUM",
"file":{
"fileUrl":"https://i.pinimg.com/736x/ec/80/a6/ec80a6378f9b21d149bdacbba282f584.jpg",
"thumbnailUrl":"https://i.pinimg.com/736x/ec/80/a6/ec80a6378f9b21d149bdacbba282f584.jpg",
"contentDescription":"Tata Play 16 OTT App Pack"
}
},
"suggestions":[
{
"action":{
"text":"Explore Now!",
"postbackData":"16_plans",
"openUrlAction":{
"url":"https://manageapps.tataplaybinge.com/manage-app/check-value-plan/choose-plan"
}
}
},
{
"reply":{
"text":"Choose Your Apps",
"postbackData":"choose_13_apps"
}
}
]
},
{
"title":"📺 Tata Play Binge: 16 OTT Apps",
"description":"Pick any 6 apps + 10 complimentary.\nWatch on 4 devices.\nIncludes Prime, AppleTV, Lionsgate, BBCPlayer.",
"media":{
"height":"MEDIUM",
"file":{
"fileUrl":"https://i.pinimg.com/736x/93/c5/1b/93c51bc541036930a6e91894879691d8.jpg",
"thumbnailUrl":"https://i.pinimg.com/736x/93/c5/1b/93c51bc541036930a6e91894879691d8.jpg",
"contentDescription":"Tata Play 16 OTT App Pack"
}
},
"suggestions":[
{
"action":{
"text":"Explore Now!",
"postbackData":"16_plans",
"openUrlAction":{
"url":"https://manageapps.tataplaybinge.com/manage-app/check-value-plan/choose-plan"
}
}
},
{
"reply":{
"text":"Choose Your Apps",
"postbackData":"choose_16_apps"
}
}
]
},
{
"title":"👑 Tata Play Binge: 32 OTT Apps",
"description":"Get all 32 apps in one pack.\nStream on 4 devices.\nIncludes Prime, AppleTV, BBCPlayer, FanCode, etc.",
"media":{
"height":"MEDIUM",
"file":{
"fileUrl":"https://i.pinimg.com/736x/8e/74/f3/8e74f3570b2a8960f6314d7881bc2afa.jpg",
"thumbnailUrl":"https://i.pinimg.com/736x/8e/74/f3/8e74f3570b2a8960f6314d7881bc2afa.jpg",
"contentDescription":"Tata Play 32 OTT App Pack"
}
},
"suggestions":[
{
"action":{
"text":"Explore Now!",
"postbackData":"32_plans",
"openUrlAction":{
"url":"https://manageapps.tataplaybinge.com/manage-app/check-value-plan/choose-plan"
}
}
},
{
"reply":{
"text":"Choose Your Apps",
"postbackData":"choose_32_apps"
}
}
]
}
]
},
"suggestions":[
{
"reply":{
"text":"Sports",
"postbackData":"more_info",
"buttonId":"01"
}
},
{
"reply":{
"text":"Movies",
"postbackData":"more_info",
"buttonId":"01"
}
},
{
"reply":{
"text":"Regional - Marathi",
"postbackData":"more_info",
"buttonId":"01"
}
},
{
"reply":{
"text":"Regional - Telugu",
"postbackData":"more_info",
"buttonId":"01"
}
},
{
"reply":{
"text":"Regional - Tamil",
"postbackData":"more_info",
"buttonId":"01"
}
}
]
}
URL Parameters and Headers
The following is the list of parameters and headers to send the outgoing message request:
Parameter/Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | xxxxx6913850xxxx | Yes |
Content-Type | String | Indicates the format of the content the API will be processing. | The only allowed value is application/JSON | Yes |
api-key | String | API key generated from kaleyra.io account. | xxxxx3b8497f58a94e84b671aca43xxxx | Yes |
Following is the list of attributes to be used in the payload to send the messages:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
from | String | The service code unique to the RCS agent, specified when the RCS agent is created or onboarded. | rcs-test | Yes |
to | Array of String | List of recipients’ device addresses (up to 100 allowed), which can either be a phone number in E.164 format prefixed with the country code without a plus sign, or a URI-like identification used to contact the user. | [9191588XXXXX] | Yes |
richCardCarousel | JSON Object | Contains the details of the carousel of rich cards sent to the user device. | See the specific table for details. | No |
The following table describes the different attributes used for the richCardCarousel
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
| String | Width of the cards in the carousel. Values: UNSPECIFIED, SMALL, MEDIUM | MEDIUM | No |
| JSON Object | Contains the content for each card in the carousel. Must be between 2 and 10 cards. | See the specific table for details. | Yes |
The following table describes the different attributes used for the content
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
title | String | Title of the rich card. | 🎥 Tata Play Binge: 13 OTT Apps | Yes |
description | String | Description text of the rich card (2000 Unicode characters max.). | Choose any 3 apps + 10 complimentary.\nWatch on 4 devices: TV, Laptop & Mobile.\nIncludes Prime, Hotstar, Zee5 & more. | Yes |
media | JSON Object | Media to be included in a rich card. | See the specific table for details. | No |
suggestions | JSON Object | List of chiplist items (action). | See the specific table for details. | No |
The following table describes the different attributes used for the media
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
height | String | Height of the media (SHORT, MEDIUM, TALL). | MEDIUM | Yes |
file | JSON Object | File message content to send to the users’ device, typically an image, audio, or a video file. | See the specific table for details. | Yes |
The following table describes the different attributes used for the file
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
fileUrl | String | Public accessible URL of the media file (image or video). | https://i.pinimg.com/736x...jpg | Yes |
thumbnailUrl | String | Public accessible URL of the thumbnail image. | "https://i.pinimg.com/736x...jpg | No |
contentDescription | String | Description of the media content for accessibility. | Tata Play 13 OTT App Pack | No |
The following table describes the different attributes used for the <suggestions>
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
reply | JSON Object | Defines a suggested reply option in an RCS message. When the end user taps the chip, the specified text is sent back to the agent as a message, and the associated postbackData is included in the response payload. | See the specific table for details. | No |
action | JSON Object | Defines a suggested action chip. When the end user taps this chip, it can trigger an event such as opening a URL, dialing a phone number, or performing another predefined action. | See the specific table for details. | No |
The following table describes the different attributes used for the reply
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
text | String | Text displayed on the reply chip. | Choose Your Apps | Yes (if reply) |
postbackData | String | Data sent back to your system when the reply chip is clicked. | choose_13_apps | Yes (if reply) |
buttonId | String | Identifier for the action button. | 01 | No |
The following table describes the different attributes used for the action
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
text | String | Text displayed on the action chip. | Explore Now! | Yes |
postbackData | String | Data sent back to your system when the action chip is clicked. | 13_plans | Yes |
buttonId | String | Identifier for the action button. | 01 | No |
openUrlAction | JSON Object | Contains the URL to be opened when the action chip is clicked. | See the specific table for details. | No |
createCalendarEventAction | JSON Object | Contains details for a calendar event. | See the specific table for details. | No |
askLocationAction | JSON Object | Contains details to trigger a location request from the user. | NA | No |
dialAction | JSON Object | Contains phone number to be dialed. | See the specific table for details. | No |
viewLocationAction | JSON Object | Contains location details. | See the specific table for details. | No |
The following table describes the different attributes used for the createCalendarEventAction
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
startTime | String | Start time of the calendar event (ISO 8601 format). | 2025-07-01T19:00:00Z | Yes (if used) |
endTime | String | End time of the calendar event (ISO 8601 format). | 2025-07-02T20:00:00Z | Yes (if used) |
title | String | Title of the calendar event. | Flight Booking | Yes (if used) |
description | String | Description of the calendar event. | Flight to Delhi | No |
The following table describes the different attributes used for the dialAction
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
phoneNumber | String | Phone number to dial when the chip is clicked. | +9111693XXXXX | Yes (if used) |
The following table describes the different attributes used for the viewLocationAction
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
label | String | Label for the location view chip. | Airport | Yes (if used) |
latLng | JSON Object | Contains the location details. | See the specific table for details. | Yes (if used) |
The following table describes the different attributes used for the latLng
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
latitude | Number | Latitude of the location. | 28.6139 | Yes (if used) |
longitude | Number | Longitude of the location. | 77.2090 | Yes (if used) |
query | String | Location search query. | New Delhi Airport | Yes (if used) |
The following table describes the different attributes used for the openUrlAction
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
url | String | A URL, as defined by RFC 2396 (4000 Unicode characters max.) | https://www.tatacommunications.com/ | Yes (if action) |
Sample Success Response
The following success message appears:
{
"recipientDetails": [
{
"to": "9191588XXXXX",
"messageId": "dc4cxxxx-xxxx-xxxx-xxxx-xxxx349a5e3d "
}
]
}
The following examples illustrate typical success responses generated during the lifecycle of a message transmitted using the messaging platform. These responses represent key stages in message delivery, including successful submission to the carrier, delivery to the recipient's device, and confirmation of message read status. Each response includes metadata such as timestamps, message identifiers, and event types, which can be used for tracking and diagnostics.
Sent
The messages that are successfully submitted from Google to the carrier.
{
"type": "SENT",
"eventId": "c8c3aa5d-1082-45a9-9f88-026c9XXXXX94",
"from": "9176739XXX02",
"to": "mmx_traffic",
"sentAt": "2025-06-16T13:46:38.929Z",
"messageId": "4543932d-c8f0-48c4-90bf-f9aXXXXXX2095f"
}
Delivered
The messages that are successfully delivered to the recipient's handset.
{
"type": "DELIVERED",
"eventId": "MxfdhMDmfXXXXXQQBlrIGcIg",
"from": "91767XXXXXX2",
"to": "mmx_traffic",
"sentAt": "2025-06-16T13:46:41.295Z",
"messageId": "4543932d-c8f0-48c4-90bf-f9aXXXXX005f"
}
Read
The messages that have been read on the recipient's handset.
{
"type": "READ",
"eventId": "MxZJragNjfT=qY4XXXXXYxcA",
"from": "917673XXXXX2",
"to": "mmx_traffic",
"sentAt": "2025-06-16T13:46:49.193Z",
"messageId": "4543932d-c8f0-48c4-90bf-f9aXXXXX005f"
}
Error
The messages that have been undelivered.
For information related to RCS error codes, see RCS Error Codes.
Updated about 8 hours ago