Card message

A card message is a message that features a formatted card. Depending on the channel, the card can contain an image or a video. The card can contain choices to display text, a URL, a location, or make a call. You can send a card message by making a POST request to the /messages:send Conversation API endpoint with the following payload:

{"app_id": "{{APP_ID}}",
"recipient": {"contact_id": "{{CONTACT_ID}}"
},
"message": {"card_message": {"title": "Sign up for our newsletter",
"description": "Our weekly newsletter with deals and extra content!",
"media_message": {"url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
},
"choices": [{"text_message": {"text": "Sign up here"
}
}
]
}
}
}

Card message schema

A card message can take the following parameters and properties. Required parameters are marked.

object (Card Message)

Message containing text, media and choices.

	Array of Call (object) or Location (object) or Text (object) or URL (object) (Choice message) You may include choices in your Card Message. The number of choices is limited to 10.
description	string This is an optional description field that is displayed below the title on the card.
height	string (CardHeight) You can set the desired size of the card in the message. Enum: "UNSPECIFIED_HEIGHT" "SHORT" "MEDIUM" "TALL"
	object (Media message) A message containing an image media component.
title	string The title of the card message.

Note:

Not all channels support every parameter.

The following sections give examples of how card messages are rendered in each channel and specific parameter support:

WhatsApp
SMS
Facebook Messenger
Instagram
MMS
RCS
Viber Bot
Viber Business Messages
Telegram
KakaoTalk
Apple Messages for Business
LINE
WeChat

WhatsApp channel provides limited native support for card messages. Conversation API will use native quick reply buttons on WhatsApp if:

the title is no more than 1024 characters long
the description is no more than 60 characters long
the card message contains no more than three choices
each text choice is no more than 20 characters long and doesn't contain Markdown
all choices are unique within the message
postback data is no more than 229 characters long

Otherwise, your message will be transcoded as a media message with plaintext captions.

Media support in CardMessage:

image or video media will be displayed as rich content (see supported image and video types at Media Messages)
audio or sticker media will be included as plaintext link on the card due to a limitation of the WhatsApp Business API
document media has conditional support. At least one choice (that adheres to the conditions of a Choice Message) must be provided, and all choices must be text choices, in order to be displayed as rich content. Otherwise, it will be a plaintext link in the card
the caption field of the media_message object is not supported

The following image gives an example of a card message.

Card Message

The following image gives an example of a card message sent using the Cloud API:

Single Choice Url Card Message

SMS

SMS channel doesn't natively support card messages. Messages are sent in plain text. The following image gives an example of a card message.

Card Message

Facebook Messenger

Facebook Messenger natively supports Card Messages. Note the following:

The media_message property only supports images.
You can include a maximum of 80 characters in the title property.

Note:

Choices included in the card message have the same limitations as choices included in Choice message on Facebook Messenger.

The following image gives an example of a card message:

Card Message

Instagram

Instagram natively supports card messages.

Note the following:

Only image media are supported for Instagram cards.
You can include a maximum of 80 characters in the title property.

The following image gives an example of a card message.

Card Message

MMS

MMS natively supports card messages.

The title of the card message will be used as the Subject of the MMS message. The title will not be duplicated in the message body content. The maximum length of the title is 80 characters, though 40 characters and under is recommended for best deliverability.

Using media in a card message is optional. If you choose to add media, the content can be checked against the recommendations for MMS messages listed in the MMS documentation if you use the MMS_STRICT_VALIDATION flag.

In this message, you can send the following media types on MMS channel:

image: .jpg, .png (please observe that .jpg files have wider support on mobile devices than .png files)
video: .mp4, .gif, .mov
vCard (Virtual Contact File): .vcf
PDF files: .pdf

We recommend you to keep media file sizes under 1MB, as MMS providers usually use this limit.

The following image gives an example of a card message (presentation may vary by device-type/carrier):

Card Message

RCS

RCS natively supports card messages that meet the following conditions:

Maximum title length of 200 characters
Maximum description length of 2000 characters
Maximum of 4 choices included in the card message

