Send a Rich Card Carousel Message

POST Method

The Send a Rich Card Carousel Message API sends a carousel of rich cards using RCS (Rich Communication Services). Each card in the carousel can contain media, title, and description, allowing for visually engaging and interactive messaging experiences.

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

URL	Region
`https://rcs-api.<pod>.kaleyra.io`	For North America (NA).
`https://rcs-api.<pod>.kaleyra.io`	For the 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.io`

API request to send a Rich Card Carousel Message

To send a rich card carousel message, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/messages endpoint with the following request method:

Request Format

The following is the request format to send rich card carousel message:

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/messages'\ 
--header '<api-key>: <api-key>' \
--header 'Content-Type: <content-type>' \
--data '{ 
  "from":"<from>",
  "to":["<to>"],
  "richCardCarousel" : 
  {
    "cardWidth" : "<card_width>",
    "cardContents" : [ 
	{
		 "title" : "<title>",
		 "description" : "<description>",
		 "media" : {
		 "height" : "<height>",
		 "file" : {
		 "fileUrl" : "<fileUrl>",
		 "thumbnailUrl" : "<thumbnailUrl>",
		 "contentDescription" : "<contentdescription>"
		}
		},
		"suggestions" : [ 
		{
		"action" : {
		"text" : "<text>",
		"postbackData" : "<postbackData>",
		"buttonId" : "<button_id>",
		"openUrlAction" : {
		"url" : "<url>"
		      }
		    }
		     } 
		 ]
	  	}, 
		{
		"title" : "<title>",
		"description" : "<description>",
		"suggestions" : [ 
		{
		"action" : {
		"text" : "<text>",
		"postbackData" : "<postbackData>",
		"openUrlAction" : {
		"url" : "<url>"
		}
	 	  }
		} 
		  ]
		} 
		  ]
    },
	"suggestions" : [
	{
	"reply" : {
	"text" : "<text>",
	"postbackData" : "<postbackData>",
	"buttonId" : "<buttonId>"
	}
	 }
]
  }'

Sample Request Format

The following is the sample request format that describes how to send a rich card carousel message:

curl --location --request POST 'https://rcs-api.<pod>.kaleyra.ai/v1/xxxxx6913850xxxx/rcs/messages'\
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx' \
--header 'Content-Type: application/json' \
--data '{ 
"from":"rcs-dev",
"to":["[9177XXXXX931]"],
"richCardCarousel" : {
"cardWidth" : "MEDIUM",
"cardContents" : [ 
{
"title" : " Deepavali Offer",
"description" : "Enjoy the deepavali offers",
"media" : {
"height" : "MEDIUM",
"file" : {
"fileUrl" : "https://images.pexels.com/photos/5458393/pexels-photo-54XXXXX.jpeg",
"thumbnailUrl" : "https://images.pexels.com/photos/5458393/pexels-photo-5XXXXX4.jpeg",
"contentDescription" : "Just a sample image"
	}
	},
"suggestions" : [ 
	{
"action" : {
"text" : "Details",
"postbackData" : "offer-a-details",
"buttonId" : "null",
"openUrlAction" : {
"url" : "http://www.sample.com/offer-a"
	}
	 }
	} 
 	 ]
	}, 
	{
"title" : "Offer B",
"description" : "Offer B is perfect for you",
"suggestions" : [ 
	{
"action" : {
"text" : "Details",
"postbackData" : "offer-b-details",
"openUrlAction" : {
"url" : "http://www.sample.com/offer-b"
		}
		 }
		} 
	  	]
		} 
	  	]
    },
"suggestions" : [
		{
"reply" : {
"text" : "Start Over",
"postbackData" : "my-start-over-response",
"buttonId" : "null"
		}
		}
	]
}'

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

The 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 agent, specified when the agent is created/onboarded.	rcs-dev	Yes
`to`	Array of String	List of recipients’ device addresses (100 max.), 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.	[ 9177XXXXX931]	Yes
`richCardCarousel`	JSON Object	Contains the details of the carousel of rich cards sent to the user device.	See the specific table for details.	Yes

The following table describes the different attributes used for the richCardCarousel JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`cardWidth`	String	Width of the cards in the carousel. Values: UNSPECIFIED, SMALL, MEDIUM	MEDIUM	No
`cardContents`	JSON Object	The content of the rich card.	See the specific table for details.	No

The following table describes the different attributes used for the cardContents JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`title`	String	Title of the rich card.	Deepavali offer.	Yes
`description`	String	Description text of the rich card (2000 Unicode characters max).	Enjoy the Deepavali offers.	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 (quick replies or actions).	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://images.pexels.com/photos/5458393/pexels-photo-54XXXXX.jpeg`	Yes
`thumbnailUrl`	String	Public accessible URL of the thumbnail image.	`https://images.pexels.com/photos/5458393/pexels-photo-5XXXXX4.jpeg`	No
`contentDescription`	String	Description of the media content for accessibility.	Just a sample image	No

The following table describes the different attributes used for the suggestions JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`action`	JSON Object	Contains the details of the action chip.	See the specific table for details.	Yes (if action)
`reply`	JSON Object	Contains the details of the reply chip.	See the specific table for details.	Yes (if reply)

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.	Details	Yes (if action)
`postbackData`	String	Data sent back to your system when the action chip is clicked.	offer-b-details	Yes (if action)
`button_id`	String	Unique ID used to identify the click event.	null	Optional
`openUrlAction`	JSON Object	Contains the URL to open when the action chip is clicked.	See the specific table for details.	Yes (if action)

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 reply/action)

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.	Start Over	Yes (if reply)
`postbackData`	String	Data sent back to your system when the reply chip is clicked.	my-start-over-response	Yes (if reply)
`button_id`	String	Unique ID used to identify the click event.	null	Optional

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.

Updated about 3 hours ago