# Authorize

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

To interact with Zoom, chat apps must be authorized and authenticated to access resources and make requests.

## Add App

To install your Chatbot to your Zoom account, navigate to the Local Test page, and click Add App Now.

![](/img/blog/tommygaessler/unsplash-chatbot/section-1/development-beta.png)

You can also construct and navigate to the authorization URL yourself following this format:

```plaintext
https://zoom.us/oauth/authorize?response_type=code&client_id=ZOOM_CLIENT_ID&redirect_uri=ZOOM_REDIRECT_URI
```

If this is the first time you are authorizing your app or if you have made webhook or scope changes, Zoom prompts you to authorize.

![](/img/blog/tommygaessler/unsplash-chatbot/section-1/development-install.png)

If authorized, you will be redirected to the `redirect_uri` with the authorization code in the code query parameter. The `code` in the redirect URL can be used for `authorization_code` [OAuth flows](/docs/integrations/oauth/) to call additional [API endpoints](/docs/api/), but if you are just calling [Chatbot API endpoints](/docs/api/chatbot/), it is not needed.

`https://example.com/?code=Wk9PTV9BVVRIT1JJWkFUSU9OX0NPREU`

![](/img/example-redirect.png)

You can also [redirect to open the Zoom Client and show your chatbot to the user](/docs/chat/installation-and-authentication/#deep-linking).

In Zoom Chat, you should see the default welcome message for your chatbot. [Custom welcome messages](#custom-welcome-message) will be covered later in this section.

![](/img/default-welcome-message.png)

## Request chatbot token

To request a Chatbot token, make a `POST` request with a basic authorization header to:

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

The basic authorization header is your Client ID and Client Secret with a colon `:` in between, Base64 Encoded.

### Example request:

```plaintext
POST https://zoom.us/oauth/token?grant_type=client_credentials
```

Request headers:

```json
{ "Authorization": "Basic Wk9PTV9DTElFTlRfSUQ6Wk9PTV9DTElFTlRfU0VDUkVU" }
```

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

```json
{
    "access_token": "<JWT_TOKEN>",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "imchat:bot",
    "api_url": "https://api.zoom.us"
}
```

Chatbot tokens expire after one hour. After your chatbot token expires, you can simply [request a new one](#request-chatbot-token), there is no separate refresh flow required.

## OAuth token

To call APIs endpoints other than the Chatbot ones, you can request an [account managed](/docs/internal-apps/s2s-oauth/) or [admin/user managed](/docs/integrations/oauth/) OAuth `access_token` with your Chatbot's same client ID and client secret.

## Deep linking

The Zoom Client supports deep linking so that an application can open the Zoom Client to the chatbot.

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

`https://zoom.us/launch/chat?jid=robot_ZOOM_BOT_JID`

This URL is useful for redirecting users to your Chatbot in Zoom Chat after they add and authorize it.

![](/img/chatbot-deeplink.gif)

Notes:

-   If you intend to submit your app to the Zoom App Marketplace and have set this deep link as your OAuth redirect URL, you may need to proxy this deep link from a domain you own since Zoom may require domain validation when you submit your app.
-   After navigating to the Chatbot Channel deep link, if users are not logged in to the Zoom web portal, they are prompted to log in.
-   After log in, the browser asks permission to open the Zoom Client.
-   If the user is logged in to the Zoom Client as a user different from the Zoom web portal, the Zoom Client asks the user to switch to the same account. Then the Chatbot channel opens.

## Custom welcome message

From the **App Marketplace Dashboard**, you can customize the type of welcome message users receive when they add your Chatbot.

### Configuring a static welcome message

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

![](/img/static-custom-welcome-message.png)

Welcome message in Zoom Chat:

![](/img/sent-custom-welcome-message.png)

### Configuring a dynamic welcome message

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

![](/img/dynamic-welcome-message.png)

After your Chatbot is authorized, an HTTP POST request goes to
your respective Bot Endpoint URL with the following request body:

```json
{
    "event": "bot_installed",
    "payload": {
        "accountId": "Wk9PTV9BQ0NPVU5UX0lE",
        "robotJid": "Wk9PTV9ST0JPVF9KSUQ@xmpp.zoom.us",
        "timestamp": 1740442110529,
        "userId": "Wk9PTV9VU0VSX0lE",
        "userJid": "Wk9PTV9VU0VSX0lE@xmpp.zoom.us",
        "userMemberId": "Wk9PTV9VU0VSX01FTUJFUl9JRA",
        "userName": "Jane Dev",
        "userStatus": "authenticated"
    }
}
```

### Sending the welcome message

After receiving the `bot_installed` event, respond to the HTTP
POST request you received with a [Chatbot Message Object](/docs/chat/customizing-messages#base-json-structure) to send the welcome
message to Zoom Chat.

Response Body:

```json
{
    "content": {
        "head": {
            "text": "Custom Welcome Message!"
        },
        "body": [
            {
                "type": "message",
                "text": "Thanks for adding the Zoom Chatbot!"
            }
        ]
    }
}
```

Welcome message in Zoom Chat:

![](/img/sent-dynamic-welcome-message.png)

## Deauthorization

When a user deauthorizes or removes a **production** Chatbot app, an HTTP POST request will be sent to your app's Deauthorization Notification
Endpoint URL specified on the App Listing page.

![](/img/deauth-chatbot.png)

After receiving a [deauthorization webhook event](/docs/api/marketplace/events/#tag/app_deauthorized/POSTapp_deauthorized), apps must delete all associated user data.

An unsecured deauthorization notification endpoint URL leaves your server vulnerable to denial of service attacks. We recommend you verify the requests sent to your deauthorization notification endpoint URL with our [supported webhook verification methods](/docs/api/webhooks/#verify-webhook-events).

Below is an example deauthorization webhook event:

```json
{
    "event": "app_deauthorized",
    "event_ts": 1740439732278,
    "payload": {
        "account_id": "Wk9PTV9BQ0NPVU5UX0lE",
        "user_id": "Wk9PTV9VU0VSX0lE",
        "signature": "Wk9PTV9TSUdOQVRVUkU",
        "deauthorization_time": "2019-06-17T13:52:28.632Z",
        "client_id": "XO8c5xFdQVqGAgGB3utlRA"
    }
}
```