Installation and Authentication

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

Installation

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.

https://yourapp.com/?code=obBEe8ewaL_KdyNjniT4KPd8ffDWt9fGB

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": "v1w1u1acrraq_mhwf2gclg@xmpp.zoom.us",
        "userJid": "kdynimt4kpd8kkdqt9fq@xmpp.zoom.us",
        "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:

Authentication

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 https://zoom.us/oauth/token 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:

POST

https://api.zoom.us/oauth/token?grant_type=client_credentials

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"
}

Pro Tip: You can JWT Decode your Chatbot token to get a JSON object that includes data like the userId and more.

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:

POST

https://api.zoom.us/v2/im/chat/messages

Request Headers:

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

Request Body:

{
  "robot_jid": "v1zx6cy00psoylshypvg-iuq@xmpp.zoom.us",
  "to_jid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us",
  "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": "v1zx6cy00psoylshypvg-iuq@xmpp.zoom.us",
	"sent_time": "2019-12-18 17:54:54",
	"to_jid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us"
}
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 specfic Chatbot channel.

Usage

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

https://zoom.us/launch/chat?jid=robot_{ 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.

Deauthorization

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 and notify Zoom of the action by sending an HTTP POST request to the Data Compliance API. For a full reference on Deauthorization, reference our Data Compliance guide.

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": {
    "user_data_retention": false,
    "account_id": "EabCDEFghiLHMA",
    "user_id": "z9jkdsfsdfjhdkfjQ",
    "signature": "827edc3452044f0bc86bdd5684afb7d1e6becfa1a767f24df1b287853cf73000",
    "deauthorization_time": "2019-06-17T13:52:28.632Z",
    "client_id": "ADZ9k9bTWmGUoUbECUKU_a"
  }
}

Data Compliance Completed Request

After receiving the Deauthorization request body, set the payload object of the request as the deauthorization_event_received object for the POST request sent to the Data Compliance API.

Make a POST request to https://api.zoom.us/oauth/data/compliance with the following request header and request body:

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=.
Request Body Description
client_id Your Chatbot’s Client ID.
user_id The User ID of the User uninstalling your app. Retrieve from the app_deauthorized event.
account_id The Account ID of the User uninstalling your app. Retrieve from the app_deauthorized event.
compliance_completed Set to true if you have complied with the agreement.
deauthorization_event_received The payload object of the JSON Request Body you received from the app_deauthorized event.

Example Request:

POST

https://api.zoom.us/oauth/data/compliance

Request Headers:

{
   "Authorization": "Basic Q2xpZW50X0lEOkNsaWVudF9TZWNyZXQ="
}

Request Body:

{
  "client_id": "ADZ9k9bTWmGUoUbECUKU_a",
  "user_id": "z9jkdsfsdfjhdkfjQ",
  "account_id": "EabCDEFghiLHMA",
	"compliance_completed": true,
  "deauthorization_event_received": {
    "user_data_retention": false,
    "account_id": "EabCDEFghiLHMA",
    "user_id": "z9jkdsfsdfjhdkfjQ",
    "signature": "827edc3452044f0bc86bdd5684afb7d1e6becfa1a767f24df1b287853cf73000",
    "deauthorization_time": "2019-06-17T13:52:28.632Z",
    "client_id": "ADZ9k9bTWmGUoUbECUKU_a"
  }
}

If successful, the response body will be a JSON representation of the completed data compliance flow:

{
  "client_id": "ADZ9k9bTWmGUoUbECUKU_a",
  "user_id": "z9jkdsfsdfjhdkfjQ",
  "account_id": "EabCDEFghiLHMA",
  "user_data_retention": false,
  "deauthorization_time": "2020-01-17T16:49:24.649Z",
  "signature": "827edc3452044f0bc86bdd5684afb7d1e6becfa1a767f24df1b287853cf73000"
}

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.