How to Send Rich Cards and Carousels

This guide explains how to send rich cards and carousels using the Vonage Messages API. For more details on the different types of messages and their components, see Rich cards and Carousels Types.

Send Rich Card

A rich card lets you send visually engaging messages to RCS users. Cards can include a title, text, media (such as an image or video), and up to four suggested replies or actions.

Prerequisites

Define the Rich Card Elements

Each card object must include:

  • title - The title of the card (max 200 characters)
  • text - A text description (max 2000 characters)
  • media_url - A public URL of the image or video

You can also optionally add:

  • media_height - SHORT, MEDIUM, or TALL
  • media_description - for accessibility
  • thumbnail_url - placeholder image while media loads
  • suggestions - interactive suggested replies or actions

Add the RCS Parameters

An RCS card message must include an rcs object specifying:

  • card_orientation: VERTICAL or HORIZONTAL
  • image_alignment: LEFT or RIGHT (only for horizontal cards)

Send the Message

Use the Messages API POST endpoint and include the rich card in the request body.

Here’s an example of a standalone rich card message:

{
  "to": "447700900000",
  "from": "Vonage",
  "channel": "rcs",
  "message_type": "card",
  "card": {
    "title": "Hello, world!",
    "text": "This is some text to display on the card.",
    "media_url": "https://example.com/image.jpg",
    "media_description": "Image description for accessibility purposes.",
    "media_height": "TALL",
    "thumbnail_url": "https://example.com/thumbnail.jpg",
    "media_force_refresh": false,
    "suggestions": [
      {
        "type": "suggested_reply",
        "text": "Suggestion #1",
        "postback_data": "suggestion_1"
      },
      {
        "type": "suggested_reply",
        "text": "Suggestion #2",
        "postback_data": "suggestion_2"
      }
    ]
  },
  "rcs": {
    "image_alignment": "RIGHT",
    "card_orientation": "VERTICAL"
  }
}

A rich card carousel lets you combine 2–10 cards into a single message. Each card can have its own media and suggestions.

Each card must include:

  • title - The title of the card (max 200 characters)
  • text - Text description (max 2000 characters)
  • media_url - A public URL for an image or video

Optional parameters (per card):

  • media_height - SHORT, MEDIUM, or TALL
  • media_description - for accessibility
  • thumbnail_url - shown while media loads
  • media_force_refresh - whether to force refresh
  • suggestions - up to 4 suggested replies or actions
{
 "to": "447700900000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "carousel",
 "carousel": {
   "cards": [
     {
       "title": "Card 1",
       "text": "Description for card 1",
       "media_url": "https://example.com/image1.jpg",
       "media_height": "TALL",
       "suggestions": [
         {
           "type": "reply",
           "text": "Yes",
           "postback_data": "suggestion_1"
         }
       ]
     },
     {
       "title": "Card 2",
       "text": "Description for card 2",
       "media_url": "https://example.com/image2.jpg",
       "media_height": "TALL",
       "suggestions": [
         {
           "type": "reply",
           "text": "No",
           "postback_data": "suggestion_2"
         }
       ]
     }
   ]
 },
 "rcs": {
   "card_width": "MEDIUM"
 }
}

Further information