docs(android)Add card streaming events and update documentation for card messages

docs.json

@@ -4152,7 +4152,6 @@
                               "sdk/android/v5/typing-indicators",
                               "sdk/android/v5/delivery-read-receipts",
                               "sdk/android/v5/transient-messages",
-                              "sdk/android/v5/interactive-messages",
                               "sdk/android/v5/mentions",
                               "sdk/android/v5/reactions"
                             ]
@@ -8348,6 +8347,10 @@
       "source": "/fundamentals/limits",
       "destination": "/rest-api/rate-limits"
     },
+    {
+      "source": "/sdk/android/v5/interactive-messages",
+      "destination": "/sdk/android/v5/send-message"
+    },
     {
       "source": "/sdk/javascript/interactive-messages",
       "destination": "/sdk/javascript/send-message"

sdk/android/ai-agents.mdx

@@ -31,10 +31,10 @@
 
 ## Agent Run Lifecycle and Message Flow
 
-This section explains how a user’s text message to an Agent becomes a structured "run" which emits real-time events and then produces agentic messages for historical retrieval.
+This section explains how a user's text message to an Agent becomes a structured "run" which emits real-time events and then produces agentic messages for historical retrieval.
 - A user sends a text message to an Agent.
 - The platform starts a run and streams real-time events via the **`AIAssistantListener`**.
 - After the run completes, persisted Agentic Messages arrive via the **`MessageListener`**.
 
 ### Real-time Events
 Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantListener`** class as [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) objects in this general order:
@@ -54,7 +54,7 @@
 Notes:
 - `Run Start` and `Run Finished` are always emitted.
 - `Tool Call` events appear only when a backend or frontend tool is invoked. There can be multiple tool calls in a single run.
-- `Text Message` events are always emitted and carry the assistant’s reply incrementally.
+- `Text Message` events are always emitted and carry the assistant's reply incrementally.
 
 <Tabs>
     <Tab title="Java">
@@ -87,17 +87,17 @@
 </Tabs>
 
 #### Event descriptions
-- Run Start: A new run has begun for the user’s message.
+- Run Start: A new run has begun for the user's message.
 - Tool Call Start: The agent decided to invoke a tool.
 - Tool Call Arguments: Arguments being passed to the tool.
 - Tool Call End: Tool execution completed.
-- Tool Call Result: Tool’s output is available.
+- Tool Call Result: Tool's output is available.
 - Text Message Start: The agent started composing a reply.
 - Text Message Content: Streaming content chunks for progressive rendering.
 - Text Message End: The agent reply is complete.
 - Run Finished: The run is finalized; persisted messages will follow.
 
 ### Agentic Messages
 
 These events are received via the **`MessageListener`** after the run completes.
 - `AIAssistantMessage`: The full assistant reply.
@@ -153,7 +153,7 @@
 </Tabs>
 
 
 ## Agentic Message Payload Structures
 
 <Accordion title="AIAssistantMessage Object">
 
@@ -172,7 +172,7 @@
 | `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) |
@@ -203,24 +203,24 @@
     "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"]
 }
@@ -324,7 +324,7 @@
 | `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) |
@@ -390,7 +390,7 @@
 |-----------|------|-------------|
 | `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:**
 
@@ -419,7 +419,7 @@
 | `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 |

sdk/android/v5/ai-agents.mdx

@@ -11,10 +11,10 @@
 
 ## Agent Run Lifecycle and Message Flow
 
-This section explains how a user’s text message to an Agent becomes a structured "run" which emits real-time events and then produces agentic messages for historical retrieval.
+This section explains how a user's text message to an Agent becomes a structured "run" which emits real-time events and then produces agentic messages for historical retrieval.
 - A user sends a text message to an Agent.
 - The platform starts a run and streams real-time events via the **`AIAssistantListener`**.
 - After the run completes, persisted Agentic Messages arrive via the **`MessageListener`**.
 
 ### Real-time Events
 Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantListener`** class in this general order:
@@ -25,16 +25,21 @@
     - Tool Call Arguments
     - Tool Call End
     - Tool Call Result
-3. One or more assistant reply streams:
+3. Zero or more card streams (repeats for each card the agent produces):
+    - Card Start
+    - Card
+    - Card End
+4. One or more assistant reply streams:
     - Text Message Start
     - Text Message Content (multiple times; token/char streaming)
     - Text Message End
-4. Run Finished
+5. Run Finished
 
 Notes:
 - `Run Start` and `Run Finished` are always emitted.
 - `Tool Call` events appear only when a backend or frontend tool is invoked. There can be multiple tool calls in a single run.
-- `Text Message` events are always emitted and carry the assistant’s reply incrementally.
+- `Card` events (`Card Start` → `Card` → `Card End`) appear only when the agent produces a card, and repeat for each card.
+- `Text Message` events are always emitted and carry the assistant's reply incrementally.
 
 <Tabs>
     <Tab title="Java">
@@ -67,17 +72,82 @@
 </Tabs>
 
 #### Event descriptions
-- Run Start: A new run has begun for the user’s message.
+- Run Start: A new run has begun for the user's message.
 - Tool Call Start: The agent decided to invoke a tool.
 - Tool Call Arguments: Arguments being passed to the tool.
 - Tool Call End: Tool execution completed.
