RCS API - Rich Card Specification
Rich cards allow you to combine media, text, and suggestions in one message. As such, media shouldn't be the only element in a rich card, and suggested replies or suggested actions should always accompany a standalone rich card.
Type of Rich Media Contents
Following type of Rich Media Contents are supported to be sent over RBM.
| Media type | Document type | Extension |
|---|---|---|
application/pdf | ||
image/jpeg | JPEG | .jpeg, .jpg |
image/gif | GIF | .gif |
image/png | PNG | .png |
video/h263 | H263 video | .h263 |
video/m4v | M4V video | .m4v |
video/mp4 | MP4 video | .mp4 |
video/mpeg4 | MPEG-4 video | .mp4, .m4p |
video/mpeg | MPEG video | .mpeg |
video/webm | WEBM video | .webm |
Note:
- PDF files can't be used with Rich Card.
Rich Card Definition
JSON Object
{"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:
| 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 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.
Card Orientation
Vertical rich cards
- Aspect Ratio: Vertical rich cards display horizontal media at the top of the card. Horizontal media should have an aspect ratio of 2:1, 16:9, or 7:3.
- Size & Resolution: When you send media to a user, you should be respectful of the user's resources. With 2:1 Ratio Horizontal media:
- Optimal resolution for Image: 1440x720px
- Optimal resolution for Thumbnail: 770x335px
- Max Image File Size: 2 MB
- Max Video File Size: 10 MB
- Recommended Thumbnail File Size: 40-100 KB
Horizontal rich cards
- Aspect Ratio: Horizontal rich cards display vertical media on the left or right side of the card. Vertical media should have an aspect ratio of 3:4.
- Size & Resolution: When you send media to a user, you should be respectful of the user's resources. With vertical media has a 3:4 ratio:
-
Optimal resolution for Image: 768x1024px
-
Optimal resolution for Thumbnail: 250x330px
-
Max Image File Size: 2 MB
-
Max Video File Size: 10 MB
-
Recommended Thumbnail File Size: 40-100 KB
-