Skip to content

Proposed rich message implementation

Jump to bottom Edit New page
ear-dev edited this page May 23, 2018 · 72 revisions

This is a proposed implementation of rich message types in Rocket.chat.

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.
  • 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.
  • template: (Requires the use of a template_type field) Indicates that the layout and contents will be described in the context of a known template.
  • template_type: (Depends on template) Indicates which known template to use when constructing the layout. Currently only supports generic.

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 are the rich message types to be implemented. A survey of rich messaging in chatbots can be found here

Rich Message Features

| Buttons | Generic Template | Custom Keyboard | Carousel

Buttons

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:

  1. Send a message into the chat window on behalf of the user. ("type": "postback")
  2. Open up a new web page via a url. ("type": "url")
  3. A configurably sizable webview in front of the chat window. ("type": "web_view")

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 the webview_height_ratio field. (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 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.

Horizontal Buttons

Here are a few examples using horizontal buttons.

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>"
                    },       
                ]
            },

Vertical Buttons

Here's an example 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>"
                    },       
                ]
            },

Generic Template

This is our basic form of rich message designed to combine various message types. It can include a title, text body, image, link, buttons, or any combination of types.

The Generic Template contains these fields:

  • type: Must be "template" (String)
  • template_type: Must be "generic"
  • 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)
  • 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":"template",
  "template_type":"generic",
  "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>" ]      
    },
  ]
}

Carousel Template

A carousel is when the list of elements are displayed left to right with a slider.

The Carousel Template contains these fields:

  • type: Must be "template" (String)
  • template_type: Must be "carousel"
  • elements: An array of element objects. The elements are displayed horizontally, left to right with a slider.

"payload": {
  "type":"template",
  "template_type":"carousel",
  "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>" ]      
    },
    {
         "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>" ]      
    },
  ]
}

Custom Keyboards

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 initial implementation displays an arbitrary set of buttons vertically 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
{
    "payload": {
        "text": "Hi Peter.  Your opinion matters.  Please rate your experience below",
        "keyboard": {
            "default_height": true,
            "buttons": [
                 "<BUTTON_OBJECT>",
                  "<BUTTON_OBJECT>",
                  "<BUTTON_OBJECT>",
                  "..."
            ]
        }
    }
}
Add a custom footer
Add a custom sidebar

Clone this wiki locally