Note:

Choices included in the card message have the same limitations as choices included in choice messages on the RCS channel.

The media message included in the card should point to an image or a video

Note:

When a mobile terminated (MT) media message is sent on the RCS channel of the Conversation API, the media located at the corresponding URL may be cached for up to 28 days. If you change the media stored at the URL, the new media may not be reflected in MT messages referencing that URL that are sent within that 28-day period. To force an update of the media cache, rename the file referenced by the URL.

The following image gives an example of a card message:

Card Message With URL Choice

Viber Bot

The Viber Bot channel natively supports card messages. When using the Viber Bot channel, the maximum number of choices that can be defined in the choices field of a card message is 4. The following image gives an example of a card message:

Card Message

Viber Business Messages

Viber Business Messages supports natively Card messages with one URL, Call, or Location choice. The media message in the Card should point to an image. The title of the choice in the Card message has a maximum length of 30 characters, longer content will be truncated.

The following image gives an example of a card message.

Card Message

The Telegram Bot channel natively supports card messages with one media content.

When sending card messages on the Telegram Bot channel, you can use Markdown syntax in the card title and description. See Telegram Bot channel Markdown support for more information.

The following image gives an example of a card message:

Card Message

KakaoTalk

KakaoTalk supports Card messages natively.

Note

Card messages on KakaoTalk only support png and jpg image media types.

Media included in the Media message will be rejected by the channel if:

the width is below 500px, or if the 'width:length' ratio is below 2:1, or above 3:4 or if the image dimension is not equal to [800px * 600px] (so called wide image)
image file format is different than JPG or PNG
file size is bigger than 500KB or for image with dimension [800px * 600px] is bigger than 2MB

The concatenated title and descritpion text of the Card message has a maximum length of:

1000 characters (if Card message doesn't contain Media message)
400 characters (if Card message contains Media message)
76 characters (if Card message contains Media message with wide image)

The title of the choice in the Card message has a maximum length of 14 characters.

The Card message can have only one choice in case Media message is a wide image.

Apple Messages for Business

Card messages are converted into a list picker if all choices are text, and are converted into a rich link message if it contains a single URL choice. Otherwise, the message can be sent with an attachment containing the media, and the card content is converted to plain text.

When converted to a rich link message, it's also possible to use a video in the url field, along with an image in the thumbnail_url field inside the card's media_message. This will allow the display of a video media with an image thumbnail.

Supported (as list picker):

Card Message

Supported (as rich link message):

Card Message

Unsupported:

Card Message

LINE

LINE channel natively supports card messages with one media content.

Image:
- Max width: 1024 pixels
- Aspect ratio of the image must be one of:
  - rectangle: 1.51:1
  - square: 1:1
Title: max characters limit: 40
Description: max characters limit: 60
Choice Buttons:
- Max of 4 buttons
- Text Message Choice, with postback data. When clicking the button, Text will appear in the chat window, invisible postback data will be sent back.
- URL Message Choice. When clicking the button, URL will be opened in the embedded browser.
- Location Message Choice. When clicking the button, Google Map will be opened in the embedded browser.
- Call Message Choice. When clicking the button, phone dial panel will be opened with prefilled number.

The following image gives an example of a card message:

Card Message

WeChat

WeChat channel doesn't natively support Card messages. The following transcoding rules are applied to Conversation Card Messages so they can be delivered on the WeChat channel.

Title: Converted to WeChat text.
Description: Converted to WeChat text.
Media: Converted to WeChat clickable links. Clicking the link will open media content.
Text Choices: Converted to WeChat clickable links. Clicking the link will send invisible postback_data back to the Conversation Callback URL. WeChat will also show link label in the chat Window.
Call Choices: Converted to text after removing special characters from phone numbers. The WeChat app will make a choice clickable if it detects a valid phone number in the message. Clicking the phone number will display options such as Make Call, Send Message, etc.
Location Choice: Converted to Map URL. Refer to Location Message type for more details.
URL Choice: Converted to normal URL.