Installation and Authentication

To interact with Zoom, Chatbot applications must be installed and authenticated in order to access resources and make requests.


To get started with Chatbot development, create a Chatbot on the Zoom App Marketplace, and then install the Local Test version.

If this is the first time that you are requesting authorization from a user, the user will be prompted by Zoom to authorize access for your app.

If authorized, the user will be redirected to the redirect_uri with the authorization code in the code query parameter.

NOTE: You don’t need the code unless you plan on calling OAuth endpoints. Ignore it if you only plan to use the Chatbot endpoints.

If successful, you will see the default Welcome Message in Zoom Chat.

Welcome Message

From the App Marketplace Dashboard, you can customize the type of welcome message that gets sent to the user who installs your Chatbot.

The “Zoom App Marketplace” option allows you to set a static welcome message via the Marketplace GUI. If you do not enter anything in the Title and Body inputs, you will get the default message shown in the image above.

The “Your App” option allows you to set a dynamic welcome message that is sent programmatically after your Chatbot is installed.

Configuring a Dynamic Welcome Message

To configure a dynamic Welcome Message, go to your Chatbot’s settings, navigate to the “Features” page, and check the “Your App” option for the Welcome Message.

Make sure to click “Save”.

After your Chatbot is installed, an HTTP POST request will be sent to your respective Bot Endpoint URL with the following request body:

    "event": "bot_installed",
    "payload": {
        "robotJid": "",
        "userJid": "",
        "accountId": "gVZnWWRLWvv_GtyGuaxg",
        "userId": "KdYnimT4KPd8KKdQt9FQ",
        "userName": "Jane Dev",
        "timestamp": 1542654424247

Sending the Welcome Message

After receiving the bot_installed event, simply respond to the HTTP POST request you received with a Chatbot Message content Object to send the Welcome Message to Zoom Chat.

Response Body:

  "head": {
    "text": "Custom Welcome Message!"
  "body": [{
    "type": "message",
    "text": "Thanks for installing the Zoom Chatbot!"
Welcome Message in Zoom Chat:
Welcome Message in Zoom Chat:


To Send, Update, or Delete Chatbot messages, Chatbots, must be authenticated. Chatbots authenticate via the client_credentials grant type.

Since Chatbots authenticate at the application level, and not the user level, Chatbots only need to store and refresh one access_token for all users.

For information on using a Chatbot Token in conjunction with an OAuth Access Token, see the OAuth with Chatbots guide.

Requesting a Chatbot Token

Make a POST request to with the following query parameters and authorization header:

Query Parameter Description
grant_type Value client_credentials
Request Headers Description
Authorization The string “Basic” with your Client ID and Client Secret with a colon : in between, Base64 Encoded. For example, Client_ID:Client_Secret Base64 Encoded is Q2xpZW50X0lEOkNsaWVudF9TZWNyZXQ=.

Example Request:


Request Headers:

   "Authorization": "Basic Q2xpZW50X0lEOkNsaWVudF9TZWNyZXQ="

If successful, the response body will be a JSON representation of the Chatbot token:

    "access_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ2ZXIiOiI2IiwibmJmIjoxNTgwMTQ2NjkzLCJjbGllbnRJZCI6IjxDbGllbnRfSUQ-IiwiaXNzIjoidXJuOnpvb206Y29ubmVjdDpjbGllbnRpZDo8Q2xpZW50X0lEPiIsImF1dGhlbnRpY2F0aW9uSWQiOiI8QXV0aGVudGljYXRpb25fSUQ-IiwiZXhwIjoxNTgwMTUwMjkzLCJ0b2tlblR5cGUiOiJjbGllbnRfdG9rZW4iLCJpYXQiOjE1ODAxNDY2OTMsInVzZXJJZCI6IjxVc2VyX0lEPiIsImdyb3VwTnVtYmVyIjowLCJqdGkiOiI8SlRJPiJ9.chgzEaGxeYl3alAaLsFSRvQFVRqoabM5BINVELOYPO1FqveoEk02i8AIGrtg0FiX779pMWpMObkxFnPQy7euNA",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "imchat:bot"

Chatbot tokens expire after one hour.

Using a Chatbot Token

Make requests to the Chatbot API by sending the Chatbot token as the Authorization Bearer header:

"Authorization": "Bearer <CHATBOT_TOKEN>"

Example Request:


Request Headers:

"Authorization": "Bearer eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ2ZXIiOiI2IiwibmJmIjoxNTgwMTQ2NjkzLCJjbGllbnRJZCI6IjxDbGllbnRfSUQ-IiwiaXNzIjoidXJuOnpvb206Y29ubmVjdDpjbGllbnRpZDo8Q2xpZW50X0lEPiIsImF1dGhlbnRpY2F0aW9uSWQiOiI8QXV0aGVudGljYXRpb25fSUQ-IiwiZXhwIjoxNTgwMTUwMjkzLCJ0b2tlblR5cGUiOiJjbGllbnRfdG9rZW4iLCJpYXQiOjE1ODAxNDY2OTMsInVzZXJJZCI6IjxVc2VyX0lEPiIsImdyb3VwTnVtYmVyIjowLCJqdGkiOiI8SlRJPiJ9.chgzEaGxeYl3alAaLsFSRvQFVRqoabM5BINVELOYPO1FqveoEk02i8AIGrtg0FiX779pMWpMObkxFnPQy7euNA"

Request Body:

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

If successful, the response body will be a JSON representation of the sent Chatbot message:

	"message_id": "20191218175454248_UvRlxOz_aw1",
	"robot_jid": "",
	"sent_time": "2019-12-18 17:54:54",
	"to_jid": ""
Chatbot Message
Chatbot Message

Refreshing a Chatbot Token

Refreshing a Chatbot token is the same process as Requesting a Chatbot Token.

Deep Linking

Deep linking is supported by the Zoom Client so that an application can open Zoom Chat to a specific Chatbot channel.


To open Zoom Chat to a Chatbot channel, direct your user to:{ robot_jid_here }

This is useful for redirecting users to your Chatbot in Zoom Chat after they install it.

If you intend to submit your app to the Zoom App Marketplace, use the Deep Link on your Redirect URL page, and not as your actual “Redirect URL for OAuth” as it will differ from your base Domain Address and you won’t be able to submit your app for review.

User Flow

After navigating to the Chatbot Channel deep link:

If the user is not logged into the Zoom web portal, they are prompted to login.

Once logged in, the browser asks permission to open the Zoom Client.

If the user is logged into the Zoom Client as a user different than the Zoom web portal, the Zoom Client will ask the user to switch to the same account.

Then the Chatbot Channel will be opened.


When a User uninstalls a production Chatbot app, an HTTP POST request will be sent to the Chatbot’s Deauthorization Notification Endpoint URL specified in the App Dashboard’s Information page.

Uninstall Event

After receiving a Deauthorization request, Chatbot apps must delete all associated user data.

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

Below is an example Deauthorization request body, sent to the Chatbot’s Deauthorization Notification Endpoint URL:

  "event": "app_deauthorized",
  "payload": {
    "account_id": "EabCDEFghiLHMA",
    "user_id": "z9jkdsfsdfjhdkfjQ",
    "signature": "827edc3452044f0bc86bdd5684afb7d1e6becfa1a767f24df1b287853cf73000",
    "deauthorization_time": "2019-06-17T13:52:28.632Z",
    "client_id": "ADZ9k9bTWmGUoUbECUKU_a"