Authorization and Authentication

To interact with Zoom, Chatbot applications must be authorized and authenticated in order to access resources and make requests. Users add a chatbot and authorize it to use their account information. In this guide, add and authorize are used synonymously, as are deauthorize and remove.

On This Page

Authorization

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

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 adds 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 authorized.

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 authorized, 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
  }
}

Note that installed, in this case, means added and authorized.

Sending the Welcome Message

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

Response Body:

{
  "robot_jid": "v1w1u1acrraq_mhwf2gclg@xmpp.zoom.us",
  "to_jid": "kdynimt4kpd8kkdqt9fq@xmpp.zoom.us",
  "account_id": "gVZnWWRLWvv_GtyGuaxg",
  "content": {
    "head": {
      "text": "Custom Welcome Message!"
    },
    "body": [{
      "type": "message",
      "text": "Thanks for adding the Zoom Chatbot!"
    }]
  }
}

See Send Messages for descriptions of these fields.

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 ParameterDescription
grant_typeValue client_credentials
Request HeadersDescription
AuthorizationThe 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://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"
}

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 specific 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 add and authorize it.

chatbot gif

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 deauthorizes or removes 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.

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

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.