cometchat · hritika-cometchat · Feb 17, 2026 · Feb 17, 2026 · Feb 18, 2026 · Feb 18, 2026
diff --git a/docs.json b/docs.json
@@ -1,13 +1,33 @@
 ---
 title: "AI Agents"
+sidebarTitle: "AI Agents"
+description: "Integrate AI-powered agents for intelligent, automated interactions in the Android SDK"
 ---
 
-# AI Agents Overview
+<Accordion title="AI Integration Quick Reference">
+
+```kotlin
+// Listen for real-time AI events
+CometChat.addAIAssistantListener("LISTENER_ID", object : CometChat.AIAssistantListener() {
+    override fun onAIAssistantEventReceived(event: AIAssistantBaseEvent) {
+        // Handle run start, tool calls, text streaming, run finished
+    }
+})
+
+// Listen for persisted agentic messages
+CometChat.addMessageListener("LISTENER_ID", object : CometChat.MessageListener() {
+    override fun onAIAssistantMessageReceived(message: AIAssistantMessage) { }
+    override fun onAIToolResultReceived(message: AIToolResultMessage) { }
+    override fun onAIToolArgumentsReceived(message: AIToolArgumentMessage) { }
+})
+```
+</Accordion>
 
 AI Agents enable intelligent, automated interactions within your application. They can process user messages, trigger tools, and respond with contextually relevant information. For a broader introduction, see the [AI Agents section](/ai-agents).
 
-> **Note:**
-> Currently, an Agent only responds to **Text Messages**.
+<Note>
+Currently, an Agent only responds to **Text Messages**.
+</Note>
 
 ## Agent Run Lifecycle and Message Flow
 
