# Choice message A choice message is a message that features a number of clickable choice buttons presented to the user. These choices can be text, a URL, a location, a calendar event, request to share location or to make a call. You can send a choice 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": { "choice_message": { "text_message": { "text": "Friendly reminder of your appointment tomorrow at 10AM. Please confirm your booking by replying below." }, "choices": [ { "text_message": { "text": "Confirm" } }, { "text_message": { "text": "Cancel" } } ], "message_properties": [ { "whatsapp_footer": "WhatsApp footer text" } ] } } } ``` ## Choice message schema A choice message can take the following parameters and properties. Required parameters are marked. ```json { "$ref": "#/components/schemas/ChoiceMessageField", "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" } ] }, "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}." } } }, "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" } ] }, "Choices": { "type": "object", "properties": { "choices": { "type": "array", "description": "The number of choices is limited to 10.", "items": { "$ref": "#/components/schemas/Choice" } } } }, "ChoiceMessagePropertiesField": { "type": "object", "title": "Properties", "description": "Additional properties for the message.", "properties": { "message_properties": { "type": "object", "properties": { "whatsapp_footer": { "description": "Optional. Sets the text for the footer of a WhatsApp reply button or URL button message. Ignored for other channels.", "type": "string" } } } } }, "ChoiceMessageField": { "description": "Message containing choices/actions.", "type": "object", "title": "Choice", "properties": { "choice_message": { "title": "Choice Message", "type": "object", "required": [ "choices" ], "allOf": [ { "description": "A message containing choices." }, { "$ref": "#/components/schemas/Choices" }, { "$ref": "#/components/schemas/TextMessageField" }, { "$ref": "#/components/schemas/ChoiceMessagePropertiesField" } ] } } } } } } ``` Note: Not all channels support every parameter. The following sections give examples of how choice 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 choice messages. Conversation API will use native quick reply buttons on WhatsApp if: - the choice message contains only text and no more than three choices - the title of the choice message is set and is no more than 1024 characters long - each text choice is no more than 20 characters long and doesn't contain markdown - the text for each choice is unique - postback data is no more than 229 characters long Otherwise, your message will be transcoded as a text message. The following images gives an example of a choice message. ![Choice Message](/assets/whatsapp_choice_message.fd3a90248602a43c7b3596002af6fb0c6b30804ff1fa81c2286edc01ce163efc.3a8dbadf.png) The following image gives an example of sending a single choice url message using the Cloud API: ![Single Choice Url Choice Message](/assets/whatsapp_single_choice_url_choice_message.de9c88ecea538451c0a52892130fcefcd2258c87558646d85b113312bac37d20.3a8dbadf.png) 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 choice message is transcoded to a native quick reply button message or a native URL button message. ## 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 doesn't natively support choice messages. Choice messages are transcoded in plain text. The following image gives an example of a choice message. ![Choices Message](/assets/sms_choice_message.6fe5ef6b590cfd952768dfde59646e1024ce85ee27ebfe08da57058b73ba296c.22f24fc4.png) ## Facebook Messenger Facebook Messenger supports choice messages natively. Note the following: - A maximum of 3 choices is supported for the following types: - URL Choice - Location Choice - Call Choice - A maximum of 13 choices is supported for the following types: - Text Choice The following images give examples of choice messages (one with 3 or fewer choices, and one with more than 3 text choices): ![Choice Message with buttons](/assets/messenger_choice_message.3b4d8401879b801babb42697800346ae2277f8d1f30daec39e3dee2b28f02766.46a24e6c.png) ![Choice Message with quick replies](/assets/messenger_choice_message_quick_replies.170ccdbf9f84c26386aea059b3707f31e2c2d70a7a37a13397541e83e81dfa7d.46a24e6c.png) ## Instagram Instagram supports choice messages natively. Note `Choice Message` will only be supported on Android and iOS Instagram’s apps. Choice message won't be rendered on a web client. Instead, users will see just the text message without the choice buttons. The following image gives an example of a choice message on an Android or iOS app: ![Choice Message](/assets/instagram_choice_message.6c3ab659f7a8f8ea999fce796a0ebda8d2e7060e557987489024a1fc7306d1f6.01afcbcc.png) ## MMS MMS doesn't natively support Choice messages therefore they're transcoded and sent as text messages by Conversation API. The following image gives an example of a choice message. ![URL Choice Message](/assets/mms_choice_message.2df09c9fdfa22a5865dfd13eaaf709ccc3f7ca1118879a88bd4a5e296d808500.88839cbf.png) ## RCS RCS channel natively supports Choice Messages. You can configure a choice message from the following choice types: - Text Choice - URL Choice - Call Choice - Location Choice - Calendar Choice - Request location Choice The following image gives an example of a choice message. ![Choice Message](/assets/rcs_choice_message.b8cac1b7fcb4c35eea8e489abbdeae529527b0f2a740a671c1b7ca263e9dd84b.94cf44a2.png) ## Viber Business Messages Viber Business Messages channel provides native support for single choice (URL, Call, or Location) choice messages. The title of the choice has a maximum length of 30 characters, longer content will be truncated. The following image gives an example of a choice message. ![URL Choice Message](/assets/viberbm_choice_message.b26688997a633e7265ebd82d815cdcfa246e239d0ce4ea90cfa545bf8f8892bf.c734a361.png) ## Telegram The Telegram Bot channel natively supports choice messages. When sending choice messages on the Telegram Bot channel, you can use Markdown syntax in the choice text. See [**Telegram Bot channel Markdown support**](/docs/conversation/channel-support/telegram/markdown) for more information. The following image gives an example of a choice message: ![Choice Message](/assets/telegram_android_choicemessage.504bf18691e37e0dbbe48691d182e71b6ed745a021b241a1873d35fde9dd585c.22cfd7e9.png) ## KakaoTalk KakaoTalk supports choice messages natively. The text of the Choice message has a maximum length of 1000 characters. The title of the choice in the Choice message has a maximum length of 14 characters. ## LINE LINE channel natively supports choice messages. The following image gives an example of a choice message. - Text: max characters limit: 160 - Choice Buttons: - Max 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. ![Choice Message](/assets/line_choice.e3fd9ef312d0e335cf241034b579257b34f5cdf5abdf1addd7f98e7250aa9f36.7a4a72d5.jpg) ## WeChat The WeChat channel doesn't natively support Choice messages. The following transcoding rules are applied to Conversation Choice Messages, so they can be delivered on the WeChat channel. - 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 the 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, opened by embedded browser. ![Choices](/assets/wechat_card.954e427d2b1cb4db2c68505a0783d2935baaf8fd168ecb2b8f9ff5e9fd5ede91.5b7624f8.png)