Message types
This section gives you an overview of how you can structure your Messages API request for different message types and channels and see some example output.
Message types contain a number of sections including a header, body, footer, and buttons depending on the message type you are using for your communication. This structure intuitively follows how the message is rendered on the user's phone. For example, you may want to include some header text when sending an image or as part of a WhatsApp template. This is all possible with Messages API (opens in a new tab).
Not all messaging channels support all message types. For a deeper dive into message types per channel then see the channel pages documentation:
- Apple Messages for Business
- Instagram DM
- LINE (LON)
- Messenger
- MMS
- RCS
- SMS
- Viber Bots
- Viber Business Messages
Text
Send a simple text message using Messages API.
Text message types are natively supported by:
- Apple Messages for Business
- Instagram DM
- LINE (LON)
- Messenger
- MMS
- RCS
- SMS
- Viber Bots
- Viber Business Messages
Example
{
"messages": [
{
"channel": "SMS",
"content": {
"body": {
"text": "Follow the link athleete.com/event-details for more details. See you next week!",
"type": "TEXT"
}
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
]
}
]
}Output
Image
Send an image in your message.
Images are natively supported by
- Apple Messages for Business
- Instagram DM
- LINE (LON)
- Messenger
- MMS
- RCS
- Viber Bots
- Viber Business Messages
Sending an SMS with an image will render the image URL.
Example image
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"body": {
"type": "IMAGE",
"url": "http://homestore/image.png",
"text": "Spring is around the corner! Check out what we have in store for you."
}
},
"options": {
"adaptationMode": true
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
]
}
]
}Output
Image with header
Add data such as caption text inside the message header.
Images with headers are natively supported by:
- Apple Messages for Business
- Instagram DM
- LINE (LON)
- MMS
Example image with header
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"header": {
"text": "Spring is around the corner!"
},
"body": {
"type": "IMAGE",
"url": "http://homestore/image.png",
"text": "Check out what we have in store for you."
}
},
"options": {
"adaptationMode": true
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
]
}
]
}Output
Document
Send files through your chosen messaging channel.
Document message types are natively supported by:
- Apple Messages for Business
- Instagram DM
- LINE (LON)
- Messenger
- MMS
- Viber Bots
- Viber Business Messages
Channel availability and output depends on the message elements you include in your request. For example, Viber Business Messages does not support documents with filename.
If you are using a channel that does not natively support document as a message type then you can use the adaptationMode parameter as part of your API request to remove the unsupported element and deliver the message anyway without throwing an error.
Example document
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"body": {
"type": "DOCUMENT",
"url": "http://my.domain/document.pdf"
}
},
"options": {
"adaptationMode": true
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
]
}
]
}Output
Video
Send video as part of your communication.
Video message types are natively supported by:
- Apple Messages for Business
- Instagram DM
- Messenger
- MMS
- RCS
- Viber Bots
- Viber Business Messages
If you are using a channel that does not natively support videos as a message type then you can use the adaptationMode parameter as part of your API request to remove the unsupported element and deliver the message anyway without throwing an error.
Example video
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"body": {
"type": "VIDEO",
"url": "http://my.domain/video.mp4"
}
},
"options": {
"adaptationMode": true
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
]
}
]
}Output
Buttons
Add buttons to your communication to facilitate interaction.
Buttons are natively supported by:
- Apple Messages for Business
- Instagram DM
- LINE (LON)
- Messenger
- RCS
- Viber Bots
- Viber Business Messages
Viber Business Messages only supports single buttons in messages. This can be achieved by using a single button block in your request rather than multiple button blocks.
If you are using a channel that does not support buttons as a message type then you can use the adaptationMode parameter as part of your API request to remove the unsupported element and deliver the message anyway without throwing an error.
Example button
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"body": {
"text": "Thank you for joining us on Athleete Unlocked! Would you like to subscribe for future Athleete events?",
"type": "TEXT"
},
"buttons": [
{
"type": "REPLY",
"text": "Yes",
"postbackData": "true"
},
{
"type": "REPLY",
"text": "No",
"postbackData": "false"
}
]
},
"options": {
"adaptationMode": true
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
]
}
]
}Output
Contact message
The Contact message type allows users to send contact details directly to recipients, enabling them to view, message, or save contact information within their app. This feature supports seamless information sharing by allowing users to provide actionable contact details, which recipients can save or use to initiate instant communication.
Contact message types are natively supported by:
- Viber Bots
Carousel
Carousel messages allow customers to send multiple rich cards within a single message. Users can scroll horizontally through the rich cards, compare different items, and interact with individual cards by taking specific actions.
Carousel message types are natively supported by:
- Instagram DM
- Messenger
- RCS
- Viber Bots
Templates
Send messages from predefined templates.
Template message types are natively supported by:
- LINE (LON)
Message templates contain various sections including header, body, footer, and buttons. When sending template messages using the Messages API it is optional if you want to include header and button elements in your communication.
Templates with headers represent sending media in a templated message. See Templates with headers below for some example requests.
Example template
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"body": {
"1": "Jane",
"2": "Doe",
"type": "TEXT"
}
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
],
"template": {
"templateName": "account_update",
"language": "en_GB"
}
}
]
}Output
Templates with headers
Use Messages API to send template messages that contain data inside the header:
- Text
- Image
- Document
- Video
- Location
The below example shows a WhatsApp template with a document header using the Messages API.
You can also adapt the header content to include image, location, and video as needed for your communication scenario.
Example template with header
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"header": {
"url": "https://mydocument.com",
"filename": "Filename.doc",
"type": "DOCUMENT"
},
"body": {
"1": "Jane",
"2": "Doe",
"type": "TEXT"
}
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
],
"template": {
"templateName": "receipt",
"language": "en_GB"
}
}
]
}Output
Templates with buttons
Templates can also include buttons. The below example shows how you can render templates with buttons using with Messages API.
You can render the following button types:
- URL - Redirects the user to a specified URL when clicked.
- Quick reply - Provides predefined quick reply options that users can select.
- Flow - Directs the user into a predefined interactive flow.
- Copy code - Allows users to copy a specific code, such as a coupon, directly from the message.
- Catalog - Displays a product catalog, allowing users to browse through products within the interface.
- Multi-product - Showcases multiple products in a single template, providing an overview of several items simultaneously.
Example template with buttons
{
"messages": [
{
"channel": "WHATSAPP",
"content": {
"body": {
"1": "Jane",
"2": "Doe",
"type": "TEXT"
},
"buttons": [
{
"suffix": "search?q=123456",
"type": "OPEN_URL"
}
]
},
"sender": "441234567890",
"destinations": [
{
"to": "440987654321"
}
],
"template": {
"templateName": "appointment_update",
"language": "en_GB"
}
}
]
}Output
RCS templates (India only)
When communicating with customers in India, utilizing the RCS message templates is essential. This requirement aims to prevent the misuse of anti-spam regulations, however, it still allows you to leverage RCS for customer communications. Learn more about sending RCS messages in India using templates.
Stickers
Send sticker images that add personality and engagement to conversations. Stickers are typically static or animated images that can enhance user interaction, convey emotions, or emphasize branding in a fun, visual format.
Stickers are natively supported by:
- Viber Bots
Location
Location messages allow you to seamlessly share latitude and longitude coordinates, providing mode contextual and real-time communication with your users. This feature enhances your ability to send location data along with your other messaging content.
Location message types are supported by:
- Viber Bots
Location messages for WhatsApp can only be successfully delivered if the recipient has contacted the business within the last 24 hours. Otherwise, a template message (opens in a new tab) should be used.
Request location button
Use a Request location button to ask users to share their location directly through the message interface. This feature is ideal for cases where location information is necessary, such as coordinating deliveries or assisting users with location-based support. Users can select the button and share their location without manually entering their address or coordinates.
Request location buttons are natively supported by:
- RCS
