cometchat · swapnil-cometchat · Jun 14, 2026 · Jun 15, 2026 · Jun 15, 2026 · Jun 15, 2026
diff --git a/ai-chatbots/custom-agents.mdx b/ai-chatbots/custom-agents.mdx
@@ -7,6 +7,24 @@ In CometChat, custom agents are unique users capable of autonomously sending and
 
 Users can interact with agents through private one-on-one conversations or within group chats. When an agent receives a message, whether from an individual chat or a group, CometChat relays that message to a `Callback URL` that you configure. Upon receiving the message, you can process it according to your business logic and send a response using CometChat's API.
 
+<Note>
+A **custom agent** lets you bring your own backend and AI logic — CometChat only forwards messages to your callback URL and posts your responses back. If you would rather configure an agent (tools, knowledge base, MCP servers) without running your own orchestration, use CometChat's native [Agent Builder APIs](/rest-api/ai-agents-apis/overview) instead.
+</Note>
+
+The flow at a glance:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CometChat
+    participant Your Server
+    User->>CometChat: Sends a message to the agent
+    CometChat->>Your Server: HTTP POST to your Callback URL (JSON)
+    Your Server->>Your Server: Apply your business logic
+    Your Server->>CometChat: Send Bot Message REST API (agent's reply)
+    CometChat->>User: Delivers the agent's reply
+```
+
 ## Create a callback endpoint
 
 ### Callback endpoint requirements
@@ -57,4 +75,25 @@ The actual development and behavior of the agent are completely in your hands. A
 
 ### Responding as an agent
 
-After your bot's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so.
+After your agent's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so. This API posts a message authored by the agent's UID (`POST /bots/{uid}/messages`).
+
+<Note>
+The exact JSON shape CometChat POSTs to your Callback URL is not documented on this page. Log the incoming request body from your endpoint to inspect it, or contact the CometChat team for the current payload reference.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom Bots" icon="robot" href="/ai-chatbots/custom-bots">
+    Configure a custom bot the same way as a custom agent.
+  </Card>
+  <Card title="Send Bot Message (REST API)" icon="paper-plane" href="/rest-api/messages/send-bot-message">
+    Post the agent's reply back into the conversation.
+  </Card>
+  <Card title="Create User (REST API)" icon="user-plus" href="/rest-api/users/create">
+    Create the user account that backs the agent.
+  </Card>
+  <Card title="Agent Builder APIs" icon="wand-magic-sparkles" href="/rest-api/ai-agents-apis/overview">
+    Build native agents with tools and knowledge bases instead.
+  </Card>
+</CardGroup>
diff --git a/ai-chatbots/custom-bots.mdx b/ai-chatbots/custom-bots.mdx
@@ -7,6 +7,24 @@ In CometChat, Custom bots are unique users capable of autonomously sending and r
 
 Users can interact with bots through private one-on-one conversations or within group chats. When a bot receives a message, whether from an individual chat or a group, CometChat relays that message to a `Callback URL` that you configure. Upon receiving the message, you can process it according to your business logic and send a response using CometChat's API.
 
+<Note>
+A **custom bot** lets you bring your own backend and logic — CometChat only forwards messages to your callback URL and posts your responses back. If you would rather configure an agent (tools, knowledge base, MCP servers) without running your own orchestration, use CometChat's native [Agent Builder APIs](/rest-api/ai-agents-apis/overview) instead.
+</Note>
+
+The flow at a glance:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CometChat
+    participant Your Server
+    User->>CometChat: Sends a message to the bot
+    CometChat->>Your Server: HTTP POST to your Callback URL (JSON)
+    Your Server->>Your Server: Apply your business logic
+    Your Server->>CometChat: Send Bot Message REST API (bot's reply)
+    CometChat->>User: Delivers the bot's reply
+```
+
 ## Create a callback endpoint
 
 ### Callback endpoint requirements
@@ -57,4 +75,25 @@ The actual development and behavior of the bot are completely in your hands. All
 
 ### Responding as a bot
 
-After your bot's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so.
+After your bot's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so. This API posts a message authored by the bot's UID (`POST /bots/{uid}/messages`).
+
+<Note>
+The exact JSON shape CometChat POSTs to your Callback URL is not documented on this page. Log the incoming request body from your endpoint to inspect it, or contact the CometChat team for the current payload reference.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom Agents" icon="robot" href="/ai-chatbots/custom-agents">
+    Configure a custom agent the same way as a custom bot.
+  </Card>
+  <Card title="Send Bot Message (REST API)" icon="paper-plane" href="/rest-api/messages/send-bot-message">
+    Post the bot's reply back into the conversation.
+  </Card>
+  <Card title="Create User (REST API)" icon="user-plus" href="/rest-api/users/create">
+    Create the user account that backs the bot.
+  </Card>
+  <Card title="Agent Builder APIs" icon="wand-magic-sparkles" href="/rest-api/ai-agents-apis/overview">
+    Build native agents with tools and knowledge bases instead.
+  </Card>
+</CardGroup>
diff --git a/articles/docker.mdx b/articles/docker.mdx
@@ -3,22 +3,32 @@ title: "Docker"
 description: "Docker — CometChat documentation."
 ---
 
-It is suggested to be familiar with the various kinds of roles for the on-premise deployment.
+This guide describes how to deploy CometChat on-premise as a **Docker Swarm** cluster. The deployment spans several machines, each running a specific role (master, storage, calling, websocket, worker nodes, and extensions). Before you begin, it is suggested to be familiar with these roles.
+
+<Note>
+On-premise deployment relies on artifacts and an On-Premise Token provided directly by CometChat (the bootstrap scripts and the `cometchatpro-onprem-dockerswarm` folder referenced below). If you do not have these yet, contact CometChat to start the on-premise process.
+</Note>
+
+## Prerequisites
+
+- Machines provisioned to meet the hardware requirements in the table below, with network connectivity between them.
+- Docker with Docker Compose installed on every machine (see step 3).
+- The on-premise package and On-Premise Token shared by CometChat (see steps 4 and 5).
 
 ## 1. Hardware required for Docker Swarm
 
-Below is the list of hardware required that you will need to provision.
+Below is the list of machines you will need to provision. Each row is a **role** in the Swarm cluster; the *Requires Public IP* and *Open Public Ports* columns indicate which machines must be reachable from the internet.
 
-| Minimum CPU | Minimum RAM | Minimum Storage | Requires Public IP | VM  | Open Public Ports                         |
-| ----------- | ----------- | --------------- | ------------------ | --- | ----------------------------------------- |
-| master      | 8 core      | 32GB            | 250GB              | Yes | TCP: 80,443                               |
-| storage1    | 8 core      | 32GB            | 250GB              | No  |                                           |
-| storage2    | 8 core      | 32GB            | 250GB              | No  |                                           |
-| calling     | 8 core      | 32GB            | 50GB               | Yes | TCP: 80,443, 10000-20000 UDP: 10000-20000 |
-| websocket   | 8 core      | 32GB            | 50GB               | Yes | TCP: 80,443,7070,5222,5223                |
-| node1       | 4 core      | 8GB             | 50GB               | No  |                                           |
-| node2       | 4 core      | 8GB             | 50GB               | No  |                                           |
-| extensions  | 4 core      | 8GB             | 50GB               | Yes | TCP: 80, 443                              |
+| Role / Machine | Minimum CPU | Minimum RAM | Minimum Storage | Requires Public IP | Open Public Ports                         |
+| -------------- | ----------- | ----------- | --------------- | ------------------ | ----------------------------------------- |
+| master         | 8 core      | 32GB        | 250GB           | Yes                | TCP: 80,443                               |
+| storage1       | 8 core      | 32GB        | 250GB           | No                 |                                           |
+| storage2       | 8 core      | 32GB        | 250GB           | No                 |                                           |
+| calling        | 8 core      | 32GB        | 50GB            | Yes                | TCP: 80,443, 10000-20000 UDP: 10000-20000 |
+| websocket      | 8 core      | 32GB        | 50GB            | Yes                | TCP: 80,443,7070,5222,5223                |
+| node1          | 4 core      | 8GB         | 50GB            | No                 |                                           |
+| node2          | 4 core      | 8GB         | 50GB            | No                 |                                           |
+| extensions     | 4 core      | 8GB         | 50GB            | Yes                | TCP: 80, 443                              |
 
 ## 2. Once the hardware and public IP's are ready
 
@@ -89,3 +99,12 @@ cd cometchatpro-onprem-dockerswarm-1.0.0
 #on extensions
 ._extensions_bootstrap.sh
 ```
+
+<Note>
+Run the bootstrap script that matches each machine's role, using the exact script names included in the on-premise package shared by CometChat. If a script name in the package differs from what is shown here, follow the package. Once every machine is bootstrapped, return to the **master** node to complete the final bootstrap step with CometChat.
+</Note>
+
+## Related
+
+- [Properties and Constraints](/articles/properties-and-constraints)
+- [Rate Limits](/articles/rate-limits)
diff --git a/chat-builder/android/builder-customisations.mdx b/chat-builder/android/builder-customisations.mdx
@@ -19,9 +19,13 @@ The Android UI Kit Builder uses two main files for customization:
 | `BuilderSettingsHelper.kt` | Utility class that applies settings to UI components | Component-level customizations |
 
 <Info>
-  `CometChatBuilderSettings.kt` is auto-generated by the Builder plugin from your `cometchat-builder-settings.json` file. You can modify the values directly in the Kotlin file, but changes will be overwritten if you rebuild with the plugin.
+  `CometChatBuilderSettings.kt` is auto-generated by the Builder plugin from your `cometchat-builder-settings.json` file. You can modify the values directly in the Kotlin file, but changes will be overwritten if you rebuild with the plugin. For changes that should survive a rebuild, edit `cometchat-builder-settings.json` (feature toggles) or `themes.xml` (styling) instead.
 </Info>
 
+<Note>
+  The two files above cover Builder-level customization. Because the Builder sits on top of the standard [CometChat Android UI Kit](/ui-kit/android/getting-started), you can go further using the UI Kit's own customization layers — **Message Templates**, **View Slots**, and **DataSource decorators**. See [Beyond Builder Settings](#beyond-builder-settings-deeper-ui-kit-customization) below.
+</Note>
+
 ---
 
 ## Using BuilderSettingsHelper
@@ -379,6 +383,27 @@ You can customize individual component styles by overriding their style attribut
 
 ---
 
+## Beyond Builder Settings: Deeper UI Kit Customization
+
+`BuilderSettingsHelper` and `themes.xml` cover feature toggles and broad styling. When you need to change the *structure* or *behavior* of a component — not just whether a feature is on — use the standard UI Kit customization layers. The Builder applies its settings to the same UI Kit components, so these layers compose with it.
+
+| Layer | Use it when you want to… | Reference |
+| ----- | ------------------------ | --------- |
+| **Message Templates** | Change a message bubble's structure, content/header/reply views, or bubble interactions | [Message Template](/ui-kit/android/message-template) |
+| **View Slots** | Replace a specific region of a list item — avatar, title, subtitle, trailing section, or the entire row | [View Slots](/ui-kit/android/customization-view-slots) |
+| **DataSource & ChatConfigurator** | Globally override how messages render, which options appear on bubbles, and which attachment actions appear in the composer | [DataSource & ChatConfigurator](/ui-kit/android/customization-datasource) |
+| **Style classes & attributes** | Override individual component style attributes beyond the brand color and font themes | [Component Styling](/ui-kit/android/component-styling) |
+
+<Tip>
+  Read the [Customization Overview](/ui-kit/android/customization-overview) first. It explains the View + ViewModel + Adapter architecture that all of these layers build on.
+</Tip>
+
+<Note>
+  These layers belong to the underlying UI Kit, not the Builder plugin. Apply them in the same Activity/Fragment where you call `BuilderSettingsHelper`, after the component is inflated. Call order generally does not matter for visibility flags, but if a template or slot and a Builder setting target the same region, the more specific UI Kit customization wins. Verify the exact precedence for your case against the linked reference pages.
+</Note>
+
+---
+
 ## Next Steps
 
 <CardGroup cols={2}>

diff --git a/chat-builder/android/builder-dir-structure.mdx b/chat-builder/android/builder-dir-structure.mdx
@@ -178,6 +178,10 @@ Drawable resources including icons, shapes, and backgrounds.
   Prefer using `CometChatBuilderSettings.kt` for feature toggles and `themes.xml` for styling. For extensive changes, extend existing components instead of modifying core files directly.
 </Note>
 
+<Note>
+  `CometChatBuilderSettings.kt` is regenerated from `cometchat-builder-settings.json` on every Gradle build, so edits there are not preserved across rebuilds. Keep feature changes in the JSON and visual changes in `themes.xml`. For structural changes to components (custom bubbles, list-item regions, global message overrides), use the underlying UI Kit's [Message Templates](/ui-kit/android/message-template), [View Slots](/ui-kit/android/customization-view-slots), and [DataSource](/ui-kit/android/customization-datasource) layers rather than editing generated files.
+</Note>
+
 ---
 
 ## Next Steps

diff --git a/chat-builder/android/builder-settings.mdx b/chat-builder/android/builder-settings.mdx
@@ -7,9 +7,13 @@ description: "Configure Android UI Kit Builder settings for messaging, AI helper
 The `CometChatBuilderSettings` object controls everything the Android UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This object is auto-generated by the UI Kit Builder Settings Gradle plugin from your `cometchat-builder-settings.json` configuration file.
 
 <Info>
-  **For developers customizing their chat UI**: The `CometChatBuilderSettings.kt` file is generated automatically when you build your project. Edit the `cometchat-builder-settings.json` file to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/chat-builder/android/integration) for setup.
+  **For developers customizing their chat UI**: The `CometChatBuilderSettings.kt` file is generated automatically when you build your project. Edit the `cometchat-builder-settings.json` file to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/chat-builder/android/integration) for setup, and [Customizations](/chat-builder/android/builder-customisations) for how the generated constants are applied to components via `BuilderSettingsHelper`.
 </Info>
 
+<Note>
+  These settings control feature toggles, layout, and broad styling. For structural or behavioral customization beyond what the JSON exposes — custom bubbles, list-item regions, or global message overrides — use the underlying UI Kit's [Message Templates](/ui-kit/android/message-template), [View Slots](/ui-kit/android/customization-view-slots), and [DataSource](/ui-kit/android/customization-datasource) layers. The Builder applies its settings to the same UI Kit components, so these layers compose with it.
+</Note>
+
 ## Top-level Structure
 
 The generated `CometChatBuilderSettings` object in Kotlin follows this structure:
@@ -401,4 +405,16 @@ Some features require additional configuration in the [CometChat Dashboard](http
   >
     Modify component props, styling, and behavior for deeper customization.
   </Card>
+  <Card
+    title="Theming"
+    href="/ui-kit/android/theme-introduction"
+  >
+    Go beyond brand color and font with full colors, typography, and style attributes.
+  </Card>
+  <Card
+    title="Customization Overview"
+    href="/ui-kit/android/customization-overview"
+  >
+    Learn the UI Kit architecture and all deeper customization entry points.
+  </Card>
 </CardGroup>
-Original file line number
+Diff line change
@@ Expand Up @@
       Prefer using `CometChatBuilderSettings.kt` for feature toggles and `themes.xml` for styling. For extensive changes, extend existing components instead of modifying core files directly.
     </Note>
+    <Note>
+      `CometChatBuilderSettings.kt` is regenerated from `cometchat-builder-settings.json` on every Gradle build, so edits there are not preserved across rebuilds. Keep feature changes in the JSON and visual changes in `themes.xml`. For structural changes to components (custom bubbles, list-item regions, global message overrides), use the underlying UI Kit's [Message Templates](/ui-kit/android/message-template), [View Slots](/ui-kit/android/customization-view-slots), and [DataSource](/ui-kit/android/customization-datasource) layers rather than editing generated files.
+    </Note>
     ---
     ## Next Steps
@@ Expand Down @@