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 the initial types we intend to implement 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 a type field:
-
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.
This document will describe several payload types. Using the payload.type method to describe a rich message should be very extensible and lead to many more potential types moving forward.
Types that are described in more detail below include:
-
image: An image only. -
horizontal_buttons: An array of button objects to be displayed horizontally on the screen. -
vertical_buttons: An array of button objects to be displayed vertically on the screen. -
generic_template: A basic rich message layout that can include any or all of title, text body, image, link and buttons
Example JSON of a simple image only message showing the use of the payload field:
{
"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 the rich message types we intend to implement as a starting point. Our full survey of rich message types can be found here
| Rich Message Feature |
|---|
| Buttons |
| Generic Template |
| 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.
So far we've seen four types of actions that occur on click of buttons:
- Send a message into the chat window ("type": "postback")
- Send a message back to the bot but do not display it in the chat window ("type": "postback")
- Open up a new web page via a url ("type": "url")
- A configurably sizable webview in front of the chat window. ("type": "web_view") See Integrated Webview below.
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.
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":"vertical_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>"
},
]
},This is our basic form of rich message designed to combine various native message types. 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, or any combination of types. (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.)
The Generic Template contains these fields:
-
type: must be "generic_template" (String) -
elements: An array of element objects that describe instances of the generic template to be sent.
The Elements array contains these fields:
-
title: The title to display in the template. (String) -
subtitle: (Optional) The subtitle to display in the template. (String) -
image_url: (Optional) The URL of the image to display in the template. (String) -
default_actions: (Optional) The default action executed when the template is tapped. Accepts the same properties as URL button, except title. (Object) -
buttons: (Optional) An array of buttons to append to the template. A maximum of 3 buttons per element is supported.
"payload": {
"type":"generic_template",
"elements":[
{
"title":"<TITLE_TEXT>",
"image_url":"<IMAGE_URL_TO_DISPLAY>",
"subtitle":"<SUBTITLE_TEXT>",
"default_action": {
"type": "web_url",
"url": "<DEFAULT_URL_TO_OPEN>",
"webview_height_ratio": "<COMPACT | TALL | FULL>"
},
"buttons":["<BUTTON_OBJECT>", "<BUTTON_OBJECT>", "<BUTTON_OBJECT>" ]
},
]
}Keyboard is a type of menu that replaces the traditional keyboard, allowing a user to select from a series of options instead of typing out a request. When present it temporarily replaces the default keyboard on the mobile device with predefined reply options or actions implemented using buttons.
Here are a couple examples from Telegram and Viber:
A keyboard can be attached to any message type. To attach a keyboard to a message simply add the keyboard’s parameters to the payload JSON.
An initial implementation would vertically display an arbitrary set of buttons inside the keyboard space.
The keyboard object contains these fields:
-
buttons: Array containing all keyboard buttons by order. See buttons for buttons parameter details. -
default_height: (Optional) When true the keyboard will always be displayed with the same height as the native keyboard.When false short keyboards will be displayed with the minimal possible height. Maximal height will be native keyboard height -
bg_color: (Optional) Background color of the keyboard.
{
"payload": {
"keyboard": {
"default_height": true,
"bg_color": "#FFFFFF",
"buttons": [
"<BUTTON_OBJECT>",
"<BUTTON_OBJECT>",
"<BUTTON_OBJECT>",
"..."
]
}
}
}