# 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, 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. 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 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 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 four choice types: - Text Choice (text length limit is 25 characters) - URL Choice (title length limit is 25 characters, url length limit is 2048 characters) - Call Choice (title length limit is 25 characters) - Location Choice (title length limit is 25 characters, label length limit is 1000 characters) The following image gives an example of a choice message. ![Choice Message](/assets/rcs_choice_message.901cc92dbb028b94ed932abefad48bbf572d86cecb5f6f5984f0b2101c6679f2.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)