RCS Rich Cards Message Types

Rich cards allow you to send visually engaging messages through RCS by combining media, text, and user interaction elements in a single structured message.

This guide explains how to send two types of rich card messages via the Messages API:

Rich Cards

A rich card can include the following:

Each card object must contain at least the title, text, media_url, and media_height parameters to be valid. Additionally, an RCS message with a message_type of card must include an rcs object containing image_alignment and card_orientation parameters.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "card",
 "card": {
  "title": "Title text for the card",
  "text": "This is some text content to display on the card.",
  "media_url": "https://example.com/image.png",
   // rest of card object parameters (optional)
 },
 "rcs": {
  "image_alignment": "RIGHT",
  "card_orientation": "VERTICAL"
 }
}

Standalone Rich Card

A standalone rich card is a single card containing a combination of the elements described above. The structure of a standalone card is defined within a card object. The card object can contain the following properties:

  • title (String): The title text displayed on the card. Maximum length 200 characters.
  • text (String): Text content displayed on the card. Maximum length 2000 characters.
  • media_url (String): a publicly reachable URL of the media file. Recommended maximum file size of 100 MB.
  • media_height (String): defines the display height of the media for cards in vertical orientation. The selected value determines the display height in density-independent pixels. Must be one of SHORT (112 DP), MEDIUM (168 DP), or TALL (264 DP); if not specified, this defaults to SHORT.
  • media_description (String): an optional text description for the media for accessibility purposes.
  • media_force_refresh (Boolean): an optional parameter which determines whether to force the RCS client to refresh the rich card media content when the message is viewed.
  • thumbnail_url (String): an optional URL for a thumbnail image to display while the media specified in media_url parameter downloads. Maximum size of 100 kB. For optimal user experience, 50 kB or less is recommended.
  • suggestions (Array): a list of suggestion objects to include in the card. These can be suggested replies and/or suggested actions. Maximum of four. See suggestions for details of the different suggestion types.

In addition to the card object, an RCS message with a message_type of card must include an rcs parameter, which is an object containing the following parameters:

  • card_orientation (String): the orientation of the card. Can be HORIZONTAL or VERTICAL. Horizontal cards have the media displayed to the left or right of the card. Vertical cards have the media displayed at the top.
  • image_alignment (String): the alignment of the media displayed on the card, for cards in horizontal orientation. Can be LEFT or RIGHT.

An example of the JSON payload for an RCS card message can be seen below:

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

Carousels can combine multiple rich cards, allowing recipients to interact with each card individually.

Note: The maximum size of a rich card carousel payload is 250 KB.

The structure of a rich card carousel is defined within a carousel object. This object has one top-level property:

  • cards (Array): an array of rich card objects (between two and ten). The structure of these objects is the same as described for the structure of the card object for standalone rich cards. Note that cards in a carousel can only have a VERTICAL orientation.

As well as the individual cards in the carousel object being able to define (up to four) suggestions at the card level. As per the standalone card, an RCS message of type carousel can define a suggestions array as a top-level parameter, with this array containing up to eleven suggestion objects defining suggested replies and/or actions.

In addition to the required card object, an RCS message with a message_type of carousel must include an rcs parameter, which is an object containing the following parameters:

  • card_width (String): defines the width of the cards in the carousel. The selected value determines the card width in density-independent pixels. Must be one of SMALL (180 DP) or MEDIUM (296 DP).

An example of the JSON payload for a rich card carousel containing two rich cards can be seen below:

{
 "to": "447700900000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "carousel",
 "carousel": {
   "cards": [
     {
       "title": "Card Title",
       "text": "The description for card #1",
       "media_url": "https://example.com/image.jpg",
       "media_height": "TALL",
       "media_description": "Image description for accessibility purposes.",
       "thumbnail_url": "https://example.com/thumbnail.jpg",
       "media_force_refresh": false,
       "suggestions": [
         {
           "type": "reply",
           "text": "Yes",
           "postback_data": "suggestion_1"
         }
       ]
     },
     {
       "title": "Card Title",
       "text": "The description for card #2",
       "media_url": "https://example.com/image.jpg",
       "media_height": "TALL",
       "media_description": "Image description for accessibility purposes.",
       "thumbnail_url": "https://example.com/thumbnail.jpg",
       "media_force_refresh": false,
       "suggestions": [
         {
           "type": "reply",
           "text": "No",
           "postback_data": "suggestion_2"
         }
       ]
     }
   ]
 },
 "rcs": {
   "card_width": "MEDIUM"
 }
}

Code Snippets

Further Reading