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 aPOST request to the /messages:send Conversation API endpoint with the following payload:{- "app_id": "{{APP_ID}}",
- "recipient": {
- "contact_id": "{{CONTACT_ID}}"
}, - "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"
}
}
]
}
}
}Choice message schema
A choice message can take the following parameters and properties. Required parameters are marked.
object (Choice Message) A message containing only text. | |||||
| |||||
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:
- SMS
- Facebook Messenger
- MMS
- RCS
- Viber Bot
- Viber Business Messages
- Telegram
- KakaoTalk
- Apple Messages for Business
- LINE
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.
The following image gives an example of sending a single choice url message using the Cloud API:
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.
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):
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:
Apple Messages for Business
Choice messages are sent as a list picker if all choices are text. Otherwise, the choices are converted to plain text.
Supported:
Unsupported:
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.
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.
Viber Bot
The Viber Bot channel natively supports choice messages. The limit for thetext field of the text_message object within a choice_message is 7000 characters (the same maximum character count allowed for text messages sent on the Viber Bot channel). The following image gives an example of a choice message:
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.
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 for more information.
The following image gives an example of a choice message:
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.
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.
- 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.
