Using Zoom's Incoming Webhook Chatbot

The Incoming Webhook app allows you to send messages from your external services, such as Amazon CloudWatch, directly to any Zoom chat channel. Use the chat app in any channel to generate a unique endpoint and verification token. With these credentials, you can send messages to your Zoom chat channel through HTTP POST requests.

This article covers:

How to add and configure Incoming Webhook
- Add from the Zoom App Marketplace
- Configure the Incoming Webhook Chatbot
How to send messages to Zoom Team Chat
How to use the Incoming Webhook Chatbot
- Available commands
- Examples of how to send messages with an image
How to remove the Incoming Webhook Chatbot

Prerequisites for using the Incoming Webhook chatbot

Pro, Business, Education, or Enterprise account
Account owner or admin privileges
Familiarity with sending HTTP POST requests with a token and endpoint
Admin approval to use the Incoming Webhook chatbot in the Zoom App Marketplace
Note: If the app is not pre-approved, please contact your Zoom admin. Learn more about admin app approvals.

How to add and configure Incoming Webhook

Add from the Zoom App Marketplace

You will need to have admin permissions on your Zoom account to add and configure the Incoming Webhook Chatbot.

Sign in to the Zoom App Marketplace as the account administrator.
In the top right of the window, search for Incoming Webhook.
In your search results, find the Incoming Webhook app and click it.
Note: If the app is not pre-approved, contact your Zoom admin to approve this app for your account. Learn more about admin app approvals.
Click Add.
Confirm the permissions the app requires, then click Authorize.
The Incoming Webhook app is now added.

Configure the Incoming Webhook Chatbot

Sign in to the Zoom desktop client.
Click the Team Chat tab.
Under Apps , find and select Incoming Webhook, or select a chat channel from above that you would like to receive messages in.
Enter one of the following commands to make a new connection:
- /inc connect <connectionName: Creates a connection and responds with a 1:1 chat message with the following details:
  - endpoint
  - verification token
  - example cURL requests
- /inc connect -s <connectionName: Creates a secure connection with signature and responds with a 1:1 chat message with the following details:
  - endpoint
  - secret
  - example cURL requests

You can use this information to send your POST requests.
Note: You must complete these steps for every channel you want to have the Incoming Webhook chatbot send messages to.

How to send messages to Zoom Team Chat

After you have created your connection, you can then start sending POST requests to the integration’s endpoint. Ensure that your POST requests include verification token to the Authorization header.
Note: The endpoint only accepts POST requests.

To test your connection, you can use Terminal or an open git-bash (or an equivalent that supports cURL commands). You can copy the example cURL from the initial 1:1 chat message from the Incoming Webhook Chatbot and send the cURL request. Once sent, you should see the test message sent in the specified channel. A successful test will respond with 200 OK.

For a connection with signature, the signature must be created in the following way:

base64UrlEncode(HMACSHA256({format}&${timestamp}&${input message}, secret))

timestamp: millisecond, expire in half an hour

As an example:

echo -n "{format}&{timestamp}&{input message}" | openssl dgst -sha256 -hmac {secret} -binary | base64

When sending messages using the Incoming Webhook Chatbot, you will have 6 options for the type and complexity of your messages:

