docs(react-native): document Card Message support for SDK and UI Kit

sdk/react-native/ai-agents.mdx

@@ -1,7 +1,7 @@
 ---
 title: "AI Agents"
 sidebarTitle: "AI Agents"
 description: "Integrate AI Agents into your React Native app using the CometChat SDK, including real-time event streaming and agentic message handling."
 ---
 
 <Accordion title="AI Integration Quick Reference">
@@ -43,7 +43,7 @@
 
 When a user sends a text message to an Agent:
 1. The platform starts a run and streams real-time events via `AIAssistantListener`
 2. After the run completes, persisted Agentic Messages arrive via `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:
@@ -57,13 +57,16 @@
 | 3 | Tool Call Arguments | Arguments being passed to the tool |
 | 4 | Tool Call End | Tool execution completed |
 | 5 | Tool Call Result | Tool's output is available |
-| 6 | Text Message Start | Agent started composing a reply |
-| 7 | Text Message Content | Streaming content chunks (multiple) |
-| 8 | Text Message End | Agent reply is complete |
-| 9 | Run Finished | Run finalized; persisted messages follow |
+| 6 | Card Start | Agent started generating a card |
+| 7 | Card | Full card payload is available |
+| 8 | Card End | Card generation is complete |
+| 9 | Text Message Start | Agent started composing a reply |
+| 10 | Text Message Content | Streaming content chunks (multiple) |
+| 11 | Text Message End | Agent reply is complete |
+| 12 | Run Finished | Run finalized; persisted messages follow |
 
 <Note>
-`Run Start` and `Run Finished` are always emitted. Tool Call events only appear when tools are invoked — there can be multiple tool call cycles in a single run. Text Message events are always emitted and carry the assistant's reply incrementally.
+`Run Start` and `Run Finished` are always emitted. Tool Call events only appear when tools are invoked — there can be multiple tool call cycles in a single run. Card events (`Card Start` → `Card` → `Card End`) only appear when the agent produces a card, and may repeat for each card. Text Message events are always emitted and carry the assistant's reply incrementally.
 </Note>
 
 ### Event Object Properties
@@ -88,11 +91,14 @@
 | Text Message Content | `getDelta()` | The streaming text chunk for progressive rendering |
 | Tool Call Arguments | `getToolCallId()`, `getDelta()` | Tool call ID and argument chunk |
 | Tool Call Result | `getToolCallId()`, `getContent()`, `getRole()` | Tool call ID, result content, and role |
+| Card Start | `getCardId()`, `getExecutionText()`, `getStreamMessageId()` | Card ID, a human-readable status string, and the stream message ID |
+| Card | `getCardId()`, `getCard()`, `getStreamMessageId()` | Card ID, the raw card payload, and the stream message ID |
+| Card End | `getCardId()`, `getStreamMessageId()` | Card ID and the stream message ID |
 
 <Tabs>
 <Tab title="TypeScript">
 ```ts
         const listnerId: string = "unique_listener_id";
 
         // Adding the AIAssistantListener
         CometChat.addAIAssistantListener(listnerId, {
@@ -108,7 +114,7 @@
 
 <Tab title="JavaScript">
 ```js
         const listnerId = "unique_listener_id";
 
         // Adding the AIAssistantListener
         CometChat.addAIAssistantListener(listnerId, {
@@ -125,7 +131,7 @@
 </Tabs>
 
 <Warning>
 Always remove AI Assistant listeners when the component unmounts to prevent memory leaks.
 ```javascript
 CometChat.removeAIAssistantListener("unique_listener_id");
 ```
@@ -137,12 +143,68 @@
 - Tool Call Arguments: Arguments being passed to the tool.
 - Tool Call End: Tool execution completed.
 - Tool Call Result: Tool's output is available.
+- Card Start: The agent started generating a card. Carries `cardId` and `executionText` (a human-readable status like "Building your product card...").
+- Card: The full card payload is available. Use `getCard()` to retrieve the raw card JSON and pass it to the renderer.
+- Card End: The card generation flow is finalized.
 - 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 the agent generates a card, the run emits a card cycle (`Card Start` → `Card` → `Card End`). All three are `AIAssistantBaseEvent` subclasses delivered through the same `onAIAssistantEventReceived` callback — no separate listener is required.
+
+| Class | Event type (`getType()`) | Getters |
+|-------|--------------------------|---------|
+| `AIAssistantCardStartedEvent` | `card_start` | `getCardId()`, `getExecutionText()`, `getStreamMessageId()` |
+| `AIAssistantCardReceivedEvent` | `card` | `getCardId()`, `getCard()`, `getStreamMessageId()` |
+| `AIAssistantCardEndedEvent` | `card_end` | `getCardId()`, `getStreamMessageId()` |
+
+<Tabs>
+<Tab title="TypeScript">
+```typescript
+CometChat.addAIAssistantListener("unique_listener_id", {
+  onAIAssistantEventReceived: (event: CometChat.AIAssistantBaseEvent) => {
+    if (event instanceof CometChat.AIAssistantCardStartedEvent) {
+      console.log("Card generation started:", event.getCardId());
+      console.log("Execution text:", event.getExecutionText());
+    } else if (event instanceof CometChat.AIAssistantCardReceivedEvent) {
+      console.log("Card received:", event.getCardId());
+      const cardPayload = event.getCard();
+      // Pass cardPayload to your card renderer
+    } else if (event instanceof CometChat.AIAssistantCardEndedEvent) {
+      console.log("Card generation ended:", event.getCardId());
+    }
+  },
+});
+```
+
+</Tab>
+
+<Tab title="JavaScript">
+```javascript
+CometChat.addAIAssistantListener("unique_listener_id", {
+  onAIAssistantEventReceived: (event) => {
+    if (event instanceof CometChat.AIAssistantCardStartedEvent) {
+      console.log("Card generation started:", event.getCardId());
+      console.log("Execution text:", event.getExecutionText());
+    } else if (event instanceof CometChat.AIAssistantCardReceivedEvent) {
+      console.log("Card received:", event.getCardId());
+      const cardPayload = event.getCard();
+      // Pass cardPayload to your card renderer
+    } else if (event instanceof CometChat.AIAssistantCardEndedEvent) {
+      console.log("Card generation ended:", event.getCardId());
+    }
+  },
+});
+```
+
+</Tab>
+
+</Tabs>
+
 ### Agentic Messages
 
 After the run completes, these messages arrive via `MessageListener`:
 
@@ -152,7 +214,7 @@
 | `AIToolResultMessage` | The final output of a tool call |
 | `AIToolArgumentMessage` | The arguments passed to a tool |
 
 Each message type extends [`BaseMessage`](/sdk/reference/messages#basemessage) and has a typed data accessor:
 
 | Message Type | Data Getter | Data Properties |
 |--------------|-------------|-----------------|
@@ -217,9 +279,86 @@
 </Tabs>
 
 <Warning>
 Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling.
 </Warning>
 
+### AIAssistantMessage Elements
+
+Starting from React Native SDK **4.0.26**, a persisted `AIAssistantMessage` carries its content as an ordered list of blocks via `getElements()`. This is the preferred render source — when present, walk the list in order and render each block. If the agent response contains only a card (no accompanying text), the text returned by `getAssistantMessageData().getText()` will be empty, so always prefer `getElements()`.
+
+`getElements()` returns an array of `AIAssistantElement` (or `null` for older messages without elements). Each element exposes:
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `getType()` | `string` | The block type, e.g. `"text"` or `"card"`. Determines the shape of `getData()`. |
+| `getData()` | `string \| object` | The block's raw body. `"text"` → `string`; `"card"` → `{ card, cardId }`; other types → raw JSON value. The SDK never interprets this — it returns the value as-is. |
+
+<Tabs>
+<Tab title="TypeScript">
+```typescript
+function handleAIAssistantMessage(message: CometChat.AIAssistantMessage) {
+  const elements = message.getElements();
+
+  if (elements && elements.length > 0) {
+    // Preferred path: walk elements in order
+    elements.forEach((element: CometChat.AIAssistantElement) => {
+      switch (element.getType()) {
+        case "text":
+          console.log("Text block:", element.getData());
+          break;
+        case "card": {
+          const { card, cardId } = element.getData() as {
+            card: object;
+            cardId: string;
+          };
+          console.log("Card block:", cardId);
+          // Pass card to your card renderer
+          break;
+        }
+        default:
+          console.log("Unknown element type:", element.getType());
+      }
+    });
+  } else {
+    // Fallback for older messages without elements
+    console.log("Message text:", message.getAssistantMessageData().getText());
+  }
+}
+```
+
+</Tab>
+
+<Tab title="JavaScript">
+```javascript
+function handleAIAssistantMessage(message) {
+  const elements = message.getElements();
+
+  if (elements && elements.length > 0) {
+    elements.forEach((element) => {
+      switch (element.getType()) {
+        case "text":
+          console.log("Text block:", element.getData());
+          break;
+        case "card": {
+          const { card, cardId } = element.getData();
+          console.log("Card block:", cardId);
+          // Pass card to your card renderer
+          break;
+        }
+        default:
+          console.log("Unknown element type:", element.getType());
+      }
+    });
+  } else {
+    console.log("Message text:", message.getAssistantMessageData().getText());
+  }
+}
+```
+
+</Tab>
+
+</Tabs>
+
 ---
 
 ## Next Steps

sdk/react-native/campaigns.mdx

@@ -47,7 +47,7 @@
     { "type": "button", "id": "btn_1", "label": "Shop Now", "action": { "type": "openUrl", "url": "https://..." } }
   ],
   "style": { "background": {"light": "#FFFFFF", "dark": "#1E1E1E"}, "borderRadius": 12, "padding": 16 },
   "fallbackText": "Flash Sale! Shop Now: https://..."
 }
 ```
 
@@ -153,7 +153,7 @@
 <Tabs>
 <Tab title="JavaScript">
 ```javascript
 const categoriesRequest = new CometChat.NotificationCategoriesRequestBuilder()
   .setLimit(50)
   .build();
 
@@ -389,7 +389,7 @@
 <Tabs>
 <Tab title="JavaScript">
 ```javascript
 const pushNotification = new CometChat.PushNotification(pushPayloadJson);
 
 CometChat.markPushNotificationDelivered(pushNotification).then(
   () => { /* Success */ },
@@ -485,10 +485,10 @@
             // Open URL in browser
             break;
           case "chatWithUser":
             // Navigate to chat with event.params.uid
             break;
           case "chatWithGroup":
             // Navigate to group chat with event.params.guid
             break;
         }
       }}
