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