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.
Rich Card Carousel Definition
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/Object | Data Type | Constraints | Description |
|---|---|---|---|
title | String | Required | Title or name of the Card or Media |
description | String | Optional | Descriptive text to follow in the Card |
url | String | Optional | Publicly accessible HTTPS hosted URL for the Media File. Can't be used with id |
id | String | Optional | Pre-Uploaded File-ID. Its alternate way to add media to card. Can't be used with url |
thumbnail_url | String | Optional | Publicly 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_id | String | Optional | Pre-Uploaded File-ID. Its alternate way to add thumbnail image to card. Can't be used with thumbnail_url |
suggestions | Array | Optional | Array of suggestions. Each card may have one or more suggested actions that the user can interact with. |
Read more....
Note
- 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.
Truncation
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.