Slash Commands and UI Elements

Users can interact with Chatbots via Slash Commands and Chatbot Message UI Elements. Each user action sends a JSON representation of the action to your Chatbot’s Bot Endpoint URL.

On This Page

• Slash Commands
• UI Elements
• Event Subscriptions

Slash Commands

After a user enters a Slash Command, the Chatbot sends an HTTP POST request to the Bot Endpoint URL with a JSON payload containing all text entered following the command. This payload also contains information on the User and event, including the account, channel, timestamp, and user name.

It is highly recommended all Chatbot apps verify the Verification Token, contained in the header of this request. Unsecured Bot Endpoint URLs will leave the Chatbot app vulnerable to denial of service attacks. The verification token can be found on the Features page.

For example in the Build a Chatbot Tutorial, we have created a Slash Command named /unsplash for the Unsplash Chatbot. To use the Chatbot, a User would have to enter the command /unsplash island into Zoom Chat.

A user entering the text /unsplash island into the Zoom Chat triggers an HTTP POST request with a JSON payload containing a cmd field with the value of "island". The request would then be handled and returned in Zoom Chat as a message in the format specified by the Chatbot. In this instance, the Chatbot app would receive the command to request the third-party Unsplash API to return a photo of an “island” which is displayed as an image in Zoom Chat.

Below is an example of the request body sent to the Bot Endpoint URL:

{
  "event": "bot_notification",
  "payload": {
    "accountId": "asgVcjZnWWRLWvv_GtyGuaxg",
    "channelName": "Photos",
    "cmd": "island",
    "name": "Unsplash",
    "robotJid": "v10r4uxexurcasg-pwh8hyh7sg@xmpp.zoom.us",
    "timestamp": 1560796234686,
    "toJid": "b1c841dc7b0b4as69287e6be05c7f93f25@conference.xmpp.zoom.us",
    "userId": "KdYKjnimT4asKPd8KKdQt9FQ",
    "userJid": "kdykjnimtas4kpd8kkdqt9fq@xmpp.zoom.us",
    "userName": "Jane Dev"
  }
}

The cmd value reflects the text entered by the User after the slash command. The userName is the string value of the User’s displayed name, and channelName is the string value of the channel in which the command was sent. In this example, the User “Jane Dev” entered /unsplash island in the Zoom Chat “Photos” channel.

For more information, see the Slash Commands Webhook Reference.

UI Elements

After a user interacts with an Editable Text, Form Field, Dropdown, or Button Chatbot message UI Element, the Chatbot sends an HTTP POST request to the Bot Endpoint URL with a JSON payload containing the action. This payload also contains information on the User and event, including the account, channel, timestamp, and user name.

It is highly recommended all Chatbot apps verify the Verification Token, contained in the header of this request. Unsecured Bot Endpoint URLs will leave the Chatbot app vulnerable to denial of service attacks. The verification token can be found on the Features page.

For example in the Vote Chatbot sample app, when a user clicks on the Up Vote button in the Chatbot message it would trigger an HTTP POST request with a JSON payload containing an actionItem field with the value of { "text": "Up Vote", "value": "up-vote" }.

Below is an example of the request body sent to the Bot Endpoint URL when a user clicks on button in a Chatbot message:

{
  "event": "interactive_message_actions",
  "payload": {
    "accountId": "gVcjZnWWRLWvv_GtyGuaxg",
    "actionItem": {
      "text": "Up Vote",
      "value": "up-vote"
    },
    "channelName": "Marketing",
    "messageId": "20190827185906670_yqGXjuJ_aw1",
    "original": {
      "head": {
        "text": "Vote bot"
      },
      "body": [
        {
          "footer": "Vote by John Dev",
          "type": "section",
          "sections": [
            {
              "text": "\"Tacos for Lunch?\"",
              "type": "message"
            },
            {
              "type": "actions",
              "items": [
                {
                  "style": "Primary",
                  "text": "Up Vote",
                  "value": "up-vote"
                },
                {
                  "style": "Danger",
                  "text": "Down Vote",
                  "value": "down-vote"
                }
              ]
            }
          ]
        }
      ]
    },
    "robotJid": "v1m0ynasf1imztuosgsxjje8fdgew@xmpp.zoom.us",
    "timestamp": 1566932352415,
    "toJid": "b1c841fdc7b0b469287e6be05c7wf93f125@conference.xmpp.zoom.us",
    "userId": "kdyskjni3mt4k1pd8kksdqt9fq",
    "userJid": "kdyskjni3mt4k1pd8kksdqt9fq@xmpp.zoom.us",
    "userName": "Jane Dev"
  }
}

The actionItem value reflects the action the user took. The userName is the string value of the User’s displayed name, and channelName is the string value of the channel in which the command was sent. In this example, the User “Jane Dev” clicked on the Up Vote button in the Zoom Chat “Marketing” channel.

For more information, see the Editable Text, Form Fields, Dropdown, and Buttons Webhook References.

Event Subscriptions

Chatbots can also subscribe to events on your account just like a Webhook App.

An example of how a Chatbot could effectively use an Event Subscription is after a meeting recording has finished processing, the Chatbot would receive the event payload, and then send a Chatbot message with the link to the recording.

To enable Event Subscriptions for your Chatbot App, navigate to the Chatbot settings in the App Marketplace Dashboard. Go to the features page and turn on the “Event Subscriptions” switch.

Click “Add new event subscription”, add a “Subscription Name”, choose who can trigger event subscriptions “All users in the account” or “Only users installed this app”, and add the Development and Production Event Notification Endpoint URLs.

Finally, choose the events to subscribe to, click “Done”.

Make sure to click “Save”.

Now your Chatbot is configured to receive Webhooks.