-- Tool Call Result: Tool’s output is available.
+- Tool Call Result: Tool's output is available.
+- Card Start: The agent began producing a card; carries a `cardId` and an `executionText` loading label.
+- Card: The full card payload for the given `cardId` is available to render.
+- Card End: The card stream for the given `cardId` is complete.
 - Text Message Start: The agent started composing a reply.
 - Text Message Content: Streaming content chunks for progressive rendering.
 - Text Message End: The agent reply is complete.
 - Run Finished: The run is finalized; persisted messages will follow.
 
+#### Card Streaming Events
+
+When an agent produces a card, it is delivered through three streaming events on `onAIAssistantEventReceived`. Each event is a subclass of `AIAssistantBaseEvent` — check the concrete type to handle it.
+
+| Event | Getter | Description |
+| ----- | ------ | ----------- |
+| `AIAssistantCardStartedEvent` | `getCardId()` | Identifier for the card being generated. |
+| | `getExecutionText()` | Loading label shown while the card is built. |
+| | `getStreamMessageId()` | Identifier of the streaming message that owns this card. |
+| `AIAssistantCardReceivedEvent` | `getCardId()` | Identifier matching the corresponding start event. |
+| | `getCard()` | The complete card payload (`JSONObject`) to render. |
+| `AIAssistantCardEndedEvent` | `getCardId()` | Signals the card stream for this `cardId` is complete. |
+
+<Tabs>
+    <Tab title="Java">
+        ```java
+
+        CometChat.addAIAssistantListener(LISTENERS_TAG, new CometChat.AIAssistantListener() {
+            @Override
+            public void onAIAssistantEventReceived(AIAssistantBaseEvent event) {
+                if (event instanceof AIAssistantCardStartedEvent) {
+                    AIAssistantCardStartedEvent started = (AIAssistantCardStartedEvent) event;
+                    String cardId = started.getCardId();
+                    String label = started.getExecutionText(); // e.g. "Building card…"
+                } else if (event instanceof AIAssistantCardReceivedEvent) {
+                    AIAssistantCardReceivedEvent received = (AIAssistantCardReceivedEvent) event;
+                    String cardId = received.getCardId();
+                    JSONObject card = received.getCard();       // full card payload
+                } else if (event instanceof AIAssistantCardEndedEvent) {
+                    AIAssistantCardEndedEvent ended = (AIAssistantCardEndedEvent) event;
+                    // card stream for ended.getCardId() is complete
+                }
+            }
+        });
+
+        ```
+    </Tab>
+    <Tab title="Kotlin">
+        ```kotlin
+
+        CometChat.addAIAssistantListener(LISTENERS_TAG, object : CometChat.AIAssistantListener() {
+            override fun onAIAssistantEventReceived(event: AIAssistantBaseEvent) {
+                when (event) {
+                    is AIAssistantCardStartedEvent -> {
+                        val cardId = event.cardId
+                        val label = event.executionText  // e.g. "Building card…"
+                    }
+                    is AIAssistantCardReceivedEvent -> {
+                        val cardId = event.cardId
+                        val card = event.card            // full card payload (JSONObject)
+                    }
+                    is AIAssistantCardEndedEvent -> {
+                        // card stream for event.cardId is complete
+                    }
+                }
+            }
+        })
+
+        ```
+    </Tab>
+</Tabs>
+
 ### Agentic Messages
 
 These events are received via the **`MessageListener`** after the run completes.
 - `AIAssistantMessage`: The full assistant reply.
@@ -128,6 +198,63 @@
             }
         })
 
+        ```
+    </Tab>
+</Tabs>
+
+### AIAssistantMessage Elements
+
+Once a run completes, the assistant's reply is persisted as an `AIAssistantMessage`. Its content is exposed as an ordered list of blocks via `getElements()`, letting you render text and cards in the exact order the agent produced them. When `getElements()` is `null` or empty, fall back to the plain `getText()` body.
+
+| Method | Returns | Description |
+| ------ | ------- | ----------- |
+| `getElements()` | `List<AIAssistantElement>` | Ordered content blocks. `null`/empty for plain-text replies. |
+| `getText()` | `String` | Plain-text body (fallback when there are no elements). |
+
+Each `AIAssistantElement` exposes:
+
+| Method | Returns | Description |
+| ------ | ------- | ----------- |
+| `getType()` | `String` | Block type — `"text"` or `"card"`. |
+| `getData()` | `Object` | The block body (text string, or card payload). |
+
+<Tabs>
+    <Tab title="Java">
+        ```java
+
+        List<AIAssistantElement> elements = message.getElements();
+        if (elements == null || elements.isEmpty()) {
+            renderText(message.getText());
+        } else {
+            for (AIAssistantElement element : elements) {
+                switch (element.getType()) {
+                    case "text":
+                        renderText(String.valueOf(element.getData()));
+                        break;
+                    case "card":
+                        renderCard(element.getData());
+                        break;
+                }
+            }
+        }
+
+        ```
+    </Tab>
+    <Tab title="Kotlin">
+        ```kotlin
+
+        val elements = message.elements
+        if (elements.isNullOrEmpty()) {
+            renderText(message.text.orEmpty())
+        } else {
+            for (element in elements) {
+                when (element.type) {
+                    "text" -> renderText(element.data?.toString().orEmpty())
+                    "card" -> renderCard(element.data)
+                }
+            }
+        }
+
         ```
     </Tab>
 </Tabs>