From bed56aede188dcf2322d763a05a501f659f0480c Mon Sep 17 00:00:00 2001 From: Pranav Kamble Date: Thu, 19 Nov 2026 19:42:28 +0530 Subject: [PATCH 1/3] docs(ENG-57601): add Bots section to the REST API reference Co-authored-by: multica-agent --- chat-apis.json | 426 +++++++++++++++++++++++++++++++++++++++ docs.json | 11 + rest-api/bots.mdx | 75 +++++++ rest-api/bots/create.mdx | 26 +++ rest-api/bots/delete.mdx | 12 ++ rest-api/bots/get.mdx | 29 +++ rest-api/bots/list.mdx | 46 +++++ rest-api/bots/update.mdx | 20 ++ 8 files changed, 645 insertions(+) create mode 100644 rest-api/bots.mdx create mode 100644 rest-api/bots/create.mdx create mode 100644 rest-api/bots/delete.mdx create mode 100644 rest-api/bots/get.mdx create mode 100644 rest-api/bots/list.mdx create mode 100644 rest-api/bots/update.mdx diff --git a/chat-apis.json b/chat-apis.json index 33890e75c..f77e01433 100644 --- a/chat-apis.json +++ b/chat-apis.json @@ -1131,6 +1131,428 @@ ] } }, + "/bots": { + "post": { + "tags": [ + "Bots" + ], + "summary": "Create", + "description": "Creates a new bot for an existing user", + "operationId": "create-bot", + "requestBody": { + "content": { + "application/json": { + "schema": { + "required": [ + "uid", + "webhookURL" + ], + "properties": { + "uid": { + "description": "UID of an existing user to turn into a bot. Maximum 50 characters, forced to lowercase.", + "type": "string", + "default": "" + }, + "webhookURL": { + "description": "URL that receives the messages relayed to the bot. Maximum 255 characters.", + "type": "string", + "default": "" + }, + "groupChatSetting": { + "description": "Which group messages are relayed to the webhook. Possible values: allMessages, slashedMessages, mentionedMessages, none.", + "type": "string", + "default": "none", + "enum": [ + "allMessages", + "slashedMessages", + "mentionedMessages", + "none" + ] + }, + "useBasicAuth": { + "description": "Sends HTTP basic auth credentials with every webhook call.", + "type": "boolean", + "default": false + }, + "username": { + "description": "Basic auth username. Maximum 50 characters. Ignored unless useBasicAuth is true.", + "type": "string", + "default": "" + }, + "password": { + "description": "Basic auth password. Maximum 50 characters. Ignored unless useBasicAuth is true.", + "type": "string", + "default": "" + }, + "enabled": { + "description": "Whether the bot relays messages to its webhook.", + "type": "boolean", + "default": false + } + }, + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "Created a new Bot", + "content": { + "application/json": { + "schema": { + "properties": { + "data": { + "type": "object" + } + }, + "type": "object" + }, + "example": { + "data": { + "uid": "support-bot", + "webhookURL": "https://example.com/webhooks/support-bot", + "groupChatSetting": "mentionedMessages", + "useBasicAuth": true, + "username": "support-bot", + "password": "********", + "enabled": true, + "createdAt": 1763558400 + } + } + } + } + } + }, + "security": [ + { + "apiKey": [] + } + ] + }, + "get": { + "tags": [ + "Bots" + ], + "summary": "List", + "description": "Lists the bots of an app", + "operationId": "list-bots", + "parameters": [ + { + "name": "searchKey", + "in": "query", + "description": "Performs a LIKE% query, searching for bot UIDs starting with the specified characters.", + "schema": { + "type": "string" + } + }, + { + "name": "isAIBot", + "in": "query", + "description": "Fetches AI bots instead of standard bots. Defaults to false, so AI bots are returned only when this is true.", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "perPage", + "in": "query", + "description": "Number of bots to be fetched in a request. The default value is 100 and the maximum value is 1000.", + "schema": { + "type": "integer", + "default": "100" + } + }, + { + "name": "page", + "in": "query", + "description": "Page Number.", + "schema": { + "type": "integer", + "default": "1" + } + } + ], + "responses": { + "200": { + "description": "Lists the bots", + "content": { + "application/json": { + "schema": { + "properties": { + "data": { + "type": "array", + "items": {} + }, + "meta": { + "type": "object" + } + }, + "type": "object" + }, + "example": { + "data": [ + { + "uid": "order-bot", + "webhookURL": "https://example.com/webhooks/order-bot", + "groupChatSetting": "slashedMessages", + "enabled": true, + "createdAt": 1763472000 + }, + { + "uid": "support-bot", + "webhookURL": "https://example.com/webhooks/support-bot", + "groupChatSetting": "mentionedMessages", + "useBasicAuth": true, + "username": "support-bot", + "password": "********", + "enabled": true, + "createdAt": 1763558400, + "updatedAt": 1763561000 + } + ], + "meta": { + "pagination": { + "total": 2, + "count": 2, + "per_page": 100, + "current_page": 1, + "total_pages": 1 + } + } + } + } + } + } + }, + "security": [ + { + "apiKey": [] + } + ] + } + }, + "/bots/{uid}": { + "get": { + "tags": [ + "Bots" + ], + "summary": "Get", + "description": "Retrieves bot details for a specified UID.", + "operationId": "get-bot", + "parameters": [ + { + "name": "uid", + "in": "path", + "description": "An UID of a bot.", + "required": true, + "schema": { + "type": "string" + }, + "examples": { + "string": { + "summary": "UID", + "value": "" + } + } + } + ], + "responses": { + "200": { + "description": "Fetched the bot", + "content": { + "application/json": { + "schema": { + "properties": { + "data": { + "type": "object" + } + }, + "type": "object" + }, + "example": { + "data": { + "uid": "support-bot", + "webhookURL": "https://example.com/webhooks/support-bot", + "groupChatSetting": "mentionedMessages", + "useBasicAuth": true, + "username": "support-bot", + "password": "********", + "enabled": true, + "createdAt": 1763558400 + } + } + } + } + } + }, + "security": [ + { + "apiKey": [] + } + ] + }, + "put": { + "tags": [ + "Bots" + ], + "summary": "Update", + "description": "Updates a bot with the provided UID", + "operationId": "update-bot", + "parameters": [ + { + "name": "uid", + "in": "path", + "description": "An UID of a bot.", + "required": true, + "schema": { + "type": "string" + }, + "examples": { + "string": { + "summary": "UID", + "value": "" + } + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "properties": { + "webhookURL": { + "description": "URL that receives the messages relayed to the bot. Maximum 255 characters.", + "type": "string", + "default": "" + }, + "groupChatSetting": { + "description": "Which group messages are relayed to the webhook. Possible values: allMessages, slashedMessages, mentionedMessages, none.", + "type": "string", + "enum": [ + "allMessages", + "slashedMessages", + "mentionedMessages", + "none" + ] + }, + "useBasicAuth": { + "description": "Sends HTTP basic auth credentials with every webhook call.", + "type": "boolean", + "default": false + }, + "username": { + "description": "Basic auth username. Maximum 50 characters. Ignored unless useBasicAuth is true.", + "type": "string", + "default": "" + }, + "password": { + "description": "Basic auth password. Maximum 50 characters. Ignored unless useBasicAuth is true.", + "type": "string", + "default": "" + }, + "enabled": { + "description": "Whether the bot relays messages to its webhook.", + "type": "boolean", + "default": false + } + }, + "type": "object" + } + } + } + }, + "responses": { + "200": { + "description": "Updated Bot", + "content": { + "application/json": { + "schema": { + "properties": { + "data": { + "type": "object" + } + }, + "type": "object" + }, + "example": { + "data": { + "uid": "support-bot", + "webhookURL": "https://example.com/webhooks/support-bot-v2", + "groupChatSetting": "allMessages", + "useBasicAuth": true, + "username": "support-bot", + "password": "********", + "enabled": true, + "createdAt": 1763558400, + "updatedAt": 1763561000 + } + } + } + } + } + }, + "security": [ + { + "apiKey": [] + } + ] + }, + "delete": { + "tags": [ + "Bots" + ], + "summary": "Delete", + "description": "Deletes a bot for the specified UID", + "operationId": "delete-bot", + "parameters": [ + { + "name": "uid", + "in": "path", + "description": "An UID of a bot.", + "required": true, + "schema": { + "type": "string" + }, + "examples": { + "string": { + "summary": "UID", + "value": "" + } + } + } + ], + "responses": { + "200": { + "description": "Deleted Bot", + "content": { + "application/json": { + "schema": { + "properties": { + "data": { + "type": "object" + } + }, + "type": "object" + }, + "example": { + "data": { + "success": true, + "message": "A bot with uid support-bot has been removed successfully." + } + } + } + } + } + }, + "security": [ + { + "apiKey": [] + } + ] + } + }, "/groups": { "post": { "tags": [ @@ -21566,6 +21988,10 @@ "name": "Users", "description": "The REST collection for users." }, + { + "name": "Bots", + "description": "The bots relay messages from your app to a webhook." + }, { "name": "Auth Tokens", "description": "The auth tokens are used to login end users using client SDKs." diff --git a/docs.json b/docs.json index 40eea0779..58788a8cd 100644 --- a/docs.json +++ b/docs.json @@ -4995,6 +4995,17 @@ "rest-api/users/delete" ] }, + { + "group": "Bots", + "pages": [ + "rest-api/bots", + "rest-api/bots/list", + "rest-api/bots/create", + "rest-api/bots/get", + "rest-api/bots/update", + "rest-api/bots/delete" + ] + }, { "group": "Blocked Users", "pages": [ diff --git a/rest-api/bots.mdx b/rest-api/bots.mdx new file mode 100644 index 000000000..34f69f28e --- /dev/null +++ b/rest-api/bots.mdx @@ -0,0 +1,75 @@ +--- +title: "Overview" +description: "Create and manage CometChat bots with REST APIs to relay user and group messages to your own webhook." +--- + +A **Bot** is an existing user that also has a webhook. Once a bot is enabled, CometChat relays the messages it receives to the bot's `webhookURL`, and your service replies by calling the [Send Bot Message API](/rest-api/messages/send-bot-message). + +### Endpoints + +| Method | Endpoint | Description | +| ------ | -------- | ----------- | +| POST | [`/bots`](/rest-api/bots/create) | Create a new bot | +| GET | [`/bots`](/rest-api/bots/list) | List all bots | +| GET | [`/bots/{uid}`](/rest-api/bots/get) | Get a specific bot | +| PUT | [`/bots/{uid}`](/rest-api/bots/update) | Update a bot | +| DELETE | [`/bots/{uid}`](/rest-api/bots/delete) | Delete a bot | + +### How bots work + +- A bot is a **user plus a webhook**. The `uid` you pass to the Create Bot API must already belong to a [User](/rest-api/users); if it does not, the API returns `ERR_UID_NOT_FOUND`. +- One-to-one messages sent to the bot are relayed to its `webhookURL`. +- Group messages are relayed according to `groupChatSetting`: + +| Value | Messages relayed to the webhook | +| ----- | ------------------------------- | +| `allMessages` | Every message in groups the bot belongs to | +| `slashedMessages` | Only messages beginning with a slash command | +| `mentionedMessages` | Only messages that mention the bot | +| `none` | No group messages. This is the default. | + +- A bot only relays messages while `enabled` is `true`. +- Set `useBasicAuth` to `true` to send HTTP basic auth credentials with every webhook call, so your endpoint can verify the caller. +- Bots reply through the [Send Bot Message API](/rest-api/messages/send-bot-message), which posts a message as the bot. + + +When `useBasicAuth` is `true`, the API returns the stored `password` value in responses to Create, List, Get and Update. A `GET /bots` response therefore contains the basic auth credentials of every bot in the app. Treat those responses as secrets, and restrict who can use the API key that reads them. + + +### Relationships + +- **Users** — A bot is a [User](/rest-api/users) with a webhook attached. Its name and avatar belong to the user, so change them with the [Update User API](/rest-api/users/update). +- **Send Bot Message** — Use the [Send Bot Message API](/rest-api/messages/send-bot-message) to post a message as a bot. +- **Custom Bots** — For an end-to-end walkthrough, including the webhook payload your service receives, see the [Custom Bots guide](/ai-chatbots/custom-bots). + +### Bot properties + +| Property | Type | Description | +| -------- | ---- | ----------- | +| **uid** | string | UID of the user this bot belongs to. Forced to lowercase. | +| **webhookURL** | string | URL that receives the messages relayed to the bot. | +| **groupChatSetting** | string | Which group messages are relayed. One of `allMessages`, `slashedMessages`, `mentionedMessages`, `none`. | +| **useBasicAuth** | boolean | Whether basic auth credentials are sent with each webhook call. | +| **username** | string | Basic auth username. Stored only when `useBasicAuth` is `true`. | +| **password** | string | Basic auth password. Stored only when `useBasicAuth` is `true`, and returned in responses as stored. | +| **enabled** | boolean | Whether the bot relays messages to its webhook. | +| **isAIBot** | boolean | Whether this is an AI bot. AI bots are created through AI Agents, not this API, and are returned only when you pass `isAIBot=true` to the List Bots API. | +| **createdAt** | integer | UNIX timestamp of when the bot was created. | +| **updatedAt** | integer | UNIX timestamp of the last update. Absent until the bot is updated. | + + +Responses omit every property whose value is empty or `false`. A bot with `useBasicAuth` set to `false` has no `useBasicAuth`, `username` or `password` in its response, and a standard bot has no `isAIBot`. + + +### Error handling + +| Error Code | Description | +| ---------- | ----------- | +| `ERR_BOT_NOT_FOUND` | No bot exists with the specified UID | +| `ERR_UID_NOT_FOUND` | No user exists with the specified UID | +| `ERR_PLAN_RESTRICTION` | Your plan does not include bots | +| `ERR_BAD_REQUEST` | The request failed validation, for example a duplicate bot UID | + +For the complete list of error codes, see [Error Guide](/articles/error-guide). + +For all system limits (bot caps, UID length, etc.), see [Properties and Constraints](/articles/properties-and-constraints). diff --git a/rest-api/bots/create.mdx b/rest-api/bots/create.mdx new file mode 100644 index 000000000..c6f995e42 --- /dev/null +++ b/rest-api/bots/create.mdx @@ -0,0 +1,26 @@ +--- +openapi: post /bots +description: "Create a CometChat bot for an existing user with the REST API and relay its messages to your own webhook." +--- + +The `uid` must already belong to a [User](/rest-api/users). If no such user exists, the API returns `ERR_UID_NOT_FOUND`. + +`groupChatSetting` defaults to `none`, so a new bot receives no group messages until you set it. `username` and `password` are stored only when `useBasicAuth` is `true`; otherwise they are discarded. + +A bot's name and avatar belong to its user, not to the bot — set them with the [Update User API](/rest-api/users/update). + +## Constraints + +| Item | Constraint | Notes | +| ---- | ---------- | ----- | +| Bot UID | 50 characters | Must match an existing user. CometChat forces the UID to lowercase | +| Webhook URL | 255 characters | Must be a valid URL | +| Basic auth username | 50 characters | Ignored unless `useBasicAuth` is `true` | +| Basic auth password | 50 characters | Ignored unless `useBasicAuth` is `true` | +| Bots per app | 25 bot users | See [Properties and Constraints](/articles/properties-and-constraints) | + + +When `useBasicAuth` is `true`, the API returns the stored `password` value in the response. The example masks it as `********`; a real response contains the password you sent. + + +For the complete error reference, see [Error Guide](/articles/error-guide). diff --git a/rest-api/bots/delete.mdx b/rest-api/bots/delete.mdx new file mode 100644 index 000000000..61c8fe934 --- /dev/null +++ b/rest-api/bots/delete.mdx @@ -0,0 +1,12 @@ +--- +openapi: delete /bots/{uid} +description: "Delete a CometChat bot by UID with the REST API and confirm the removal from the response." +--- + +Deleting a bot removes the bot and its webhook configuration. **The underlying user is not deleted** — the UID stays in your app as an ordinary [User](/rest-api/users), and its messages remain. To remove the user as well, call the [Delete User API](/rest-api/users/delete) afterwards. + +A later [Get Bot](/rest-api/bots/get) call for the same UID returns `ERR_BOT_NOT_FOUND`. + +To stop a bot temporarily without deleting it, set `enabled` to `false` with the [Update Bot API](/rest-api/bots/update). + +For the complete error reference, see [Error Guide](/articles/error-guide). diff --git a/rest-api/bots/get.mdx b/rest-api/bots/get.mdx new file mode 100644 index 000000000..d78e3518b --- /dev/null +++ b/rest-api/bots/get.mdx @@ -0,0 +1,29 @@ +--- +openapi: get /bots/{uid} +description: "Retrieve the details of a single CometChat bot by UID using the REST API." +--- + +Returns `ERR_BOT_NOT_FOUND` when no bot exists with this UID, including when the UID belongs to a user who is not a bot. + +Responses omit every property whose value is empty or `false`, so a bot with basic auth turned off has no `useBasicAuth`, `username` or `password`, and a standard bot has no `isAIBot`. + +For an AI bot, the response includes the flag: + +```json +{ + "data": { + "uid": "research-agent", + "webhookURL": "https://example.com/webhooks/research-agent", + "groupChatSetting": "mentionedMessages", + "enabled": true, + "isAIBot": true, + "createdAt": 1763472000 + } +} +``` + + +When `useBasicAuth` is `true`, the API returns the stored `password` value as it was saved. The example masks it as `********`. + + +For the complete error reference, see [Error Guide](/articles/error-guide). diff --git a/rest-api/bots/list.mdx b/rest-api/bots/list.mdx new file mode 100644 index 000000000..421033cee --- /dev/null +++ b/rest-api/bots/list.mdx @@ -0,0 +1,46 @@ +--- +openapi: get /bots +description: "Retrieve a paginated list of the bots in a CometChat app using the REST API, with search and AI bot filtering." +--- + +`searchKey` matches the start of a bot's UID, not its name. Results are ordered by UID. + +`perPage` defaults to 100 and is capped at 1000. Page through the results rather than assuming one response holds every bot. + +### Listing AI bots + +`isAIBot` defaults to `false`, so this endpoint returns standard bots only. Pass `isAIBot=true` to list AI bots instead — there is no call that returns both at once. AI bots are created through AI Agents, not through the [Create Bot API](/rest-api/bots/create). + +A `GET /bots?isAIBot=true` response looks like this: + +```json +{ + "data": [ + { + "uid": "research-agent", + "webhookURL": "https://example.com/webhooks/research-agent", + "groupChatSetting": "mentionedMessages", + "enabled": true, + "isAIBot": true, + "createdAt": 1763472000 + } + ], + "meta": { + "pagination": { + "total": 1, + "count": 1, + "per_page": 100, + "current_page": 1, + "total_pages": 1 + } + } +} +``` + +`isAIBot` appears only when it is `true`, because responses omit every property whose value is empty or `false`. That is also why the standard bot in the example response above has no `useBasicAuth` block. + + +Bots with `useBasicAuth` set to `true` return their stored `password` in this response, so a single call can expose the basic auth credentials of every bot in the app. The examples mask the value as `********`. + + +For the complete error reference, see [Error Guide](/articles/error-guide). diff --git a/rest-api/bots/update.mdx b/rest-api/bots/update.mdx new file mode 100644 index 000000000..19e67db2e --- /dev/null +++ b/rest-api/bots/update.mdx @@ -0,0 +1,20 @@ +--- +openapi: put /bots/{uid} +description: "Update a CometChat bot's webhook, group chat setting, basic auth credentials or enabled state with the REST API." +--- + +Every field is optional — send only the ones you want to change. The bot's `uid` cannot be changed; delete the bot and create a new one instead. + +`groupChatSetting` accepts the same four values as the [Create Bot API](/rest-api/bots/create): `allMessages`, `slashedMessages`, `mentionedMessages` and `none`. + +`username` and `password` apply only while `useBasicAuth` is `true`. Setting `enabled` to `false` stops the bot relaying messages without deleting it. + +A bot's name and avatar belong to its user — change them with the [Update User API](/rest-api/users/update). + +`updatedAt` appears in the response once a bot has been updated. + + +When `useBasicAuth` is `true`, the API returns the stored `password` value as it was saved. The example masks it as `********`. + + +For the complete error reference, see [Error Guide](/articles/error-guide). From b02531db7385ec1f2105cf7e2a66f1a9fe1e3366 Mon Sep 17 00:00:00 2001 From: Pranav Kamble Date: Thu, 19 Nov 2026 19:59:43 +0530 Subject: [PATCH 2/3] docs(ENG-57601): state the enabled default and correct two Bots page claims Co-authored-by: multica-agent --- rest-api/bots.mdx | 4 ++-- rest-api/bots/create.mdx | 2 +- rest-api/bots/list.mdx | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/rest-api/bots.mdx b/rest-api/bots.mdx index 34f69f28e..fba13a4e2 100644 --- a/rest-api/bots.mdx +++ b/rest-api/bots.mdx @@ -52,8 +52,8 @@ When `useBasicAuth` is `true`, the API returns the stored `password` value in re | **useBasicAuth** | boolean | Whether basic auth credentials are sent with each webhook call. | | **username** | string | Basic auth username. Stored only when `useBasicAuth` is `true`. | | **password** | string | Basic auth password. Stored only when `useBasicAuth` is `true`, and returned in responses as stored. | -| **enabled** | boolean | Whether the bot relays messages to its webhook. | -| **isAIBot** | boolean | Whether this is an AI bot. AI bots are created through AI Agents, not this API, and are returned only when you pass `isAIBot=true` to the List Bots API. | +| **enabled** | boolean | Whether the bot relays messages to its webhook. Defaults to `false`. | +| **isAIBot** | boolean | Whether this is an AI bot. AI bots are created through AI Agents, and are returned only when you pass `isAIBot=true` to the List Bots API. | | **createdAt** | integer | UNIX timestamp of when the bot was created. | | **updatedAt** | integer | UNIX timestamp of the last update. Absent until the bot is updated. | diff --git a/rest-api/bots/create.mdx b/rest-api/bots/create.mdx index c6f995e42..86a70fcfc 100644 --- a/rest-api/bots/create.mdx +++ b/rest-api/bots/create.mdx @@ -5,7 +5,7 @@ description: "Create a CometChat bot for an existing user with the REST API and The `uid` must already belong to a [User](/rest-api/users). If no such user exists, the API returns `ERR_UID_NOT_FOUND`. -`groupChatSetting` defaults to `none`, so a new bot receives no group messages until you set it. `username` and `password` are stored only when `useBasicAuth` is `true`; otherwise they are discarded. +`enabled` defaults to `false`, so send `enabled: true` — or call the [Update Bot API](/rest-api/bots/update) afterwards — before the bot will relay anything. `groupChatSetting` defaults to `none`, so a new bot receives no group messages until you set it. `username` and `password` are stored only when `useBasicAuth` is `true`; otherwise they are discarded. A bot's name and avatar belong to its user, not to the bot — set them with the [Update User API](/rest-api/users/update). diff --git a/rest-api/bots/list.mdx b/rest-api/bots/list.mdx index 421033cee..b80cf54ca 100644 --- a/rest-api/bots/list.mdx +++ b/rest-api/bots/list.mdx @@ -9,7 +9,7 @@ description: "Retrieve a paginated list of the bots in a CometChat app using the ### Listing AI bots -`isAIBot` defaults to `false`, so this endpoint returns standard bots only. Pass `isAIBot=true` to list AI bots instead — there is no call that returns both at once. AI bots are created through AI Agents, not through the [Create Bot API](/rest-api/bots/create). +`isAIBot` defaults to `false`, so this endpoint returns standard bots only. Pass `isAIBot=true` to list AI bots instead — there is no call that returns both at once. AI bots are created through AI Agents. A `GET /bots?isAIBot=true` response looks like this: @@ -37,7 +37,7 @@ A `GET /bots?isAIBot=true` response looks like this: } ``` -`isAIBot` appears only when it is `true`, because responses omit every property whose value is empty or `false`. That is also why the standard bot in the example response above has no `useBasicAuth` block. +`isAIBot` appears only when it is `true`, because responses omit every property whose value is empty or `false`. That is also why `order-bot` in the response example has no `useBasicAuth`, `username` or `password`. Bots with `useBasicAuth` set to `true` return their stored `password` in this response, so a single call can expose the basic auth credentials of every bot in the app. The examples mask the value as `********`. From b32f071dfce5b0e1a34e71d1ea088ae0db5e2661 Mon Sep 17 00:00:00 2001 From: siva-cometchat Date: Thu, 19 Nov 2026 20:55:45 +0530 Subject: [PATCH 3/3] docs(ENG-57601): correct Bots update and AI bot behaviour from review - Update stores username/password as sent and never clears them when useBasicAuth is set to false; reword the overview property rows, the response note, the Update page and the password warnings to match. - Bots created through AI Agents (type agentic) are hidden from every public bot endpoint; stop describing isAIBot bots as AI Agents, swap the research-agent examples for faq-bot, and note ERR_BOT_NOT_FOUND for agents. - Re-merge the Bots operations from the regenerated chat-api OAS: drop the defaults from the update-bot request body and reword the isAIBot and basic auth descriptions. - Drop the "Bots per app" row from Create; this API does not enforce it. Co-Authored-By: Claude Opus 5.5 --- chat-apis.json | 23 +++++++++-------------- rest-api/bots.mdx | 13 +++++++------ rest-api/bots/create.mdx | 1 - rest-api/bots/get.mdx | 12 ++++++------ rest-api/bots/list.mdx | 10 ++++++---- rest-api/bots/update.mdx | 6 ++++-- 6 files changed, 32 insertions(+), 33 deletions(-) diff --git a/chat-apis.json b/chat-apis.json index f77e01433..9d89d0680 100644 --- a/chat-apis.json +++ b/chat-apis.json @@ -1249,7 +1249,7 @@ { "name": "isAIBot", "in": "query", - "description": "Fetches AI bots instead of standard bots. Defaults to false, so AI bots are returned only when this is true.", + "description": "Returns only bots flagged as AI bots instead of standard bots. Defaults to false. Agents created through AI Agents are not returned either way.", "schema": { "type": "boolean", "default": false @@ -1424,8 +1424,7 @@ "properties": { "webhookURL": { "description": "URL that receives the messages relayed to the bot. Maximum 255 characters.", - "type": "string", - "default": "" + "type": "string" }, "groupChatSetting": { "description": "Which group messages are relayed to the webhook. Possible values: allMessages, slashedMessages, mentionedMessages, none.", @@ -1438,24 +1437,20 @@ ] }, "useBasicAuth": { - "description": "Sends HTTP basic auth credentials with every webhook call.", - "type": "boolean", - "default": false + "description": "Sends HTTP basic auth credentials with every webhook call. Setting this to false does not clear a stored username or password.", + "type": "boolean" }, "username": { - "description": "Basic auth username. Maximum 50 characters. Ignored unless useBasicAuth is true.", - "type": "string", - "default": "" + "description": "Basic auth username. Maximum 50 characters. Stored as sent, whatever useBasicAuth is set to.", + "type": "string" }, "password": { - "description": "Basic auth password. Maximum 50 characters. Ignored unless useBasicAuth is true.", - "type": "string", - "default": "" + "description": "Basic auth password. Maximum 50 characters. Stored as sent, whatever useBasicAuth is set to, and returned in responses.", + "type": "string" }, "enabled": { "description": "Whether the bot relays messages to its webhook.", - "type": "boolean", - "default": false + "type": "boolean" } }, "type": "object" diff --git a/rest-api/bots.mdx b/rest-api/bots.mdx index fba13a4e2..19fd0332c 100644 --- a/rest-api/bots.mdx +++ b/rest-api/bots.mdx @@ -31,9 +31,10 @@ A **Bot** is an existing user that also has a webhook. Once a bot is enabled, Co - A bot only relays messages while `enabled` is `true`. - Set `useBasicAuth` to `true` to send HTTP basic auth credentials with every webhook call, so your endpoint can verify the caller. - Bots reply through the [Send Bot Message API](/rest-api/messages/send-bot-message), which posts a message as the bot. +- Agents created through [AI Agents](/ai-agents) are not managed by these endpoints. They don't appear in the List Bots response, and Get, Update and Delete return `ERR_BOT_NOT_FOUND` for their UIDs. -When `useBasicAuth` is `true`, the API returns the stored `password` value in responses to Create, List, Get and Update. A `GET /bots` response therefore contains the basic auth credentials of every bot in the app. Treat those responses as secrets, and restrict who can use the API key that reads them. +The API returns a bot's stored `password` in responses to Create, List, Get and Update. This includes bots whose `useBasicAuth` was later set to `false`, because turning it off does not clear the stored credentials. A `GET /bots` response therefore contains the basic auth credentials of every bot in the app. Treat those responses as secrets, and restrict who can use the API key that reads them. ### Relationships @@ -50,22 +51,22 @@ When `useBasicAuth` is `true`, the API returns the stored `password` value in re | **webhookURL** | string | URL that receives the messages relayed to the bot. | | **groupChatSetting** | string | Which group messages are relayed. One of `allMessages`, `slashedMessages`, `mentionedMessages`, `none`. | | **useBasicAuth** | boolean | Whether basic auth credentials are sent with each webhook call. | -| **username** | string | Basic auth username. Stored only when `useBasicAuth` is `true`. | -| **password** | string | Basic auth password. Stored only when `useBasicAuth` is `true`, and returned in responses as stored. | +| **username** | string | Basic auth username. On create, discarded unless `useBasicAuth` is `true`. On update, stored as sent. | +| **password** | string | Basic auth password. On create, discarded unless `useBasicAuth` is `true`. On update, stored as sent. Returned in responses as stored. | | **enabled** | boolean | Whether the bot relays messages to its webhook. Defaults to `false`. | -| **isAIBot** | boolean | Whether this is an AI bot. AI bots are created through AI Agents, and are returned only when you pass `isAIBot=true` to the List Bots API. | +| **isAIBot** | boolean | Whether the bot is flagged as an AI bot. Flagged bots are returned only when you pass `isAIBot=true` to the List Bots API. | | **createdAt** | integer | UNIX timestamp of when the bot was created. | | **updatedAt** | integer | UNIX timestamp of the last update. Absent until the bot is updated. | -Responses omit every property whose value is empty or `false`. A bot with `useBasicAuth` set to `false` has no `useBasicAuth`, `username` or `password` in its response, and a standard bot has no `isAIBot`. +Responses omit every property whose value is empty or `false`, so a standard bot has no `isAIBot`, and a bot that has never had basic auth has no `useBasicAuth`, `username` or `password`. Setting `useBasicAuth` to `false` with the [Update Bot API](/rest-api/bots/update) does not clear stored credentials: the response drops `useBasicAuth` but still contains `username` and `password`. ### Error handling | Error Code | Description | | ---------- | ----------- | -| `ERR_BOT_NOT_FOUND` | No bot exists with the specified UID | +| `ERR_BOT_NOT_FOUND` | No bot exists with the specified UID. Also returned for agents created through AI Agents | | `ERR_UID_NOT_FOUND` | No user exists with the specified UID | | `ERR_PLAN_RESTRICTION` | Your plan does not include bots | | `ERR_BAD_REQUEST` | The request failed validation, for example a duplicate bot UID | diff --git a/rest-api/bots/create.mdx b/rest-api/bots/create.mdx index 86a70fcfc..832777549 100644 --- a/rest-api/bots/create.mdx +++ b/rest-api/bots/create.mdx @@ -17,7 +17,6 @@ A bot's name and avatar belong to its user, not to the bot — set them with the | Webhook URL | 255 characters | Must be a valid URL | | Basic auth username | 50 characters | Ignored unless `useBasicAuth` is `true` | | Basic auth password | 50 characters | Ignored unless `useBasicAuth` is `true` | -| Bots per app | 25 bot users | See [Properties and Constraints](/articles/properties-and-constraints) | When `useBasicAuth` is `true`, the API returns the stored `password` value in the response. The example masks it as `********`; a real response contains the password you sent. diff --git a/rest-api/bots/get.mdx b/rest-api/bots/get.mdx index d78e3518b..5be5ecb5f 100644 --- a/rest-api/bots/get.mdx +++ b/rest-api/bots/get.mdx @@ -3,17 +3,17 @@ openapi: get /bots/{uid} description: "Retrieve the details of a single CometChat bot by UID using the REST API." --- -Returns `ERR_BOT_NOT_FOUND` when no bot exists with this UID, including when the UID belongs to a user who is not a bot. +Returns `ERR_BOT_NOT_FOUND` when no bot exists with this UID. That includes a UID that belongs to a user who is not a bot, and an agent created through [AI Agents](/ai-agents). -Responses omit every property whose value is empty or `false`, so a bot with basic auth turned off has no `useBasicAuth`, `username` or `password`, and a standard bot has no `isAIBot`. +Responses omit every property whose value is empty or `false`, so a standard bot has no `isAIBot`, and a bot that has never had basic auth has no `useBasicAuth`, `username` or `password`. A bot whose `useBasicAuth` was set to `false` after it was saved still returns its stored `username` and `password`. -For an AI bot, the response includes the flag: +For a bot flagged as an AI bot, the response includes the flag: ```json { "data": { - "uid": "research-agent", - "webhookURL": "https://example.com/webhooks/research-agent", + "uid": "faq-bot", + "webhookURL": "https://example.com/webhooks/faq-bot", "groupChatSetting": "mentionedMessages", "enabled": true, "isAIBot": true, @@ -23,7 +23,7 @@ For an AI bot, the response includes the flag: ``` -When `useBasicAuth` is `true`, the API returns the stored `password` value as it was saved. The example masks it as `********`. +The API returns the stored `password` value as it was saved, including after `useBasicAuth` is set to `false`. The example masks it as `********`. For the complete error reference, see [Error Guide](/articles/error-guide). diff --git a/rest-api/bots/list.mdx b/rest-api/bots/list.mdx index b80cf54ca..6662148e1 100644 --- a/rest-api/bots/list.mdx +++ b/rest-api/bots/list.mdx @@ -9,7 +9,9 @@ description: "Retrieve a paginated list of the bots in a CometChat app using the ### Listing AI bots -`isAIBot` defaults to `false`, so this endpoint returns standard bots only. Pass `isAIBot=true` to list AI bots instead — there is no call that returns both at once. AI bots are created through AI Agents. +`isAIBot` defaults to `false`, so this endpoint returns standard bots only. Pass `isAIBot=true` to list bots flagged as AI bots instead — there is no call that returns both at once. + +Agents created through [AI Agents](/ai-agents) are not returned either way. A `GET /bots?isAIBot=true` response looks like this: @@ -17,8 +19,8 @@ A `GET /bots?isAIBot=true` response looks like this: { "data": [ { - "uid": "research-agent", - "webhookURL": "https://example.com/webhooks/research-agent", + "uid": "faq-bot", + "webhookURL": "https://example.com/webhooks/faq-bot", "groupChatSetting": "mentionedMessages", "enabled": true, "isAIBot": true, @@ -40,7 +42,7 @@ A `GET /bots?isAIBot=true` response looks like this: `isAIBot` appears only when it is `true`, because responses omit every property whose value is empty or `false`. That is also why `order-bot` in the response example has no `useBasicAuth`, `username` or `password`. -Bots with `useBasicAuth` set to `true` return their stored `password` in this response, so a single call can expose the basic auth credentials of every bot in the app. The examples mask the value as `********`. +Every bot with a stored `password` returns it in this response, including bots whose `useBasicAuth` was later set to `false`. A single call can therefore expose the basic auth credentials of every bot in the app. The examples mask the value as `********`. For the complete error reference, see [Error Guide](/articles/error-guide). diff --git a/rest-api/bots/update.mdx b/rest-api/bots/update.mdx index 19e67db2e..bc26ed5ae 100644 --- a/rest-api/bots/update.mdx +++ b/rest-api/bots/update.mdx @@ -7,14 +7,16 @@ Every field is optional — send only the ones you want to change. The bot's `ui `groupChatSetting` accepts the same four values as the [Create Bot API](/rest-api/bots/create): `allMessages`, `slashedMessages`, `mentionedMessages` and `none`. -`username` and `password` apply only while `useBasicAuth` is `true`. Setting `enabled` to `false` stops the bot relaying messages without deleting it. +Unlike the Create Bot API, Update stores `username` and `password` as sent, whatever `useBasicAuth` is set to. Setting `useBasicAuth` to `false` stops credentials being sent with webhook calls, but does not clear the stored `username` and `password`. They stay in responses. + +Setting `enabled` to `false` stops the bot relaying messages without deleting it. A bot's name and avatar belong to its user — change them with the [Update User API](/rest-api/users/update). `updatedAt` appears in the response once a bot has been updated. -When `useBasicAuth` is `true`, the API returns the stored `password` value as it was saved. The example masks it as `********`. +The API returns the stored `password` value as it was saved, including after `useBasicAuth` is set to `false`. The example masks it as `********`. For the complete error reference, see [Error Guide](/articles/error-guide).