# 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, a calendar event, request to share location or make a call. You can send a card message by making a `POST` request to the `/messages:send` Conversation API [endpoint](/docs/conversation/api-reference/conversation/messages/) with the following payload: ```json { "app_id": "{APP_ID}", "recipient": { "identified_by": { "channel_identities": [ { "channel": "{CHANNEL}", "identity": "{IDENTITY}" } ] } }, "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" } } ], "message_properties": [ { "whatsapp_header": "WhatsApp header text" } ] } } } ``` ## Card message schema A card message can take the following parameters and properties. Required parameters are marked. ```json { "$ref": "#/components/schemas/CardMessageField", "components": { "schemas": { "CallMessageField": { "description": "Message for triggering a call.", "type": "object", "title": "Call", "properties": { "call_message": { "title": "Call Message", "type": "object", "required": [ "phone_number", "title" ], "properties": { "phone_number": { "description": "Phone number in E.164 with leading +.", "type": "string", "example": "+15551231234" }, "title": { "description": "Title shown close to the phone number.\nThe title is clickable in some cases.", "type": "string", "example": "Message text" } } } } }, "Coordinates": { "type": "object", "title": "Geographic coordinates", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "description": "The latitude.", "type": "number", "format": "float" }, "longitude": { "description": "The longitude.", "type": "number", "format": "float" } } }, "LocationMessageField": { "type": "object", "description": "Message containing geographic location.", "title": "Location", "properties": { "location_message": { "title": "Location Message", "type": "object", "required": [ "coordinates", "title" ], "properties": { "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "label": { "description": "Label or name for the position.", "type": "string" }, "title": { "description": "The title is shown close to the button or link that leads to a map showing the location. The title can be clickable in some cases.", "type": "string" } } } } }, "TextMessageField": { "type": "object", "title": "Text", "description": "A message containing only text.", "properties": { "text_message": { "type": "object", "title": "Text Message", "required": [ "text" ], "properties": { "text": { "description": "The text to be sent.", "type": "string" } } } } }, "UrlMessageField": { "description": "A generic URL message.", "type": "object", "title": "URL", "properties": { "url_message": { "title": "URL Message", "type": "object", "required": [ "title", "url" ], "properties": { "title": { "description": "The title shown close to the URL. The title can be clickable in some cases.", "type": "string" }, "url": { "description": "The url to show.", "type": "string" } } } } }, "CalendarMessageField": { "description": "Message containing details about a calendar event.", "type": "object", "title": "Calendar", "properties": { "calendar_message": { "title": "Calendar message", "type": "object", "required": [ "title", "event_start", "event_end", "event_title", "fallback_url" ], "properties": { "title": { "description": "The title is shown close to the button that leads to open a user calendar.", "type": "string" }, "event_start": { "description": "The timestamp defines start of a calendar event.", "type": "string", "format": "date-time", "example": "2025-11-30T10:00:00Z" }, "event_end": { "description": "The timestamp defines end of a calendar event.", "type": "string", "format": "date-time", "example": "2025-11-30T11:00:00Z" }, "event_title": { "description": "Title of a calendar event.", "type": "string" }, "event_description": { "description": "Description of a calendar event.", "type": "string" }, "fallback_url": { "description": "The URL that is opened when the user cannot open a calendar event directly or channel does not have support for this type.", "type": "string" } } } } }, "ShareLocationMessageField": { "description": "Message requesting location from a user.", "type": "object", "title": "Request location", "properties": { "share_location_message": { "title": "Share Location Message", "type": "object", "required": [ "title", "fallback_url" ], "properties": { "title": { "description": "The title is shown close to the button that leads to open a map to share a location.", "type": "string" }, "fallback_url": { "description": "The URL that is opened when channel does not have support for this type.", "type": "string" } } } } }, "choiceTypes": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CallMessageField" }, { "$ref": "#/components/schemas/LocationMessageField" }, { "$ref": "#/components/schemas/TextMessageField" }, { "$ref": "#/components/schemas/UrlMessageField" }, { "$ref": "#/components/schemas/CalendarMessageField" }, { "$ref": "#/components/schemas/ShareLocationMessageField" } ] }, "DisplayMode": { "description": "Controls the display behavior of a choice.", "type": "string", "x-enumDescriptions": { "DISPLAY_MODE_UNSPECIFIED": "Default. Transient — choice disappears when new messages arrive.", "PERSISTENT": "Persistent — choice remains visible in the message bubble." }, "enum": [ "DISPLAY_MODE_UNSPECIFIED", "PERSISTENT" ] }, "choiceCommonProps": { "type": "object", "properties": { "postback_data": { "description": "An optional field. This data will be returned in the ChoiceResponseMessage. The default is message_id_{text, title}." }, "display_mode": { "$ref": "#/components/schemas/DisplayMode" } } }, "Choice": { "description": "A choice is an action the user can take such as buttons for quick replies or other call to actions.", "type": "object", "title": "Choice message", "allOf": [ { "$ref": "#/components/schemas/choiceTypes" }, { "$ref": "#/components/schemas/choiceCommonProps" } ] }, "CardHeight": { "description": "You can set the desired size of the card in the message.", "type": "string", "x-enumDescriptions": { "UNSPECIFIED_HEIGHT": "The height of the card is unspecified.", "SHORT": "The shortest card height.", "MEDIUM": "Medium card height.", "TALL": "The tallest card height." }, "enum": [ "UNSPECIFIED_HEIGHT", "SHORT", "MEDIUM", "TALL" ] }, "MediaProperties": { "title": "Media Properties", "type": "object", "required": [ "url" ], "properties": { "thumbnail_url": { "type": "string", "description": "An optional parameter. Will be used where it is natively supported." }, "url": { "description": "Url to the media file.", "type": "string" }, "filename_override": { "description": "Overrides the media file name.", "type": "string" } } }, "CardMessage": { "description": "Message containing text, media and choices.", "title": "Card Message", "type": "object", "properties": { "choices": { "description": "You may include choices in your Card Message. The number of choices is limited to 10.", "type": "array", "items": { "$ref": "#/components/schemas/Choice" } }, "description": { "description": "This is an optional description field that is displayed below the title on the card.", "type": "string" }, "height": { "$ref": "#/components/schemas/CardHeight" }, "title": { "description": "The title of the card message.", "type": "string" }, "media_message": { "type": "object", "description": "A message containing a media component.", "allOf": [ { "$ref": "#/components/schemas/MediaProperties" } ] }, "message_properties": { "type": "object", "description": "Optional additional properties.", "properties": { "whatsapp_header": { "description": "Optional. Sets the header for the footer of a WhatsApp reply button message, if there is no media in the message. Ignored for other channels. Ignored if not transcoded to a native WhatsApp message with reply buttons.", "type": "string" } } } } }, "CardMessageField": { "description": "Field containing a Card Message", "type": "object", "title": "Card", "properties": { "card_message": { "$ref": "#/components/schemas/CardMessage" } } } } } } ``` 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](#whatsapp) - [SMS](#sms) - [Facebook Messenger](#facebook-messenger) - [Instagram](#instagram) - [MMS](#mms) - [RCS](#rcs) - [Viber Business Messages](#viber-business-messages) - [Telegram](#telegram) - [KakaoTalk](#kakaotalk) - [LINE](#line) - [WeChat](#wechat) ## WhatsApp 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. The `whatsapp_header` property of the `message_properties` parameter can be used to add a header which can have up to 60 characters. This property is only used if the card message is transcoded to a native quick reply button message and there is no media in the message. Media support in CardMessage: table thead tr th Media Type th Supported as Attachment? th Caption/Text Support? tbody tr td b Image td Yes td Yes tr td b Video td Yes td Yes tr td b Document td Yes td Yes tr td b Audio td Yes td No tr td b Sticker td Yes td No - **Important:** Audio and sticker media do **not** support captions or rich previews via the WhatsApp Business API. They are sent **without any additional text** even when used inside a Card. - **Important:** Media Message filename_override field is only supported by documents. The following image gives an example of a card message. ![Card Message](/assets/whatsapp_card_message.71d5c185cbe3fef84e2161ca3d87233c7f744cefefd604d3d58e3e52fceae1d0.3a8dbadf.png) The following image gives an example of a card message sent using the Cloud API: ![Single Choice Url Card Message](/assets/whatsapp_single_choice_url_card_message.a8e7a5400dbf6304c78298d3f9ebfaa414586afa9dd3a3cfd847eb5bb3a936be.3a8dbadf.png) ## SMS Note: If you are sending messages on the SMS channel and you haven't set a [default originator](/docs/conversation/channel-support/sms/best-practices#international-considerations-for-the-sms-service-plan) in the Sinch Build Dashboard, ensure you include the [`SMS_SENDER` property](/docs/conversation/channel-support/sms/properties) in your API call. 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](/assets/sms_card_message.c514d5b7df3065cde80e06806508b34180f771a1333114f12edcdc3891f44a20.22f24fc4.png) ## 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](/docs/conversation/message-types/choice-message/#messenger). The following image gives an example of a card message: ![Card Message](/assets/messenger_card_message.78ca336e049552948afeeda4ec145c3fe747cac5841787ec59e3a7ce23fdd28b.46a24e6c.png) ## 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](/assets/instagram_card_message.bbbc7e32262fa298511ad322c05cdcc0d27913940a065e8dac44a6ad01acf11c.01afcbcc.png) ## 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](/docs/mms/bestpractices) if you use the [MMS_STRICT_VALIDATION](/docs/conversation/channel-support/mms/properties) 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](/assets/mms_card_message.d130de02620894e5c3625ab13988c799d0de93fc11d5023fe8accdd5e45b8ea1.88839cbf.png) ## RCS RCS natively supports card messages. Note the following: - The `title` of an RCS card can include a maximum of 200 characters. Special characters, including emojis and multi-byte characters, may count as 2 or more characters. - The `description` of an RCS card can include a maximum of 2000 characters. - The media message included in the card should point to an image or a video. For information and best practices on the kinds of media to include in cards on RCS messages, see [our article on Rich Cards](https://community.sinch.com/t5/RCS/What-are-Rich-Cards/ta-p/16576). - 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. - [Specifying `filename_override`](/docs/conversation/api-reference/conversation/messages/messages_sendmessage#messages/messages_sendmessage/t=request&path=message&oneof=0/card_message/media_message/filename_override) is not supported for RCS media messages. The following image gives an example of a card message: ![Card Message With URL Choice](/assets/rcs_card_message.2d457f0a4b6bb520453c5328255822ce784b4f23f7a517bf85e4476edff76f9f.94cf44a2.png) ## 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](/assets/viberbm_card_message.10da108e67bdc670b4f6e758ed44adbbe4895ec93fd0c10b08ca889c41006880.c734a361.png) ## Telegram 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**](/docs/conversation/channel-support/telegram/markdown) for more information. The following image gives an example of a card message: ![Card Message](/assets/telegram_android_cardmessage.ea674b9d57dc8c0dec0df964b8e2f05c5bcf2e949658d9ab123a7e4adcf41939.22cfd7e9.png) ## 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. ## 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](/assets/line_card.b3f828d4334f6cb1a22e4b4ab672a8181fed014a60578db68cd3053606969467.7a4a72d5.jpg) ## 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. ![Text Choices](/assets/wechat_choice.62d8adddd1fa73d33f73f0c8b9eb357b25a5eeca13cbafb56909de9dc86ea946.5b7624f8.png) - 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. ![Choices](/assets/wechat_card.954e427d2b1cb4db2c68505a0783d2935baaf8fd168ecb2b8f9ff5e9fd5ede91.5b7624f8.png)