diff --git a/chat-apis.json b/chat-apis.json
index 33890e75c..9d89d0680 100644
--- a/chat-apis.json
+++ b/chat-apis.json
@@ -1131,6 +1131,423 @@
]
}
},
+ "/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": "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
+ }
+ },
+ {
+ "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"
+ },
+ "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. Setting this to false does not clear a stored username or password.",
+ "type": "boolean"
+ },
+ "username": {
+ "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. 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"
+ }
+ },
+ "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 +21983,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..19fd0332c
--- /dev/null
+++ b/rest-api/bots.mdx
@@ -0,0 +1,76 @@
+---
+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.
+- 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.
+
+
+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
+
+- **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. 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 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`, 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. 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 |
+
+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..832777549
--- /dev/null
+++ b/rest-api/bots/create.mdx
@@ -0,0 +1,25 @@
+---
+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`.
+
+`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).
+
+## 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` |
+
+
+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..5be5ecb5f
--- /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. 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 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 a bot flagged as an AI bot, the response includes the flag:
+
+```json
+{
+ "data": {
+ "uid": "faq-bot",
+ "webhookURL": "https://example.com/webhooks/faq-bot",
+ "groupChatSetting": "mentionedMessages",
+ "enabled": true,
+ "isAIBot": true,
+ "createdAt": 1763472000
+ }
+}
+```
+
+
+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
new file mode 100644
index 000000000..6662148e1
--- /dev/null
+++ b/rest-api/bots/list.mdx
@@ -0,0 +1,48 @@
+---
+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 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:
+
+```json
+{
+ "data": [
+ {
+ "uid": "faq-bot",
+ "webhookURL": "https://example.com/webhooks/faq-bot",
+ "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 `order-bot` in the response example has no `useBasicAuth`, `username` or `password`.
+
+
+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
new file mode 100644
index 000000000..bc26ed5ae
--- /dev/null
+++ b/rest-api/bots/update.mdx
@@ -0,0 +1,22 @@
+---
+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`.
+
+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.
+
+
+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).