Sending Messages

New: Chatbot messages now support Markdown and @mentions!

A Chatbot is invoked when a User enters the app’s User Command into the Zoom Chat. This unique slash command triggers the Chatbot to interpret the text data following the command as a request. The Chatbot then sends the request to your Bot Endpoint URL and awaits a response from your application, which is passed back to the User as a message in the Zoom Chat.

The content, style, and format of Chatbot messages can be widely customized. Use our Customizing Messages guide for direct references and examples.

The User Command, Event Subscriptions, and Bot Endpoint URL are specified when creating your Chatbot app, and may be managed in the Zoom App Marketplace in the My Apps Dashboard. Reference our guide to Creating a Chatbot App for more detail.

Receiving User Commands and User Actions

Chatbots are invoked by Users through a User Command, which is a slash command unique to the application entered into Zoom Chat, OR a User Action which is a user interaction with the Editable Text, Form Field, Dropdown, or Button Chatbot message.

User Commands

After a user enters the User 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.

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

A User entering the text /unsplash island into the Zoom Chat would trigger 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 the 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, if received, could be displayed as an image in the 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.

User Actions

After a user interacts with a Editable Text, Form Field, Dropdown, or Button Chatbot message, 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.

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.

Sending a message

After successful authorization, Chatbot apps send messages through HTTP POST requests to the /im/chat/messages endpoint.

To send messages, your Chatbot app will require the imchat:bot scope to gain access to the API resource. For more information on adding Scopes to your app, see our Create a Chatbot App reference.

Request Schema Description

Headers Description
Authorization Bearer {{access_token}}
Content-Type application/json
Body Description
robot_jid Required, The BotJID found in the Chat Subscription Section on the Features page of your App Dashboard.
to_jid Required, The JID of the Channel or User you want the message sent to. Get this from the Chatbot request sent to your server, example above.
account_id Required, The AccountID of your Zoom account. Get this from the Chatbot request sent to your server, example above.
content Required, The Object containing the JSON which forms the message.
visible_to_user Optional, The UserID, allows a Chatbot to send a message to a group channel, but have only one designated person in that group channel see the message.
user_jid Optional, The UserJID of the user on whose behalf the message is being sent. Used to prevent members of a channel from getting notifications that were set up by a user who has left the channel.
is_markdown_support Optional, A Boolean, applies the markdown parser to your Chatbot message if set to true. See the Chatbot message markdown reference.

Example request

Below is an example POST request sent to https://api.zoom.us/v2/im/chat/messages

Request Headers:

"authorization": "Bearer {{access_token}}"
"content-type": "application/json"

Request Body:

{
   "robot_jid": "{{bot_jid}}",
   "to_jid": "{{to_jid}}",
   "account_id": "{{account_id}}",
   "content": {
      "head": {
         "text": "Hello World"
      }
   }
}

Example Response

{
  "message_id": "20190617170855488_1Cu0Fxp_aw1",
  "robot_jid": "v1m0yn1imztuogsxjje8fdew@xmpp.zoom.us",
  "sent_time": "2019-06-17 17:08:55",
  "to_jid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us"
}
Example's Chatbot Message
Example's Chatbot Message

Event Subscriptions

Chatbot apps can optionally include Event Subscription features using Zoom Webhooks to send notifications through Chatbot messages. These features can be enabled for all users in the account or only for users who install the app.

When a subscribed event on the Zoom platform occurs, a notification is sent to a Event Notification Endpoint URL. Your Chatbot app can then be developed to receive and handle incoming notifications and send them as Chatbot Messages directed to the appropriate Channel or User through the respective BotJID. For additional details on Event Subscriptions, see our Webhooks API Reference.

Need help?

The first place to look is on our Developer Forum. If you can't find the answer or your request includes sensitive information, contact Developer Support.