Buttons Inside Attachment Object Spec

This is an implementation of rich message buttons inside the current attachments object found in the Rocket.Chat message object.

This document assumes that the reader already has knowledge of the current message and attachments objects.

This implementation is modeled after Slack's button implementation.

New fields will be added to the current attachments object:

• actions: (Required when the attachment contains buttons) A collection of actions to include in the attachment (slack offers many actions, including custom actions, but this spec will only describe action type = button). A maximum of 5 actions per attachment may be provided. (Array)
• button_alignment: (Optional) Buttons in the attachment will be vertical when vertical and horizontal when horizontal. Default is vertical. (String)
• temporary_buttons: (Optional) When true, upon a button being clicked all active buttons disappear. (Boolean)

The Button action object contains these fields:

• type: (Required) Must be button to tell Rocket Chat you want to render a button. (String)
• text: (Required if image_url is not used) A UTF-8 string label for this button. Be brief but descriptive and actionable. (String)
• url: (Optional) The fully qualified http or https URL to deliver users to. Invalid URLs will result in a message posted with the button omitted. If present the url will be opened in what is configured in is_webview. (String)
  • is_webview: (Required with url) If true, then the URL will open in a configurably sizable webview. If false, then it will open in an embedded web browser (chrome custom tab on Android and SFSafariViewController on IOS). (Boolean)
    • webview_height_ratio: (Optional with is_webview) Sets the height of the webview when it opens. Size options are compact, tall, full. The default is full. (String)
• image_url: (Required if text is not used) Location of an image to be rendered as the button. (String) NOTE: Not represented in the example above.
• msg: (Optional) A text message that will either be sent back into the chat window on behalf of the user or sent back to the bot. (String)
  • msg_in_chat_window: (Required with msg) Indicates where the msg is to be sent. If true then it will go into the chat window. If false then it will be sent back to the bot but not appear in the chat window. (Boolean)

Example JSON using button actions.

{
  "messages": [
    {
      "msg": "<@W1A2BC3DD> approved your travel request. Book any airline you like by continuing below.",
      "attachments": [
        {
          "title": "example button actions", 
          "actions": [
            {
              "type": "button",
              "text": "Book flights 🛫",
              "url": "https://flights.example.com/book/r123456",
              "is_webview": false
            },
            {
              "type": "button",
              "text": "Cancel travel request",
              "url": "https://requests.example.com/cancel/r123456",
              "is_webview": false
            },
            {
              "type": "button",
              "image_url": "http://www.emoji.co.uk/files/phantom-open-emojis/travel-places-phantom/12698-airplane.png",
              "url": "https://flights.example.com/book/r123456",
              "is_webview": true,
              "webview_height_ratio": "compact"
            },
            {
              "type": "button",
              "text": "Say hello?",
              "msg": "Hello.",
              "msg_in_chat_window": true
            },
          ]
        },
      ]
    },
  ]
}