-
Notifications
You must be signed in to change notification settings - Fork 6
Proposed rich message implementation
This is a proposed implementation of rich message types in Rocket.chat.
A description of this proposed implementation can also be found in our fork of the developer-guide here.
This implementation adds a payload
field to the message object described here
The payload includes 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.
The type
field options that are described in more detail below include:
-
image
: An image only. -
buttons
: An array of button objects to be displayed either horizontally or vertically on the screen. Thebutton_layout
field can be used in conjunction withbuttons
to describe the layout (horizontal | vertical). Defaults tovertical
. -
generic
: The generic type combines various message components like title, text body, image, link, or buttons into an "element". Multiple elements can be described and displayed vertically. -
carousel
: A list of generic type elements that is displayed horizontally from left to right with a slider.
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",
"imageUrl": "<imgage-url>",
"imageDescription": "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 are the rich message types to be implemented. A survey of rich messaging in chatbots can be found here
| Buttons | Generic | Carousel | Custom Keyboard
These are clickable words or graphics possibly with styling and an image/icon associated with it.
Three types of actions can occur on click of buttons:
- Send a message into the chat window on behalf of the user. ("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")
This is an example of configurably sized webviews in front of the chat window.
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", "webView", "postback" ] -
title
: Button title. (String) -
url
: (Required with "url" type) This URL is opened in a mobile browser when the button is tapped. (String) -
webUrl
: (Required with "webView" 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 thewebviewHeightRatio
field. (String) -
webviewHeightRatio
: (Optional with "webView" type) Height of the webview. Valid values: "compact", "tall", "full". Defaults to full. -
payload
: _(Required with the postback type) This data will be posted back into the chat window on behalf of the user, which will then be sent back into the chat stream with the bot. (String) -
image
: (Optional) Url to an image to be displayed in a button.
The buttons can be rendered either horizontally or vertically using the button_layout
field in the payload.
-
button_layout
: (Optional. Depends on the inclusion of a buttons array) Describes how the buttons are to be laid out in the chat window or keyboard. Possible values:vertical
orhorizontal
.
A horizontal button layout can be described to the client by using horizontal
in the payload.button_layout field.
Example JSON using horizontal buttons.
"payload":{
"type":"buttons",
"button_layout": "horizontal",
"text":"What do you want to do next?",
"buttons":[
{
"type":"webUrl",
"title":"<button-text>",
"webUrl": "<url-to-open-in-integrated-webview>",
"webviewHeightRatio": "<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>"
},
]
},
A vertical button layout can be described to the client by using vertical
in the payload.button_layout field.
"payload":{
"type":"buttons",
"button_layout":"vertical",
"text":"What do you want to do next?",
"buttons":[
{
"type":"webUrl",
"title":"<button-text>",
"webUrl": "<url-to-open-in-integrated-webview>",
"webviewHeightRatio": "<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>"
},
]
},
The generic type combines various message components like title, text body, image, link, or buttons into an element in an elements array. When there are multiple elements the generic type displays them vertically.
This is an example of a single element.
The generic type contains these fields:
-
type
: Must be "generic" (String) -
elements
: An array of element objects. The elements are displayed vertically.
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) -
imageUrl
: (Optional) The URL of the image to display in the template. (String) -
defaultActions
: (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, rendered either vertical or horizontal using the previously describedbutton_layout
field. -
button_layout
: (Optional. Depends on the inclusion of a buttons array) Describes how the buttons are to be laid out in the chat window. Possible values:vertical
orhorizontal
.
"payload": {
"type":"generic",
"elements":[
{
"title":"<TITLE_TEXT>",
"imageUrl":"<IMAGE_URL_TO_DISPLAY>",
"subtitle":"<SUBTITLE_TEXT>",
"defaultAction": {
"type": "web_url",
"url": "<DEFAULT_URL_TO_OPEN>",
"webviewHeightRatio": "<COMPACT | TALL | FULL>"
},
"button_layout":"horizontal",
"buttons":["<BUTTON_OBJECT>", "<BUTTON_OBJECT>", "<BUTTON_OBJECT>" ]
},
]
}
Like the generic type, the carousel type combines various message components like title, text body, image, link, or buttons into an element in an elements array. When there are multiple elements, the carousel displays them left to right with a slider.
The carousel type contains these fields:
-
type
: Must be "carousel" (String) -
elements
: An array of element objects. The elements are displayed horizontally, left to right with a slider.
"payload": {
"type":"carousel",
"elements":[
{
"title":"<TITLE_TEXT>",
"imageUrl":"<IMAGE_URL_TO_DISPLAY>",
"subtitle":"<SUBTITLE_TEXT>",
"defaultAction": {
"type": "webUrl",
"url": "<DEFAULT_URL_TO_OPEN>",
"webviewHeightRatio": "<COMPACT | TALL | FULL>"
},
"button_layout":"horizontal",
"buttons":["<BUTTON_OBJECT>", "<BUTTON_OBJECT>", "<BUTTON_OBJECT>" ]
},
{
"title":"<TITLE_TEXT>",
"imageUrl":"<IMAGE_URL_TO_DISPLAY>",
"subtitle":"<SUBTITLE_TEXT>",
"defaultAction": {
"type": "webUrl",
"url": "<DEFAULT_URL_TO_OPEN>",
"webviewHeightRatio": "<COMPACT | TALL | FULL>"
},
"button_layout":"vertical",
"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.
A keyboard can be attached to any message type. To attach a keyboard to a message simply add the keyboard
parameters to the payload JSON.
The keyboard implementation will display an arbitrary set of buttons either vertically or horizontally inside the keyboard space.
The keyboard object contains these fields:
-
buttons
: Array containing all keyboard buttons by order. See buttons for buttons parameter details. -
button_layout
: (Optional. Depends on the inclusion of a buttons array) Describes how the buttons are to be laid out in the keyboard. Possible values:vertical
orhorizontal
. -
defaultHeight
: (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
{
"payload": {
"type": "image",
"imageUrl": "<imgage-url>",
"imageDescription": "Welcome!",
"keyboard": {
"defaultHeight": true,
"button_layout":"horizontal",
"buttons": [
"<BUTTON_OBJECT>",
"<BUTTON_OBJECT>",
"<BUTTON_OBJECT>",
"..."]
}
}
}