@@ -130,4 +150,338 @@ These events are received via the **`MessageListener`** after the run completes.
 
         ```
     </Tab>
-</Tabs>
+</Tabs>
+
+
+## Agentic Message Payload Structures
+
+<Accordion title="AIAssistantMessage Object">
+
+The `AIAssistantMessage` object contains the AI assistant's response:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | long | Unique message identifier |
+| `muid` | String | Developer-defined message ID |
+| `sender` | [User](#user-object-ai) | User who sent the message |
+| `receiver` | AppEntity | Message receiver ([User](#user-object-ai) or Group) |
+| `receiverUid` | String | Receiver's unique identifier |
+| `type` | String | Message type. Value: `"assistant"` |
+| `receiverType` | String | Type of receiver. Values: `"user"`, `"group"` |
+| `category` | String | Message category. Value: `"agentic"` |
+| `sentAt` | long | Unix timestamp when sent |
+| `deliveredAt` | long | Unix timestamp when delivered |
+| `readAt` | long | Unix timestamp when read |
+| `metadata` | JSONObject | Custom message metadata |
+| `readByMeAt` | long | When logged-in user read message |
+| `deliveredToMeAt` | long | When delivered to logged-in user |
+| `deletedAt` | long | Unix timestamp when deleted (0 if not deleted) |
+| `editedAt` | long | Unix timestamp when edited (0 if not edited) |
+| `deletedBy` | String | UID of user who deleted (null if not deleted) |
+| `editedBy` | String | UID of user who edited (null if not edited) |
+| `updatedAt` | long | Unix timestamp of last update |
+| `conversationId` | String | Associated conversation ID |
+| `runId` | long | AI run identifier |
+| `threadId` | String | AI thread identifier |
+| `text` | String | AI response text |
+| `tags` | Array\<String\> | Message tags |
+
+**Sample AIAssistantMessage Object:**
+
+```json
+{
+  "id": 12345,
+  "muid": "msg_abc123",
+  "sender": {
+    "uid": "user_123",
+    "name": "John Doe",
+    "avatar": "https://example.com/avatar.png",
+    "status": "online",
+    "role": "default"
+  },
+  "receiver": {
+    "uid": "user_456",
+    "name": "Jane Smith"
+  },
+  "receiverUid": "user_456",
+  "type": "assistant",
+  "receiverType": "user",
+  "category": "agentic",
+  "sentAt": 1699900000,
+  "deliveredAt": 1699900001,
+  "readAt": 1699900002,
+  "metadata": {"priority": "high"},
+  "readByMeAt": 1699900002,
+  "deliveredToMeAt": 1699900001,
+  "deletedAt": 0,
+  "editedAt": 0,
+  "deletedBy": null,
+  "editedBy": null,
+  "updatedAt": 1699900000,
+  "conversationId": "user_123_user_456",
+  "runId": 98765,
+  "threadId": "thread_abc",
+  "text": "Here's the answer...",
+  "tags": ["ai-response"]
+}
+```
+
+</Accordion>
+
+<Accordion title="AIToolArgumentMessage Object">
+
+The `AIToolArgumentMessage` object contains the arguments passed to a tool:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | long | Unique message identifier |
+| `muid` | String | Developer-defined message ID |
+| `sender` | [User](#user-object-ai) | User who sent the message |
+| `receiver` | AppEntity | Message receiver ([User](#user-object-ai) or Group) |
+| `receiverUid` | String | Receiver's unique identifier |
+| `type` | String | Message type. Value: `"tool_arguments"` |
+| `receiverType` | String | Type of receiver. Values: `"user"`, `"group"` |
+| `category` | String | Message category. Value: `"agentic"` |
+| `sentAt` | long | Unix timestamp when sent |
+| `deliveredAt` | long | Unix timestamp when delivered |
+| `readAt` | long | Unix timestamp when read |
+| `metadata` | JSONObject | Custom message metadata |
+| `readByMeAt` | long | When logged-in user read message |
+| `deliveredToMeAt` | long | When delivered to logged-in user |
+| `deletedAt` | long | Unix timestamp when deleted (0 if not deleted) |
+| `editedAt` | long | Unix timestamp when edited (0 if not edited) |
+| `deletedBy` | String | UID of user who deleted (null if not deleted) |
+| `editedBy` | String | UID of user who edited (null if not edited) |
+| `updatedAt` | long | Unix timestamp of last update |
+| `conversationId` | String | Associated conversation ID |
+| `runId` | long | AI run identifier |
+| `threadId` | String | AI thread identifier |
+| `toolCalls` | Array\<[AIToolCall](#aitoolcall-object)\> | List of tool calls |
+| `tags` | Array\<String\> | Message tags |
+
+**Sample AIToolArgumentMessage Object:**
+
+```json
+{
+  "id": 12346,
+  "muid": "msg_tool_arg_123",
+  "sender": {
+    "uid": "user_123",
+    "name": "John Doe",
+    "avatar": "https://example.com/avatar.png",
+    "status": "online",
+    "role": "default"
+  },
+  "receiver": {
+    "uid": "user_456",
+    "name": "Jane Smith"
+  },
+  "receiverUid": "user_456",
+  "type": "tool_arguments",
+  "receiverType": "user",
+  "category": "agentic",
+  "sentAt": 1699900000,
+  "deliveredAt": 1699900001,
+  "readAt": 1699900002,
+  "metadata": {"priority": "high"},
+  "readByMeAt": 1699900002,
+  "deliveredToMeAt": 1699900001,
+  "deletedAt": 0,
+  "editedAt": 0,
+  "deletedBy": null,
+  "editedBy": null,
+  "updatedAt": 1699900000,
+  "conversationId": "user_123_user_456",
+  "runId": 98765,
+  "threadId": "thread_abc",
+  "toolCalls": [
+    {
+      "id": "call_abc123",
+      "name": "search_flights",
+      "arguments": {"origin": "NYC", "destination": "LA"}
+    }
+  ],
+  "tags": ["tool-arguments"]
+}
+```
+
+</Accordion>
+
+<Accordion title="AIToolResultMessage Object">
+
+The `AIToolResultMessage` object contains the result from a tool execution:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | long | Unique message identifier |
+| `muid` | String | Developer-defined message ID |
+| `sender` | [User](#user-object-ai) | User who sent the message |
+| `receiver` | AppEntity | Message receiver ([User](#user-object-ai) or Group) |
+| `receiverUid` | String | Receiver's unique identifier |
+| `type` | String | Message type. Value: `"tool_result"` |
+| `receiverType` | String | Type of receiver. Values: `"user"`, `"group"` |
+| `category` | String | Message category. Value: `"agentic"` |
+| `sentAt` | long | Unix timestamp when sent |
+| `deliveredAt` | long | Unix timestamp when delivered |
+| `readAt` | long | Unix timestamp when read |
+| `metadata` | JSONObject | Custom message metadata |
+| `readByMeAt` | long | When logged-in user read message |
+| `deliveredToMeAt` | long | When delivered to logged-in user |
+| `deletedAt` | long | Unix timestamp when deleted (0 if not deleted) |
+| `editedAt` | long | Unix timestamp when edited (0 if not edited) |
+| `deletedBy` | String | UID of user who deleted (null if not deleted) |
+| `editedBy` | String | UID of user who edited (null if not edited) |
+| `updatedAt` | long | Unix timestamp of last update |
+| `conversationId` | String | Associated conversation ID |
+| `runId` | long | AI run identifier |
+| `threadId` | String | AI thread identifier |
+| `text` | String | Tool result text |
+| `toolCallId` | String | ID of the tool call that produced this result |
+| `tags` | Array\<String\> | Message tags |
+
+**Sample AIToolResultMessage Object:**
+
+```json
+{
+  "id": 12347,
+  "muid": "msg_tool_result_123",
+  "sender": {
+    "uid": "user_123",
+    "name": "John Doe",
+    "avatar": "https://example.com/avatar.png",
+    "status": "online",
+    "role": "default"
+  },
+  "receiver": {
+    "uid": "user_456",
+    "name": "Jane Smith"
+  },
+  "receiverUid": "user_456",
+  "type": "tool_result",
+  "receiverType": "user",
+  "category": "agentic",
+  "sentAt": 1699900000,
+  "deliveredAt": 1699900001,
+  "readAt": 1699900002,
+  "metadata": {"priority": "high"},
+  "readByMeAt": 1699900002,
+  "deliveredToMeAt": 1699900001,
+  "deletedAt": 0,
+  "editedAt": 0,
+  "deletedBy": null,
+  "editedBy": null,
+  "updatedAt": 1699900000,
+  "conversationId": "user_123_user_456",
+  "runId": 98765,
+  "threadId": "thread_abc",
+  "text": "Flight found: NYC to LA...",
+  "toolCallId": "call_abc123",
+  "tags": ["tool-result"]
+}
+```
+
+</Accordion>
+
+<Accordion title="AIToolCall Object">
+
+The `AIToolCall` object represents a single tool invocation:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | String | Unique identifier for the tool call |
+| `name` | String | Name of the tool being called |
+| `arguments` | JSONObject | Arguments passed to the tool |
+
+**Sample AIToolCall Object:**
+
+```json
+{
+  "id": "call_abc123",
+  "name": "search_flights",
+  "arguments": {
+    "origin": "NYC",
+    "destination": "LA",
+    "date": "2024-01-15"
+  }
+}
+```
+
+</Accordion>
+
+<Accordion title="User Object (AI)">
+
+The nested `User` object in `sender` contains:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uid` | String | Unique identifier of the user |
+| `name` | String | Display name of the user |
+| `avatar` | String | URL to user's profile picture |
+| `link` | String | URL to user's profile page |
+| `role` | String | User role for access control |
+| `metadata` | JSONObject | Custom data set by developer |
+| `status` | String | User online status. Values: `"online"`, `"offline"` |
+| `statusMessage` | String | Custom status message |
+| `lastActiveAt` | long | Unix timestamp of last activity |
+| `hasBlockedMe` | boolean | Whether this user has blocked the logged-in user |
+| `blockedByMe` | boolean | Whether the logged-in user has blocked this user |
+| `tags` | Array\<String\> | List of tags for user identification |
+| `deactivatedAt` | long | Unix timestamp when user was deactivated (0 if active) |
+
+**Sample User Object:**
+
+```json
+{
+  "uid": "user_123",
+  "name": "John Doe",
+  "avatar": "https://example.com/avatar.png",
+  "link": "https://example.com/profile/user_123",
+  "role": "default",
+  "metadata": {"department": "engineering"},
+  "status": "online",
+  "statusMessage": "Available",
+  "lastActiveAt": 1699900000,
+  "hasBlockedMe": false,
+  "blockedByMe": false,
+  "tags": ["premium"],
+  "deactivatedAt": 0
+}
+```
+
+</Accordion>
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Always Remove AI Listeners">
+    Remove AI assistant and message listeners in `onDestroy()` or `onPause()` to prevent memory leaks. Use unique listener IDs to manage multiple listeners effectively.
+  </Accordion>
+  <Accordion title="Handle Streaming Content Progressively">
+    Use `Text Message Content` events to render AI responses incrementally as they arrive. This provides a better user experience than waiting for the complete response.
+  </Accordion>
+  <Accordion title="Display Tool Call Information">
+    Show users when the agent is invoking tools (e.g., "Searching for flights...") using `Tool Call Start` and `Tool Call End` events. This provides transparency about agent actions.
+  </Accordion>
+  <Accordion title="Store Agentic Messages for History">
+    Persist `AIAssistantMessage`, `AIToolResultMessage`, and `AIToolArgumentMessage` objects locally to display conversation history when users return to the chat.
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="AI Agents Overview" icon="robot" href="/ai-agents">
+    Learn about AI agent capabilities and configuration
+  </Card>
+  <Card title="Send Message" icon="paper-plane" href="/sdk/android/send-message">
+    Send text messages to AI agents to trigger runs
+  </Card>
+  <Card title="Receive Messages" icon="envelope" href="/sdk/android/receive-messages">
+    Handle incoming messages including AI responses
+  </Card>
+  <Card title="Dashboard" icon="gauge" href="https://app.cometchat.com">
+    Configure and manage AI agents in the CometChat Dashboard
+  </Card>
+</CardGroup>
@@ -1,4 +1,10 @@
 ---
-title: "AI"
+title: "AI Chatbots"
+sidebarTitle: "AI Chatbots"
+description: "Implement custom AI chatbots for automated conversations in your Android application"
 url: "/ai-chatbots/overview"
----
+---
+
+AI Chatbots enable automated conversations within your application. They can process user messages and respond with contextually relevant information. For a broader introduction, see the [AI Chatbots section](/ai-chatbots).
+
+For message payload structures (AIAssistantMessage, AIToolArgumentMessage, AIToolResultMessage), see the [AI Agents](/sdk/android/ai-agents#agentic-message-payload-structures) page.