Send a Rich Card Carousel Message with Suggestion

POST Method

The Send a Rich Card Carousel Message with Suggestion API sends a rich card carousel message using RCS, where each card includes media, title, description, and interactive suggestions. Suggestions can be either actions (which open URLs) or replies (which send postback data). This format is ideal for showcasing multiple offerings with direct engagement options.

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 request to send a Rich Card Carousel Message with Suggestion

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

Request Format

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

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>" 
        } 
      } 
    } 
  ] 
}   

Sample Request Format

The following is the sample request format to send a rich card carousel message with suggestion:

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/HeadersData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier).xxxxx6913850xxxxYes
Content-TypeStringIndicates the format of the content the API will be processing.The only allowed value is application/JSONYes
api-keyStringAPI key generated from kaleyra.io account.xxxxx3b8497f58a94e84b671aca43xxxxYes

Following is the list of attributes to be used in the payload to send the messages:

ParameterData TypeDescriptionExampleMandatory?
fromStringThe service code unique to the RCS agent, specified when the RCS agent is created or onboarded.rcs-testYes
toArray of StringList 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
richCardCarouselJSON ObjectContainer for rich card content.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?

cardWidth

String

Width of the cards in the carousel. Choose one of the following options: • Small: 180 DP (fixed width) • Medium: 296 DP (fixed width)

MEDIUM

No

cardContents

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:

ParameterData TypeDescriptionExampleMandatory?
titleStringTitle of the rich card.🎥 Tata Play Binge: 13 OTT AppsYes
descriptionStringDescription 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
mediaJSON ObjectMedia to be included in a rich card.See the specific table for details.No
suggestionsJSON ObjectList of chiplist items (action).See the specific table for details.No

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

ParameterData TypeDescriptionExampleMandatory?
heightStringHeight of the media (SHORT, MEDIUM, TALL).MEDIUMYes
fileJSON ObjectFile 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:

ParameterData TypeDescriptionExampleMandatory?
fileUrlStringPublic accessible URL of the media file (image or video).https://i.pinimg.com/736x...jpgYes
thumbnailUrlStringPublic accessible URL of the thumbnail image."https://i.pinimg.com/736x...jpgNo
contentDescriptionStringDescription of the media content for accessibility.Tata Play 13 OTT App PackNo

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

ParameterData TypeDescriptionExampleMandatory?
replyJSON ObjectDefines 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
actionJSON ObjectDefines 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:

ParameterData TypeDescriptionExampleMandatory?
textStringText displayed on the reply chip.Choose Your AppsYes (if reply)
postbackDataStringData sent back to your system when the reply chip is clicked.choose_13_appsYes (if reply)

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

ParameterData TypeDescriptionExampleMandatory?
textStringText displayed on the action chip.Explore Now!Yes
postbackDataStringData sent back to your system when the action chip is clicked.13_plansYes
buttonIdStringIdentifier for the action button.01No
openUrlActionJSON ObjectContains the URL to be opened when the action chip is clicked.See the specific table for details.No
createCalendarEventActionJSON ObjectContains details for a calendar event.See the specific table for details.No
askLocationActionJSON ObjectContains details to trigger a location request from the user.NANo
dialActionJSON ObjectContains phone number to be dialed.See the specific table for details.No
viewLocationActionJSON ObjectContains location details.See the specific table for details.No

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

ParameterData TypeDescriptionExampleMandatory?
startTimeStringStart time of the calendar event (ISO 8601 format).2025-07-01T19:00:00ZYes (if used)
endTimeStringEnd time of the calendar event (ISO 8601 format).2025-07-02T20:00:00ZYes (if used)
titleStringTitle of the calendar event.Flight BookingYes (if used)
descriptionStringDescription of the calendar event.Flight to DelhiNo

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

ParameterData TypeDescriptionExampleMandatory?
phoneNumberStringPhone number to dial when the chip is clicked.+9111693XXXXXYes (if used)

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

ParameterData TypeDescriptionExampleMandatory?
labelStringLabel for the location view chip.AirportYes (if used)
latLngJSON ObjectContains 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:

ParameterData TypeDescriptionExampleMandatory?
latitudeNumberLatitude of the location.28.6139Yes (if used)
longitudeNumberLongitude of the location.77.2090Yes (if used)
queryStringLocation search query.New Delhi AirportYes (if used)

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

ParameterData TypeDescriptionExampleMandatory?
urlStringA 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.


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-026c99808674", 
  "from": "917673908652", 
  "to": "mmx_traffic", 
  "sentAt": "2025-06-16T13:46:38.929Z", 
  "messageId": "4543932d-c8f0-48c4-90bf-f9a00562095f" 
} 

Delivered

The messages that are successfully delivered to the recipient's handset.

{ 
  "type": "DELIVERED", 
  "eventId": "MxfdhMDmfQQSqKCtBlrIGcIg", 
  "from": "917673908652", 
  "to": "mmx_traffic", 
  "sentAt": "2025-06-16T13:46:41.295Z", 
  "messageId": "4543932d-c8f0-48c4-90bf-f9a00562095f" 
} 

Read

The message that has been read on the recipient's handset.

{ 
  "type": "READ", 
  "eventId": "MxZJragNjfT=qY4Yx6mlq5cA", 
  "from": "917673908652", 
  "to": "mmx_traffic", 
  "sentAt": "2025-06-16T13:46:49.193Z", 
  "messageId": "4543932d-c8f0-48c4-90bf-f9a00562095f" 
} 

Error

The messges that has been undelivered.


For information related to RCS error codes, see RCS Error Codes.






© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.