> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> 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](https://www.cometchat.com/docs/rest-api/messages/send-bot-message.md).

### Endpoints

| Method | Endpoint | Description |
| - | - | - |
| POST | [`/bots`](https://www.cometchat.com/docs/rest-api/bots/create) | Create a new bot |
| GET | [`/bots`](https://www.cometchat.com/docs/rest-api/bots/list) | List all bots |
| GET | [`/bots/{uid}`](https://www.cometchat.com/docs/rest-api/bots/get) | Get a specific bot |
| PUT | [`/bots/{uid}`](https://www.cometchat.com/docs/rest-api/bots/update) | Update a bot |
| DELETE | [`/bots/{uid}`](https://www.cometchat.com/docs/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](https://www.cometchat.com/docs/rest-api/users.md); 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](https://www.cometchat.com/docs/rest-api/messages/send-bot-message.md), which posts a message as the bot.
* Agents created through [AI Agents](https://www.cometchat.com/docs/ai-agents.md) 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.

> [!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.

### Relationships

* **Users** — A bot is a [User](https://www.cometchat.com/docs/rest-api/users.md) with a webhook attached. Its name and avatar belong to the user, so change them with the [Update User API](https://www.cometchat.com/docs/rest-api/users/update.md).
* **Send Bot Message** — Use the [Send Bot Message API](https://www.cometchat.com/docs/rest-api/messages/send-bot-message.md) 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](https://www.cometchat.com/docs/ai-chatbots/custom-bots.md).

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

> [!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](https://www.cometchat.com/docs/rest-api/bots/update.md) 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](https://www.cometchat.com/docs/articles/error-guide.md).

For all system limits (bot caps, UID length, etc.), see [Properties and Constraints](https://www.cometchat.com/docs/articles/properties-and-constraints.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.