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 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.
required | Array of objects (Choice message) The number of choices is limited to 3. |
object (TextMessage) 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.
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. You can configure the following choice types:
- Text Choice
- URL Choice
- Location Choice
You can include a maximum of 3 choices in one message.
The following image gives an example of a choice message:
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
- URL Choice
- Call Choice
- Location Choice
You can send a maximum of 3 choices in one message.
The following image gives an example of a choice message.
Viber Bot
Viber Bot channel natively supports choice messages. 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
Telegram Bot channel natively supports choice messages. 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: 240
- Choice Buttons:
- Max 2 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.