@@ -509,12 +509,62 @@
 
 | Action Type | Parameters | Description |
 | --- | --- | --- |
 | `openUrl` | url, openIn | Open a URL in browser or webview |
 | `chatWithUser` | uid | Navigate to 1:1 chat |
 | `chatWithGroup` | guid | Navigate to group chat |
 | `sendMessage` | text, receiverUid, receiverGuid | Send a text message |
 | `copyToClipboard` | value | Copy text to clipboard |
 | `downloadFile` | url, filename | Download a file |
 | `initiateCall` | callType (audio/video), uid, guid | Start a call |
 | `apiCall` | url, method, headers, body | Make an HTTP request |
 | `customCallback` | callbackId, payload | App-specific logic |
+
+---
+
+## Card Messages
+
+Besides the notification feed, the **same Card Schema JSON** can arrive as a chat message. A `CardMessage` is a message with `category: "card"` — created and sent via the Platform (REST) API or the Dashboard Bubble Builder. The SDK only **receives** card messages; it does not send them.
+
+Card messages are delivered through the `onCardMessageReceived` callback of the [`MessageListener`](/sdk/react-native/real-time-listeners#message-listener), not through the notification feed listener. The payload from `getCard()` is the same Card Schema JSON described above, so you render it with the same [`CometChatCardView`](#rendering-cards) and handle the same [card actions](#supported-card-actions).
+
+### CardMessage Fields
+
+| Method | Return Type | Description |
+| --- | --- | --- |
+| `getCard()` | object | The raw Card Schema JSON payload. Pass directly to the Cards renderer. |
+| `getText()` | string | Preview text for push notifications and the conversation list. |
+| `getFallbackText()` | string | Fallback text from inside the card (`card.fallbackText`), used for accessibility or when the renderer fails. |
+| `getTags()` | `Array<string>` | Tags associated with this message. |
+
+<Tabs>
+<Tab title="TypeScript">
+```typescript
+CometChat.addMessageListener("unique_listener_id", {
+  onCardMessageReceived: (cardMessage: CometChat.CardMessage) => {
+    console.log("Card message received:", cardMessage.getId());
+    const cardJson: string = JSON.stringify(cardMessage.getCard()); // same schema as feed cards
+    const fallback: string = cardMessage.getFallbackText();
+    const previewText: string = cardMessage.getText();
+    // Pass cardJson to CometChatCardView
+  },
+});
+```
+</Tab>
+<Tab title="JavaScript">
+```javascript
+CometChat.addMessageListener("unique_listener_id", {
+  onCardMessageReceived: (cardMessage) => {
+    console.log("Card message received:", cardMessage.getId());
+    const cardJson = JSON.stringify(cardMessage.getCard()); // same schema as feed cards
+    const fallback = cardMessage.getFallbackText();
+    const previewText = cardMessage.getText();
+    // Pass cardJson to CometChatCardView
+  },
+});
+```
+</Tab>
+</Tabs>
+
+<Note>
+Card messages are **receive-only**. They are created and sent exclusively via the Platform (REST) API and Dashboard Bubble Builder. The SDK exposes the raw payload via `getCard()` — the CometChat Cards library is responsible for drawing the card UI.
+</Note>