RCS API - Rich Card Carousel Specification

When you need to present a user with multiple options to choose between, use a rich card carousel. Carousels string together multiple rich cards allowing users to compare items and react to each individually.

Carousels may contain a minimum of 2 and a maximum of 10 rich cards. Rich cards within carousels must conform to general rich card requirements for content and height.

JSON Array: It's an Array of Rich Cards

{ rich-card },
{ rich-card }

JSON Object: A Single Rich Card Object definition.

"title": "{Plain Text}",
"description": "{Plain Text}",
"url": "{https url of media file}",
"id": "{uploaded file-id}",
"thumbnail_url": "{https url of media file}",
"thumbnail_id": "{uploaded file-id}",
"suggestions": [
{ suggestion }

Explaination: For a Single Rich Card Object

Key/ObjectData TypeConstraintsDescription
titleStringRequiredTitle or name of the Card or Media
descriptionStringOptionalDescriptive text to follow in the Card
urlStringOptionalPublicly accessible HTTPS hosted URL for the Media File. Can't be used with id
idStringOptionalPre-Uploaded File-ID. Its alternate way to add media to card. Can't be used with url
thumbnail_urlStringOptionalPublicly accessible HTTPS hosted URL for a thubmnail image to be used in against the original larger Media File. Can't be used with thumbnail_id
thumbnail_idStringOptionalPre-Uploaded File-ID. Its alternate way to add thumbnail image to card. Can't be used with thumbnail_url
suggestionsArrayOptionalArray of suggestions. Each card may have one or more suggested actions that the user can interact with.

Read more....


  • A Rich Card Carousel may have 2-10 Rich Cards.
  • A Rich Card must have a media file either using HTTPS Public URL or through uploaded File ID.
  • A Rich Card may have maximum of 4 suggested actions or suggested replies. Suggestions are optional.
  • A card can't contain a combination of suggested actions and suggested replies on a single card.
  • The maximum size of a rich card payload is 250 KB.

Card Height

Cards expand vertically to fit their contents. Rich cards have a minimum height of 112 DP and a maximum height of 344 DP. If the contents of a card are not large enough to fill the minimum card height, the card expands and fills the extra height with whitespace.

Media in rich cards must fit one of three heights:

  • Short: 112 DP
  • Medium: 168 DP
  • Tall: 264 DP

If the media doesn't fit the dimensions within the card given the selected height, the media preview is chosen by zooming and cropping the media.


In a carousel, however, the height of the first few cards defines the height of all the cards in the carousel, and card height affects title, description, and suggestion truncation.

If a device can't display all elements of a card because of display constraints or card height, RBM truncates the card until it can display on the device, using the following logic:

  • Reduce the description to one line.
  • Reduce the title to one line.
  • Omit suggestions that don't fit in the card, starting from the end of the defined list.
  • Omit the description.
  • Omit the title.

To avoid truncation, keep titles and descriptions as short as possible. For tall media, use either a title and description or one suggestion. For medium media, use up to two suggestions. For short media, use up to three suggestions. To fit four suggestions, don't include media in the card.

Keep cards roughly equivalent in terms of content sizing and length, and if necessary, front-load the carousel with larger cards to avoid truncation in following cards.