Carousel message

A carousel message is a message that features a number of horizontally-scrolling images or panes. You can send a carousel message by making a POST request to the /messages:send Conversation API endpoint with the following payload:

{"app_id": "{{APP_ID}}",
"recipient": "{{CONTACT_ID}}",
"message": {"carousel_message": {"cards": [{"title": "Sign up for our weekly newsletter",
"description": "Our weekly newsletter is filled with deals and extra content!",
"media_message": {"url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
},
"choices": [{"text_message": {"text": "Sign up here"
}
}
]
},
{"title": "Visit our website",
"description": "You can view your account and place orders from our convenient dashboard.",
"media_message": {"url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
},
"choices": [{"url_message": {"title": "Website",
"url": "https://www.sinch.com"
}
}
]
},
{"title": "Call our customer support line",
"description": "Our dedicated support staff can answer your questions and concerns.",
"media_message": {"url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
},
"choices": [{"call_message": {"title": "Support line",
"phone_number": "46732000000"
}
}
]
}
]
}
}
}

Card message schema

A carousel message can take the following parameters and properties. Required parameters are marked.

object (Carousel Message)

required	Array of objects (Card Message) A list of up to 10 cards.
	Array of Call (object) or Location (object) or Text (object) or URL (object) (Choice message) Optional. Outer choices on the carousel level. The number of outer choices is limited to 3.

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
SMS
Facebook Messenger
Instagram
MMS
RCS
Viber Bot
Viber Business Messages
Telegram
KakaoTalk
Apple Messages for Business
LINE
WeChat

WhatsApp doesn't natively support carousel messages and so they're transcoded and sent as text messages by Conversation API. The following image gives an example of a carousel message.

Carousel Message

SMS

There is no native support for carousels in SMS. Messages are in plain text. The following image gives an example of a carousel message.

Carousel Message

Facebook Messenger

Facebook Messenger natively supports Carousel Messages. Note the following:

The top-level choices property of the carousel message normally supports 3 choices. However, carousel messages support a maximum of 13 choices for the text_message choice type.
Cards included in the carousel message have the same limitations as Card messages sent on the Facebook Messenger channel, with the additional limitation that only a maximum of 3 choices is supported per card.

The following image gives an example of a carousel message:

Carousel Message

Instagram

Instagram natively supports carousel messages.

Note

Carousel outer choices are not supported.

The following image gives an example of a carousel message.

Carousel Message 1

Apple Messages for Business

Carousel messages are sent as a single text message with multiple attachments. Each card's information is converted to plain text and displayed below each attachment.

Supported:

Choice Message

Unsupported:

Choice Message

MMS

MMS doesn't natively support Carousel messages and so they're transcoded and sent as text messages by Conversation API.

The following image gives an example of a carousel message.

Carousel Message

RCS

RCS natively supports Carousel Messages. You can put from 1 to 10 cards in one message. Each card can consist of the elements described in the "Card Messages" section. If you send only one card, the message will be rendered as a normal Card Message. Additionally, RCS channel supports a maximum of 3 outer choices. You can put outer choices into the carousel_message.choices array field, and these choices will be rendered right after the displayed cards.

Note the following:

The height of the cards in the carousel can impact the amount of content displayed to your recipient. In some cases, the cards may be truncated if display constraints aren't met or if the content of a card does not fit within the height of the cards within the carousel. This can include description truncation, title truncation, or the removal of choices from cards.
When a mobile terminated (MT) media message is sent on the RCS channel of the Conversation API, the media located at the corresponding URL may be cached for up to 28 days. If you change the media stored at the URL, the new media may not be reflected in MT messages referencing that URL that are sent within that 28-day period. To force an update of the media cache, rename the file referenced by the URL.

The following image gives an example of a carousel message.

Carousel Message

Viber Bot

Viber Bot channel natively supports carousel messages. The following image gives an example of a carousel message.

Carousel Message

Viber Business Messages

Viber Business Messagers doesn't support natively Carousel messages and so they're transcoded and sent as text messages by Conversation API. The following image gives an example of a carousel message.

Carousel Message

The Telegram channel doesn't natively support Carousel messages. The following transcoding rules are applied to Conversation Carousel messages so they can be delivered on the Telegram channel.

All Cards are joined as a single message. For each card:

Title: Converted to text.
Description: Converted to text.
Media: Converted to clickable links.
Choices: Converted to text.

Carousel Message

KakaoTalk

KakaoTalk doesn't natively support Carousel messages and so they're transcoded and sent as text message by Conversation API.

The Carousel message as text has a maximum length of 1000 characters.

LINE

LINE channel natively supports carousel messages, which can be made up of a maximum of 10 cards in a single message.

For each card:

Image:
- Max width: 1024 pixels
- Aspect ratio of the image must be one of:
  - rectangle: 1.51:1
  - square: 1:1
Title: max characters limit: 40
Description: max characters limit: 60
Choice Buttons:
- Max of 3 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 following image gives an example of a carousel message:

Carousel Message

WeChat

The WeChat channel doesn't natively support Carousel messages. The following transcoding rules are applied to Conversation Carousel messages so they can be delivered on the WeChat channel.

All Cards are joined as a single message. For each card

Title: Converted to WeChat text.
Description: Converted to WeChat text.
Media: Converted to WeChat clickable links. Clicking the link will open media content.
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 link label in the chat Window.
Call Choices: Converted to text after removed special characters from phone numbers. WeChat app will make a choice clickable if it detects 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.