Message format: This format allows you to send plain text coming from the created connection. You will need to send your content as a string in the body. To use this formatting, add the message as the format (?format=message) in the query parameter.
```
POST <endpoint>?format=message
Authorization: <verificationToken>
Content-Type: application/json
Body: "This is a test message."
```
Fields format: This format allows you to send simple formatting in fields. For example, you can have your message formatted into fields. To use this formatting, add fields as the format (?format=fields) in the query parameter.
```
POST <endpoint>?format=fields
Authorization: <verificationToken>
Content-Type: application/json
Body:
{
"Field 1": "bar",
"Field 2": "qux"
}
```
List format: This format allows you to send simple formatting as a list. For example, you can have your message formatted as a list. To use this formatting, add list as the format (?format=list) in the query parameter.
```
POST <endpoint>?format=list
Authorization: <verificationToken>
Content-Type: application/json
Body:
{
"Item 1": "Item 1",
"Item 2": "Item 2"
}
```
Full format: This format will allow you to generate and send rich message formatting in Zoom Chat messages. Such formatting allows you to use headers, subheaders, links, buttons, dropdowns, attachments, and more to your chatbot messages. To use this formatting, you will need to append full as the format (?format=full) in the query parameter. For more information on the supported JSON objects, please see this developer documentation.
```
POST <endpoint>?format=full
Authorization: <verificationToken>
Content-Type: application/json
Body:
{supported JSON object}
```
Upload format: This format will allow you to get the information required for uploading a file, including UploadLink, UploadToken, and UploadUserId. To use this formatting, you will need to append upload as the format (?format=upload) in the query parameter. Nothing needs to be added in the body.
Note: This requires a connection with signature.
```
POST <endpoint>?format=upload
Authorization: <verificationToken>
Content-Type: application/json
```
Image format: This format will allow you to send an image in messages. To use this formatting, you will need to append img as the format (?format=img) in the query parameter.
Note: This requires a connection with signature.
```
POST <endpoint>?format=img
Authorization: <verificationToken>
Content-Type: application/json
Body:
[
{
"text":"input message",
"img":["file1","file2"]
}
]
```

How to use the Incoming Webhook Chatbot

Available commands

/inc connect: Enter /inc connect <connectionName>, with <ConnectionName> being replaced with appropriately, to create an endpoint (URL) and token to start sending messages directly to your current chat channel. This chatbot supports 1:1 direct messages as well as channels.
/inc connect -s: Enter /inc connect -s <connectionName>, with <ConnectionName> being replaced with appropriately, to create an endpoint (URL) and token, with support for signature and access controlled images.
/inc regenerate: Enter /inc regenerate <connectionName>, with <ConnectionName> being replaced with appropriately, to regenerate the verification token for the specified connection.
/inc disconnect: Enter /inc disconnect <connectionName>, with <ConnectionName> being replaced with appropriately, to remove the specified connection.
/inc disconnect all: Enter /inc disconnect all to remove all connections for all channels for the Incoming Webhook Chatbot.
/inc configure: Enter /inc configure to list all connections for the current chat channel.
/inc configure all: Enter /inc configure all to list all connections for all channels.
/inc admin: Enter /inc admin to get a link to open the admin page.

Examples of how to send messages with an image

Send a message with upload format to get upload information

curl 'https://integrations.zoom.us/chat/webhooks/incomingwebhook/dSUcla-dQaGYgqGuBk3BsQ?format=upload&timestamp={timestamp}' -X POST -H 'Authorization: {authorization}'

Upload image with the obtained upload information and it will return the file id in response header Zoom-File-ID

curl '{uploadLink}' -i -F file=@{path} -X POST -H 'Authorization: Bearer {uploadToken}' -H 'Zoom-File-Meta: {"ownerType":"user","ownerId":"{userId}"}'

Send an image format message with the uploaded file id

curl 'https://integrations.zoom.us/chat/webhooks/incomingwebhook/dSUcla-dQaGYgqGuBk3BsQ?format=img&timestamp={timestamp}' -X POST -H 'Authorization: {authorization}' -H 'Content-Type: application/json' -d '[{"text":"input message","img":["fileId1","fileId2"]}]'

How to remove the Incoming Webhook Chatbot

Sign in to the Zoom App Marketplace as the account administrator.
In the top-right corner of the page, click Manage.
In the navigation menu, click Added Apps.
Next to the Incoming WebHook app, click Remove.
Confirm the dialogue and click Remove.
Note: Performing this step will also remove all active connections in Zoom Team Chat.

For additional help, submit a request to Zoom Support.