Chatbot
- OpenAPI Version:
3.1.1 - API Version:
2
Chatbot APIs allow developers to interface with chatbot features programmatically. These APIs are part of Zoom's app ecosystem and allow chatbots to send and receive messages, respond to user inputs, and perform actions within Zoom Team Chat. They are particularly useful for automating tasks, providing notifications, or integrating third-party services with Zoom.
Servers
- URL:
https://api.zoom.us/v2
Operations
Send Chatbot messages
- Method:
POST - Path:
/im/chat/messages - Tags: Chatbot Messages
Sends messages from your Marketplace Chatbot app.
Authorization Flow: Client Credentials Flow
To authorize, make a POST request to the /oauth/token endpoint with the client_credentials grant type. Use the https://api.zoom.us/oauth/token?grant_type=client_credentials endpoint for the request.
You will need to send your Client ID and Secret as a Basic Base64-encoded authorization header (for example, Basic base64Encode({client_id}:{client_secret}). Then, use the received access_token value as a Bearer token when you make the GET /im/chat/users/{user_id}/messages/{message_id} request.
For more information about authorizing Chatbots, read the Chatbot Installation and Authentication documentation.
Scopes: imchat:bot
Rate Limit Label: MEDIUM
Request Body
Content-Type: application/json
-
account_id(required)string— The authorized account's account ID. -
content(required)object— A JSON-format template that describes how the edited message should be displayed for the user. For more information, read our Chatbot [Send, Edit, and Delete Messages](/docs/team-chat-apps/send-edit-and-delete-messages/#send-messages) documentation. -
robot_jid(required)string— The bot JID. You can find this value in the **Feature** tab's **Chat Subscription** section of your Marketplace Chatbot app. -
to_jid(required)string— The JID of the group channel or user to whom the message was sent. -
user_jid(required)string— The JID of the user on whose behalf the message is being sent. This is used to prevent members of a channel from getting notifications that were set up by a user who has left the channel. -
is_markdown_supportboolean— Whether to apply the [Markdown parser to your Chatbot message](/docs/team-chat-apps/customizing-messages/message-with-markdown/). -
reply_tostring— The unique identifier of the parent message to which you want to send the chatbot's reply. -
visible_to_userstring— The user ID of the user who will receive Chatbot messages in the group channel. Only this user will see the Chatbot's messages.
Example:
{
"robot_jid": "v1pky3tyBBB5pl8q@xmpp.zoom.us",
"to_jid": "xghfd@shj.zoom.us",
"account_id": "ABCDE12345",
"content": {},
"visible_to_user": "FGHIJ67890@xmpp.zoom.us",
"user_jid": "jnrgfjp6w@xmpp.zoom.us",
"reply_to": "5AF2A82E-9220-4600-AFB2-A028852E377C",
"is_markdown_support": true
}
Responses
Status: 201 **HTTP Status Code:** `201`.
Content-Type: application/json
-
message_id(required)string— The unique identifier of the message. -
robot_jid(required)string— The bot JID. You can find this value in the **Feature** tab's **Chat Subscription** section of your Marketplace Chatbot app. -
sent_time(required)string— The date and time at which the message was sent in UTC timezone. Format: `yyyy-MM-dd HH:mm:ss` -
to_jid(required)string— The JID of the group channel or user to whom the message was sent. -
user_jidstring— The JID of the user on whose behalf the message is being sent.
Example:
{
"robot_jid": "v1pky3tyBBB5pl8q@xmpp.zoom.us",
"to_jid": "xghfd@shj.zoom.us",
"sent_time": "2019-10-17 01:40:24",
"message_id": "DWQ2A82E-9220-4600-AFB2-A028852E377C",
"user_jid": "jnrgfjp6w@xmpp.zoom.us"
}
Status: 400 **HTTP Status Code:** `400` <br> Bad Request **Error Code:** `7001` <br> Invalid Request Body format. <br>
Status: 401 **HTTP Status Code:** `401` <br> Unauthorized **Error Code:** `7010` <br> * Missing Authorization header. * Invalid Authorization token. <br>
Status: 403 **HTTP Status Code:** `403` <br> Forbidden **Error Code:** `7003` <br> No Chatbot can be found with the given robot_jid value. <br> **Error Code:** `7004` <br> * Not authorized. * No channel or user can be found with the given to_jid value. <br>
Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `7002` <br> Invalid robot_jid value specified in the Request Body. <br>
Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).
Edit a Chatbot message
- Method:
PUT - Path:
/im/chat/messages/{message_id} - Tags: Chatbot Messages
Use this API to edit a message sent by your Chatbot app.
After sending a message via the Send Chatbot message API, you must store the messageId value returned in the API response in order to make edits to the associated message using this API.
Authorization Flow: Client Credentials Flow
To authorize, make a POST request to the /oauth/token endpoint with the client_credentials grant type. Use the https://api.zoom.us/oauth/token?grant_type=client_credentials endpoint for the request.
You will need to send your Client ID and Secret as a Basic Base64-encoded authorization header (for example, Basic base64Encode({client_id}:{client_secret}). Then, use the received access_token value as a Bearer token when you make the GET /im/chat/users/{user_id}/messages/{message_id} request.
For more information about authorizing Chatbots, read the Chatbot Installation and Authentication documentation.
Scopes: imchat:bot
Rate Limit Label: MEDIUM
Request Body
Content-Type: application/json
-
account_id(required)string— The account ID to which the message was sent. You can get this value from the [Chatbot request sent to your server](/docs/team-chat-apps/send-edit-and-delete-messages/#send-messages). -
content(required)object— A JSON-format template that describes how the edited message should be displayed for the user. For more information, read our Chatbot [Send, Edit, and Delete Messages](/docs/team-chat-apps/send-edit-and-delete-messages/#send-messages) documentation. -
robot_jid(required)string— The Bot JID. You can find this value in the **Feature** tab's **Chat Subscription** section of your Marketplace Chatbot app. -
is_markdown_supportboolean— Whether to apply the [Markdown parser to your Chatbot message](/docs/team-chat-apps/customizing-messages/message-with-markdown/). -
user_jidstring— The JID of the user on whose behalf the message is being sent. This is used to prevent members of a channel from getting notifications that were set up by a user who has left the channel.
Example:
{
"robot_jid": "v1pky3tyBBB5pl8q@xmpp.zoom.us",
"account_id": "ABCDE12345",
"content": {},
"user_jid": "jnrgfjp6w@xmpp.zoom.us",
"is_markdown_support": true
}
Responses
Status: 200 **HTTP Status Code:** `200` Message updated.
Content-Type: application/json
-
message_idstring— The updated message's ID. -
robot_jidstring— The Bot JID. You can find this value in the **Feature** tab's **Chat Subscription** section of your Marketplace Chatbot app. -
sent_timestring— The date and time at which the message was sent. -
to_jidstring— The JID of the group channel or user to whom the message was sent. -
user_jidstring— The JID of the user on whose behalf the message is being sent. This is used to prevent members of a channel from getting notifications that were set up by a user who has left the channel.
Example:
{
"message_id": "201910tryyRFjM_main",
"robot_jid": "v1pky3tyBBB5pl8q@xmpp.zoom.us",
"sent_time": "2019-10-17 01:40:24 +0000",
"to_jid": "xghfd@shj.zoom.us",
"user_jid": "jnrgfjp6w@xmpp.zoom.us"
}
Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `8001` <br> Invalid message_id value. <br>
Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).
Delete a Chatbot message
- Method:
DELETE - Path:
/im/chat/messages/{message_id} - Tags: Chatbot Messages
Deletes a message from your Chatbot app.
Authorization Flow: Client Credentials Flow
To authorize, make a POST request to the /oauth/token endpoint with the client_credentials grant type. Use the https://api.zoom.us/oauth/token?grant_type=client_credentials endpoint for the request.
You will need to send your Client ID and Secret as a Basic Base64-encoded authorization header (for example, Basic base64Encode({client_id}:{client_secret}). Then, use the received access_token value as a Bearer token when you make the GET /im/chat/users/{user_id}/messages/{message_id} request.
For more information about authorizing Chatbots, read the Chatbot Authentication** documentation.
JSON payloads for guest users: Be aware that guest users (users not signed in to Zoom or who are members of a different account) are assigned temporary IDs that are valid only for the duration of that meeting or chat channel. Data for guest users in JSON payloads is associated with these temporary IDs.
Scopes: imchat:bot
Rate Limit Label: MEDIUM
Responses
Status: 200 **HTTP Status Code:** `200` Message deleted.
Content-Type: application/json
-
message_idstring— The deleted message's ID. -
robot_jidstring— The Bot JID. You can find this value in the **Feature** tab's **Chat Subscription** section of your Marketplace Chatbot app. -
sent_timestring— The date and time at which the message was deleted. UTC timezone. Format: `yyyy-MM-dd HH:mm:ss -
to_jidstring— The JID of the group channel or user to whom the message was sent. -
user_jidstring— The JID of the user on whose behalf the message is being sent. This is used to prevent members of a channel from getting notifications that were set up by a user who has left the channel.
Example:
{
"message_id": "201910tryyRFjM_main",
"robot_jid": "v1pky3tyBBB5pl8q@xmpp.zoom.us",
"sent_time": "2019-10-17 01:40:24 +0000",
"to_jid": "xghfd@shj.zoom.us",
"user_jid": "jnrgfjp6w@xmpp.zoom.us"
}
Status: 404 **HTTP Status Code:** `404` <br> Not Found **Error Code:** `8001` <br> Invalid message_id. <br>
Status: 429 **HTTP Status Code:** `429` <br> Too Many Requests. For more information, see [rate limits](https://developers.zoom.us/docs/api/rest/rate-limits/).
Link Unfurls
- Method:
POST - Path:
/im/chat/users/{userId}/unfurls/{triggerId} - Tags: Chatbot Messages
Unfurls a link with your Marketplace Chat app.
Authorization Flow: The client credentials flow authorizes and makes a POST request to the /oauth/token endpoint with the client_credentials grant type.
-
Use the
https://api.zoom.us/oauth/token?grant_type=client_credentialsendpoint for the request. -
You must send your client ID and secret as a basic Base64-encoded authorization header. (For example,
Basic base64Encode({client_id}:{client_secret}). -
Use the received
access_tokenvalue as a Bearer token when you make the GET/im/chat/users/{user_id}/messages/{message_id}request.
For more information about authorizing Chatbots, see the Chatbot Authorization and installation documentation.
Scopes: imchat:bot
Rate Limit Label: MEDIUM
Request Body
Content-Type: application/json
-
content(required)string— A JSON-format template that describes how the edited message should be displayed for the user. For more information, see the Chatbot [Customizing-Messages](https://developers.zoom.us/docs/team-chat-apps/customizing-messages/) documentation.
Example:
{
"content": ""
}