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 buttons). A maximum of 5 actions per attachment may be provided. (Array)
• callback_id: (Required when the attachment contains interactive buttons) The provided string will act as a unique identifier for the collection of buttons within the attachment. It will be sent back to your message button action URL with each invoked action. It is key to identifying the interaction you're working with.

A little more about actions

Actions allow your users to quickly send messages from Slack directly to your app, enabling them to create tasks, comment on messages, follow-up from tickets, and more.

When an action is selected in Slack, your app will be notified with some relevant info; your app could then follow up by:

When an action is selected in Slack, your app will be notified with some relevant info; your app could then follow up by:

💬 Posting a message in the channel. 💭 Posting an ephemeral message to the user. 💬 Replying to the selected message in the thread. 👍 Adding a reaction emoji to the selected message. 📎 Adding an attachment to the selected message. 💭 Sending a direct message to the user. 📝 Opening a dialog for further information.

The potential use cases for custom actions are unbounded. Your app could generate a support ticket from a message, or file away information about an important lead, or maybe it'd let someone save the classic Toto song they just saw posted.

Two button types will be described: link buttons and interactive buttons.

Link Buttons

Link buttons are a kind of message attachment action. They're just links that look like buttons.

The Link Button action object contains these fields:

• type: (Required) Must be "button" to tell Rocket Chat you want to render a button. (String)
• text: (Required) A UTF-8 string label for this button. Be brief but descriptive and actionable. (String)
• url: (Required) The fully qualified http or https URL to deliver users to. Invalid URLs will result in a message posted with the button omitted. (String)
• imageUrl: (Optional) Location of an image to be rendered as the button. (String) NOTE: Not represented in the example above.

Example JSON using link buttons.

{
  "messages": [
    {
      "msg": "<@W1A2BC3DD> approved your travel request. Book any airline you like by continuing below.",
      "attachments": [
        {
          "actions": [
            {
              "type": "button",
              "text": "Book flights 🛫",
              "url": "https://flights.example.com/book/r123456",
              "imageUrl": "<my_image_url>"
            },
            {
              "type": "button",
              "text": "Cancel travel request",
              "url": "https://requests.example.com/cancel/r123456",
              "imageUrl": "<my_image_url>"
            },
          ]
        },
      ]
    },
  ]
}

## Interactive Buttons