Message with Buttons

Buttons are used for capturing user actions. A user in the chat can click a button, and it will send a request to your api with the value as the command.

There are four color options to choose from when sending a button.

  1. Primary makes the button blue
  2. Default makes the button white
  3. Danger makes the button red
  4. Disabled makes the button gray and unclickable

The limit key is a way to specify how many buttons show up. If the items array of buttons is greater than the limit, the buttons will be grouped in a menu list.

The image on the right is an example of an overflow button list, or if you want all the buttons to be grouped in a menu.

To see the style options reference the

Full JSON Schemabelow.

To see the functionality reference the

Functionality Sectionbelow.

Example

Example

Example’s JSON

{
  "head": {
    "text": "I am a header",
    "sub_head": {
      "text": "I am a sub header"
    }
  },
  "body": [
    {
      "type": "actions",
      "items": [
        {
          "text": "Add",
          "value": "add",
          "style": "Primary"
        },
        {
          "text": "Update",
          "value": "update",
          "style": "Default"
        },
        {
          "text": "Delete",
          "value": "delete",
          "style": "Danger"
        },
        {
          "text": "Disabled",
          "value": "disable",
          "style": "Disabled"
        }
      ]
    }
  ]
}

Full JSON Schema

{
  "type": "object",
  "properties": {
    "head": {
      "type": "object",
      "required": ["text"],
      "properties": {
        "text": {
          "type": "string"
        },
        "style": {
          "type": "object",
          "properties": {
            "color": {
              "type": "string",
              "format": "Hex"
            },
            "bold": {
              "type": "boolean"
            },
            "italic": {
              "type": "boolean"
            }
          }
        },
        "sub_head": {
          "type": "object",
          "required": ["text"],
          "properties": {
            "text": {
              "type": "string"
            },
            "style": {
              "type": "object",
              "properties": {
                "color": {
                  "type": "string",
                  "format": "Hex"
                },
                "bold": {
                  "type": "boolean"
                },
                "italic": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      }
    },
    "body": {
      "type": "array",
      "limit": "integer",
      "items": {
        "type": "object",
        "required": ["type", "items"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["actions"]
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["text", "value", "style"],
              "properties": {
                "text": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                },
                "style": {
                  "type": "string",
                  "enum": ["Primary", "Update", "Delete", "Disabled"]
                }
              }
            }
          },
          "limit": {
            "type": "number",
            "minimum": 1,
            "exclusiveMinimum": false
          }
        }
      }
    }
  }
}

Functionality

User Actions

When a user clicks a button, a POST request with data about the button is sent to the Bot Endpoint URL you specfied in your apps dashboard. Here is an example request body.

{
  "event": "interactive_message_actions",
  "payload": {
    "accountId": "gVcjZnWWRLWvv_GtyGuaxg",
    "actionItem": {
      "text": "Add",
      "value": "add"
    },
    "channelName": "Tommy Gaessler",
    "messageId": "20190618205516496_ynICmz8_aw1",
    "original": {
      "head": {
        "sub_head": {
          "text": "I am a sub header"
        },
        "text": "I am a header"
      },
      "body": [
        {
          "type": "actions",
          "items": [
            {
              "style": "Primary",
              "text": "Add",
              "value": "add"
            },
            {
              "style": "Default",
              "text": "Update",
              "value": "update"
            },
            {
              "style": "Danger",
              "text": "Delete",
              "value": "delete"
            },
            {
              "style": "Disabled",
              "text": "Disabled",
              "value": "disable"
            }
          ]
        }
      ]
    },
    "robotJid": "v1m0yn1imztuogsxjje8fdew@xmpp.zoom.us",
    "timestamp": 1560891332219,
    "toJid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us/robot_v1m0yn1imztuogsxjje8fdew@xmpp.zoom.us",
    "userId": "KdYKjnimT4KPd8KKdQt9FQ",
    "userJid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us",
    "userName": "Tommy Gaessler"
  }
}

For more information, see the Buttons Webhook Reference.

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.