Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
421 changes: 421 additions & 0 deletions chat-apis.json

Large diffs are not rendered by default.

11 changes: 11 additions & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
76 changes: 76 additions & 0 deletions rest-api/bots.mdx
Original file line number Diff line number Diff line change
@@ -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).

Check warning on line 6 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L6

Did you really mean 'bot's'?

### 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.

Check warning on line 34 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L34

Did you really mean 'UIDs'?

<Warning>
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.

Check warning on line 37 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L37

Did you really mean 'bot's'?
</Warning>

### 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).

Check warning on line 44 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L44

Did you really mean 'walkthrough'?

### Bot properties

| Property | Type | Description |
| -------- | ---- | ----------- |
| **uid** | string | UID of the user this bot belongs to. Forced to lowercase. |

Check warning on line 50 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L50

Did you really mean 'uid'?
| **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. |

Check warning on line 57 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L57

Did you really mean 'isAIBot'?
| **createdAt** | integer | UNIX timestamp of when the bot was created. |

Check warning on line 58 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L58

Did you really mean 'createdAt'?
| **updatedAt** | integer | UNIX timestamp of the last update. Absent until the bot is updated. |

Check warning on line 59 in rest-api/bots.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots.mdx#L59

Did you really mean 'updatedAt'?

<Note>
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`.
</Note>

### 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).
25 changes: 25 additions & 0 deletions rest-api/bots/create.mdx
Original file line number Diff line number Diff line change
@@ -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).

Check warning on line 10 in rest-api/bots/create.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots/create.mdx#L10

Did you really mean 'bot's'?

## 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` |

<Warning>
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.
</Warning>

For the complete error reference, see [Error Guide](/articles/error-guide).
12 changes: 12 additions & 0 deletions rest-api/bots/delete.mdx
Original file line number Diff line number Diff line change
@@ -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).
29 changes: 29 additions & 0 deletions rest-api/bots/get.mdx
Original file line number Diff line number Diff line change
@@ -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
}
}
```

<Warning>
The API returns the stored `password` value as it was saved, including after `useBasicAuth` is set to `false`. The example masks it as `********`.
</Warning>

For the complete error reference, see [Error Guide](/articles/error-guide).
48 changes: 48 additions & 0 deletions rest-api/bots/list.mdx
Original file line number Diff line number Diff line change
@@ -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.

Check warning on line 6 in rest-api/bots/list.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots/list.mdx#L6

Did you really mean 'bot's'?

`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`.

<Warning>
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 `********`.
</Warning>

For the complete error reference, see [Error Guide](/articles/error-guide).
22 changes: 22 additions & 0 deletions rest-api/bots/update.mdx
Original file line number Diff line number Diff line change
@@ -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."

Check warning on line 3 in rest-api/bots/update.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots/update.mdx#L3

Did you really mean 'bot's'?
---

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.

Check warning on line 6 in rest-api/bots/update.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots/update.mdx#L6

Did you really mean 'bot's'?

`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).

Check warning on line 14 in rest-api/bots/update.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

rest-api/bots/update.mdx#L14

Did you really mean 'bot's'?

`updatedAt` appears in the response once a bot has been updated.

<Warning>
The API returns the stored `password` value as it was saved, including after `useBasicAuth` is set to `false`. The example masks it as `********`.
</Warning>

For the complete error reference, see [Error Guide](/articles/error-guide).