Proposed rich message implementation
This is a proposed implementation of rich message types in Rocket.chat. It's meant as a spec for how to describe in JSON format a few of the types we suggest be implemented in a first round of development. It's also meant to start a discussion with the aim of fine tuning and deciding on the best implementation.
This implementation adds a payload field to the message object described here
The payload contains these fields:
-
type: (Required) The type of content encapsulated in the payload. It is used to describe the content and indicate to the client how to layout and display the rich message.
Example JSON of a simple image only message:
{
"messages": [
{
"_id": "<message-id>",
"rid": "<room-id>",
"payload": {
"type": "image",
"image_url": "<imgage-url>",
"image_description": "This is my image!"
},
"ts": { "$date": 1480377601 },
"u": {
"_id": "<user-id>",
"username": "<username>"
},
"_updatedAt": { "$date":1480377601 },
"editedAt": { "$date": 1480377601 },
"editedBy": {
"_id": "<user-id>",
"username": "<username>"
}
},
]
}Below is a list representing a few of the rich message types we are suggesting as a way to get started. Our full survey of rich message types can be found here
| Rich Message Feature |
|---|
| Buttons |
| Generic Rich Message / with and without buttons |
| Rich Messaging Below Composer |
| Integrated Webviews |
These are clickable words or graphics possibly with styling and an image/icon associated with it. Currently Rocket.chat has command words that operates similarly in a rudimentary way. Buttons in chatbots have a wide range of styles and placements.
Buttons can be added to the payload by using the buttons array consisting of one or more button objects. The button object contains these fields:
-
type: One of these "url", "web_view", or "postback" -
title: Button title. (String) -
url: (Required with url type) This URL is opened in a mobile browser when the button is tapped. (String) -
web_url: (Required with web_view type) This URL is opened in an integrated webview. The page view is in front of the chat window and it can be a configurably sized in conjunction with thewebview_height_ratiofield. (String) -
webview_height_ratio: (Optional with web_view type) Height of the webview. Valid values: "compact", "tall", "full". Defaults to full. -
payload: _(Required with the postback type) This data will be sent back to your webhook. (String) -
image: (Optional) Url to an image to be displayed in a button.
Below are a couple horizontal buttons in Slack followed by other examples from Messenger's Quick Replies.
A horizontal button layout can be described to the client by using horizontal_buttons in the payload.type field. We can probably only support up to three horizontal buttons.
Example JSON using horizontal buttons.
"payload":{
"type":"horizontal_buttons",
"text":"What do you want to do next?",
"buttons":[
{
"type":"web_url",
"title":"<button-text>",
"web_url": "<url-to-open-in-integrated-webview>",
"webview_height_ratio": "<compact | tall | full>",
},
{
"type":"postback",
"title":"<button-text>",
"payload": "<developer-defined-payload>",
},
{
"type":"url",
"title":"<button-text>",
"url": "<url-to-open-in-mobile-browser>",
"image": "<url-to-image-displayed-in-button>"
},
]
},Here's an example from Telegram of buttons listed vertically.
A vertical button layout can be described to the client by using vertical_buttons in the payload.type field.
"payload":{
"type":"horizontal_buttons",
"text":"What do you want to do next?",
"buttons":[
{
"type":"web_url",
"title":"<button-text>",
"web_url": "<url-to-open-in-integrated-webview>",
"webview_height_ratio": "<compact | tall | full>",
},
{
"type":"postback",
"title":"<button-text>",
"payload": "<developer-defined-payload>",
},
{
"type":"url",
"title":"<button-text>",
"url": "<url-to-open-in-mobile-browser>",
"image": "<url-to-image-displayed-in-button>"
},
]
},So far we've seen four types of actions that occur on click of buttons:
- Send a message into the chat window
- Send a message back to the bot but do not display it in the chat window
- Open up a new web page via a url
- A configurably sizable webview in front of the chat window. See Integrated Webview below.
This is our basic form of rich message. It can include buttons that allow a user to send a message back in the chat, it can have an image and provides a hyperlink so the user can click and open up some web page. It generally consists of a title, text body, image, link and possibly buttons. (It is variously referred to as card or slide or attachment. We've chosen to stay away from attachment below in order to distinguish it from a file that a user may upload into a chat window.)
This is an image with a button or buttons associated with it and when the button is clicked it performs an action:
A Telegram message with audio:
A viber message with video:
Rich messages often contain multiple UI items, and how these items are referred to varies across platforms. We're using the term Embedded List for messages that contain a list of items. In the below example from Messenger the message contains an image, title, subtitle, url, three vertical buttons, and three horizontal buttons.
Messenger has a template for more elaborately displaying elements vertically than the standard list layout -- list layout being just cards/slides displayed vertically -- called list template. It has a few different layout options.
Slack uses the term attachments for its list of items in a message. For example a url or a button are attachments. How Slack builds its messages with attachments can be seen and tried out with their Message Builder.
While Viber, Kik, and Telegram also support Embedded List messages their emphasis seems to be more on using Custom Keyboards for things like buttons, images, etc. See Custom Keyboards below.
A list of cards/slides can be displayed left to right with a slider -- Facebook recommends using this only when you think the first one is very likely to be desired and the ones to the right are just possible/recommendations of things the user might be interested in.
Note: the documentation of some platforms calls vertical displays of cards/slides also a "carousel". This is called simply "list layout" in other places. We're probably better off reserving the term carousel for only the horizontal display with slider to avoid confusion.
Messenger has a number of similarly-formed pre-defined message templates for actions like Buy, Share, Call, Play Game, etc that then go to built-in follow-on actions like a checkout dialog in the case of Buy.
Telegram has a couple of these that it calls special buttons. Theirs request the user's phone number and/or location. Another Telegram example is if a message is sent with a game content type then there is a built in "play GameName" button.
One of Kik's Suggested Repsonses button options is something called Friend Picker that can be used to invite friends to a bot.
Slack has a feature called Message Menus which supports a dropdown that can be populated with predetermined actions/choices, a list of members, a list of workspaces, etc.
Of the surveyed platforms, only Slack doesn't appear to support bot content below the composer.
Kik, Telegram, and Viber have a feature called custom keyboards which is a special keyboard with predefined reply options or actions. Here are a couple examples from Telegram and Viber:
Messenger by contrast supports what it calls a Persistent Menu below the composer. An always-on menu, it follows the below pattern of a couple menu items and then "More" with an arrow to others):
The pages displayed in Messenger webviews can include a javascript SDK file, which allows the webview to access platform components/context like user profile, payments, what bot you are talking to, etc. The height of the webview when it opens is configurable:
Thus far Messenger is the only chat with this webview functionality that we've seen.
Kik
Messenger
Slack
Telegram
Viber
Microsoft's Bot Framework site has a Channel Inspector in which you can see what different bot features -- carousel, buttons, etc -- look like in different platforms.
https://chatbottle.co/ and https://botlist.co/ have a searchable list of thousands of bots. The results list the platforms in which that bot is supported. This is useful for somewhat apples-to-apples comparisons of a given bot across platforms. You can also filter the search to only give bots supported in a desired platform (filter for Kik bots for example).
A survey of elements of Viber, Messenger, and Telegram. Includes Audio and Video.
This link from last year noting what Slack is lacking in bot support still seems accurate. Namely the following are not yet supported: conversational ui alignment, webview integration, horizontal scrolling carousel, quick replies.