cometchat · aanshisingh-cometchat · Jul 3, 2026
diff --git a/docs.json b/docs.json
@@ -538,6 +538,7 @@
                                   "ui-kit/react/components/sticker-bubble",
                                   "ui-kit/react/components/collaborative-document-bubble",
                                   "ui-kit/react/components/collaborative-whiteboard-bubble",
+                                  "ui-kit/react/components/card-bubble",
                                   "ui-kit/react/components/call-bubble",
                                   "ui-kit/react/components/call-action-bubble",
                                   "ui-kit/react/components/group-action-bubble",

@@ -5,11 +5,11 @@

 ## Architecture

 The UI Kit provides a set of independent, composable React components that wire together into complete chat layouts. A typical two-panel layout uses four core components:

 - **CometChatConversations** — sidebar listing recent conversations
 - **CometChatMessageHeader** — toolbar showing avatar, name, status, and typing indicator
 - **CometChatMessageList** — scrollable message feed with reactions, receipts, and threads
 - **CometChatMessageComposer** — rich text input with attachments, mentions, and voice notes

 Data flow: selecting a conversation yields a `CometChat.User` or `CometChat.Group` object. Pass that object as a prop (`user` or `group`) to the message components. They handle SDK calls internally — the composer sends messages, the list receives them via real-time listeners.
@@ -63,7 +63,7 @@

 ## Compound Composition

 For full layout control, use the compound pattern. Each feature component is a namespace with sub-components:

 ```tsx
 <CometChatConversations.Root onItemClick={handleClick}>
@@ -111,7 +111,7 @@

 | Component | Purpose | Page |
 | --- | --- | --- |
 | `CometChatConversations` | Scrollable list of recent conversations with real-time updates | [Conversations](/ui-kit/react/components/conversations) |
 | `CometChatUsers` | Searchable list of users with selection support | [Users](/ui-kit/react/components/users) |
 | `CometChatGroups` | Searchable list of groups with selection support | [Groups](/ui-kit/react/components/groups) |
 | `CometChatGroupMembers` | List of group members with role-based actions | [Group Members](/ui-kit/react/components/group-members) |
@@ -121,7 +121,7 @@
 | Component | Purpose | Page |
 | --- | --- | --- |
 | `CometChatMessageHeader` | Toolbar with avatar, name, status, typing indicator, and call buttons | [Message Header](/ui-kit/react/components/message-header) |
 | `CometChatMessageList` | Scrollable message feed with plugin-based bubble rendering | [Message List](/ui-kit/react/components/message-list) |
 | `CometChatMessageComposer` | Rich text input with attachments, emoji, voice recording, and formatting | [Message Composer](/ui-kit/react/components/message-composer) |
 | `CometChatMessageBubble` | Message bubble container with alignment, receipts, options, and reactions | [Message Bubble](/ui-kit/react/components/message-bubble) |
 | `CometChatThreadHeader` | Parent message bubble and reply count for threaded conversations | [Thread Header](/ui-kit/react/components/thread-header) |
@@ -145,6 +145,7 @@
 | `CometChatStickerBubble` | `extension_sticker` | Sticker image display | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) |
 | `CometChatCollaborativeDocumentBubble` | `extension_document` | Document collaboration link with join button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) |
 | `CometChatCollaborativeWhiteboardBubble` | `extension_whiteboard` | Whiteboard collaboration link with join button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) |
+| `CometChatCardBubble` | `card` (category) | Developer-defined card messages drawn by the `CometChatCardView` renderer | [Card Bubble](/ui-kit/react/components/card-bubble) |
 | `CometChatGroupActionBubble` | `groupMember` | Group membership system messages (joined, left, kicked, banned, scope change) | [Group Action Bubble](/ui-kit/react/components/group-action-bubble) |
 | `CometChatCallActionBubble` | `audio`, `video` (call category) | Call status system messages (missed, outgoing, incoming, ended) | [Call Action Bubble](/ui-kit/react/components/call-action-bubble) |
 | `CometChatCallBubble` | `meeting` (custom) | Direct call / meeting invitation bubble | [Call Bubble](/ui-kit/react/components/call-bubble) |
@@ -156,7 +157,7 @@
 | `CometChatCallButtons` | Voice and video call initiation buttons | [Call Buttons](/ui-kit/react/components/call-buttons) |
 | `CometChatIncomingCall` | Incoming call notification with accept/decline | [Incoming Call](/ui-kit/react/components/incoming-call) |
 | `CometChatOutgoingCall` | Outgoing call screen with cancel control | [Outgoing Call](/ui-kit/react/components/outgoing-call) |
 | `CometChatCallLogs` | Scrollable list of call history | [Call Logs](/ui-kit/react/components/call-logs) |

 ### Search and AI


@@ -0,0 +1,191 @@
+---
+title: "Card Bubble"
+sidebarTitle: "Card Bubble"
+description: "A render-only bubble that draws developer-defined card messages (category \"card\") with the prebuilt CometChatCardView renderer and forwards card actions to your app."
+---
+
+<Accordion title="AI Integration Quick Reference">
+```json
+{
+  "component": "CometChatCardBubble",
+  "package": "@cometchat/chat-uikit-react",
+  "import": "import { CometChatCardBubble } from \"@cometchat/chat-uikit-react\";",
+  "description": "Render-only bubble for developer card messages (category \"card\"). Stringifies the raw payload from message.getCard() and hands it to the prebuilt CometChatCardView renderer, then forwards user actions back to the app. It never parses, mutates, or acts on the card itself.",
+  "cssRootClass": ".cometchat-card-bubble",
+  "renderOnly": true,
+  "props": {
+    "data": {
+      "message": { "type": "CometChat.CardMessage", "required": true, "note": "The developer card message (category \"card\"). Drives message.getCard()." },
+      "themeMode": { "type": "CometChatCardThemeMode", "default": "\"auto\"", "note": "Theme mode forwarded to CometChatCardView." },
+      "themeOverride": { "type": "CometChatCardThemeOverride", "note": "Optional theme overrides forwarded to the renderer." },
+      "onCardAction": { "type": "(message: CometChat.BaseMessage, action: CometChatCardAction) => void", "note": "Direct callback for card actions, fired in addition to the ui:card/action event." }
+    }
+  }
+}
+```
+</Accordion>
+
+## Overview
+
+`CometChatCardBubble` renders a **card message** — a message with `category: "card"`. A card message carries a block of Card Schema JSON that is created and sent server-side (via the Platform (REST) API or the Dashboard Bubble Builder) and delivered to clients like any other message. Card messages are **receive-only**: the UI Kit renders them, it does not send them.
+
+The bubble is **render-only**, mirroring `CometChatTextBubble`: the kit performs zero transformation. It stringifies the raw payload from `message.getCard()` and hands it to the prebuilt [`CometChatCardView`](https://www.npmjs.com/package/@cometchat/cards-react) renderer (`@cometchat/cards-react`), then forwards user actions back to your app. It never parses or mutates the card body, and never performs an action itself — your app owns all action behavior (opening URLs, navigating to chats, API calls, etc.).
+
+In the message list, card messages are routed to this bubble automatically by the built-in **Card plugin** — no configuration is required. See [Plugins → Built-in Plugins](/ui-kit/react/plugins/overview#built-in-plugins).
+
+### Where cards fit in the message hierarchy
+
+`card` is a top-level message category, alongside `message`, `custom`, `action`, and `call`.
+
+<Frame>
+  <img src="/images/message-structure-hierarchy-card.svg" />
+</Frame>
+
+---
+
+## Usage
+
+Card messages render automatically inside `CometChatMessageList`. To render one directly — for example in a custom layout — pass the SDK `CardMessage` to the bubble:
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import { CometChatCardBubble } from "@cometchat/chat-uikit-react";
+
+function CardMessageItem({ message }: { message: CometChat.CardMessage }) {
+  return <CometChatCardBubble message={message} />;
+}
+```
+
+To receive card actions without going through the [event bus](/ui-kit/react/event-system), pass an `onCardAction` callback:
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import {
+  CometChatCardBubble,
+  type CometChatCardAction,
+} from "@cometchat/chat-uikit-react";
+
+function CardMessageItem({ message }: { message: CometChat.CardMessage }) {
+  const handleAction = (
+    msg: CometChat.BaseMessage,
+    action: CometChatCardAction
+  ) => {
+    // Your app owns the behavior — open a URL, start a call, call an API, etc.
+    console.log("Card action", action, "on message", msg.getId());
+  };
+
+  return <CometChatCardBubble message={message} onCardAction={handleAction} />;
+}
+```
+
+---
+
+## Props
+
+### message
+
+The developer card message (`category: "card"`). The bubble reads the raw card payload from `message.getCard()`. **Required.**
+
+| | |
+| --- | --- |
+| Type | `CometChat.CardMessage` |
+| Required | Yes |
+
+---
+
+### themeMode
+
+Theme mode forwarded to the `CometChatCardView` renderer.
+
+| | |
+| --- | --- |
+| Type | `CometChatCardThemeMode` |
+| Default | `"auto"` |
+
+---
+
+### themeOverride
+
+Optional theme overrides forwarded to the renderer.
+
+| | |
+| --- | --- |
+| Type | `CometChatCardThemeOverride` |
+| Default | `undefined` |
+
+---
+
+### onCardAction
+
+Direct callback for card actions. Fired **in addition to** the `ui:card/action` UI event, so an app embedding the bubble directly can receive actions without subscribing to the event bus. Receives the message and the clicked action.
+
+| | |
+| --- | --- |
+| Type | `(message: CometChat.BaseMessage, action: CometChatCardAction) => void` |
+| Default | `undefined` |
+
+---
+
+## Card Actions
+
+When a user clicks an action inside a card (a button, link, etc.), the bubble forwards the raw action to your app through **two** channels — it never handles the action itself:
+
+1. The optional [`onCardAction`](#oncardaction) prop, when provided.
+2. The [`ui:card/action`](/ui-kit/react/event-system#card-actions) UI event, published on the event bus with the `message` and the clicked `action`. This is the only channel that can reach a card rendered by the kit (e.g. a nested agent card) where no prop is reachable.
+
+Subscribe to the event anywhere in your app:
+
+```tsx
+import { useCometChatEvents } from "@cometchat/chat-uikit-react";
+
+function CardActionListener() {
+  useCometChatEvents((event) => {
+    if (event.type === "ui:card/action") {
+      // event.message, event.action
+      console.log("Card action clicked:", event.action);
+    }
+  });
+
+  return null;
+}
+```
+
+---
+
+## Fallback
+
+When `message.getCard()` is absent or empty, the renderer is **not** invoked. Instead the bubble renders a plain-text fallback, resolving the first available of:
+
+1. `message.getFallbackText()`
+2. `message.getText()`
+3. The localized `"Card Message"` string
+
+---
+
+## CSS Selectors
+
+| Target | Selector |
+| --- | --- |
+| Root | `.cometchat-card-bubble` |
+| Text fallback | `.cometchat-card-bubble__fallback` |
+
+The card body itself is styled by the `CometChatCardView` renderer; use `themeMode` / `themeOverride` to theme it.
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Plugins" icon="puzzle-piece" href="/ui-kit/react/plugins/overview#built-in-plugins">
+    How the Card plugin routes card messages to this bubble
+  </Card>
+  <Card title="Event System" icon="bolt" href="/ui-kit/react/event-system#card-actions">
+    Subscribe to the ui:card/action event
+  </Card>
+  <Card title="Message Bubble" icon="comment" href="/ui-kit/react/components/message-bubble">
+    The wrapper that hosts bubble content
+  </Card>
+  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
+    Customize colors, fonts, and spacing
+  </Card>
+</CardGroup>
@@ -11,7 +11,7 @@
 | Publish hook | `const publish = usePublishEvent()` |
 | Provider | `CometChatEventsProvider` (mounted automatically by `CometChatProvider` after login) |
 | Event prefix | SDK events: `message/`, `receipt/`, `user/`, `group/`, `call/`, `connection/` |
-| UI event prefix | `ui:message/`, `ui:compose/`, `ui:group/`, `ui:call/`, `ui:thread/`, `ui:conversation/` |
+| UI event prefix | `ui:message/`, `ui:compose/`, `ui:group/`, `ui:call/`, `ui:thread/`, `ui:conversation/`, `ui:card/` |
 
 </Accordion>
 
@@ -72,7 +72,7 @@
 }
 ```

 The hook automatically subscribes on mount and unsubscribes on unmount. No cleanup needed.

 ---

@@ -114,6 +114,7 @@
 | `message/media-received` | `{ message: MediaMessage }` | Media message received |
 | `message/custom-received` | `{ message: CustomMessage }` | Custom message received |
 | `message/interactive-received` | `{ message: InteractiveMessage }` | Interactive message received |
+| `message/card-received` | `{ message: BaseMessage }` | Card message (`category: "card"`) received |
 | `message/edited` | `{ message: BaseMessage }` | Message was edited |
 | `message/deleted` | `{ message: BaseMessage }` | Message was deleted |
 | `message/moderated` | `{ message: BaseMessage }` | Message was moderated |
@@ -247,6 +248,14 @@
 | --- | --- | --- |
 | `ui:open-chat` | `{ user?, group? }` | MessageList (message privately option) |
 
+### Card Actions
+
+| Event Type | Payload | Published by |
+| --- | --- | --- |
+| `ui:card/action` | `{ message, action }` | [Card Bubble](/ui-kit/react/components/card-bubble) (user clicks a card action) |
+
+Published when a user clicks an action (button, link, etc.) inside a card message bubble. The kit performs no behavior — it forwards the raw `action` and its `message` to your app, so you own all action handling. This is the only channel that can reach a kit-instantiated card (e.g. a nested agent card) where no prop is reachable.
+
 ### Panels
 
 | Event Type | Payload | Published by |

@@ -41,7 +41,7 @@
 | `renderBubble` | `(message, context) => ReactNode` | Yes | Render the inner bubble content (the outer wrapper is handled by `CometChatMessageBubble`) |
 | `getOptions` | `(message, context) => CometChatMessageOption[]` | Optional | Context menu options for the message (return `[]` for none) |
 | `getLastMessagePreview` | `(message, loggedInUser, t?) => string` | Optional | Plain-text subtitle shown in the Conversations list |
 | `getTextFormatters` | `() => CometChatTextFormatter[]` | Optional | Text formatters this plugin provides (only the text plugin uses this) |
 | `renderLeadingView` | `(message, context) => ReactNode` | Optional | Override the leading view (avatar area) |
 | `renderHeaderView` | `(message, context) => ReactNode` | Optional | Override the header view (sender name area) |
 | `renderFooterView` | `(message, context) => ReactNode` | Optional | Override the footer view (reactions area) |
@@ -97,7 +97,7 @@
 | Plugin | Message type(s) | Category | What it renders | Component |
 | --- | --- | --- | --- | --- |
 | **Text** | `text` | `message` | Formatted text with @mentions, clickable URLs, and markdown | [Text Bubble](/ui-kit/react/components/text-bubble) |
 | **Image** | `image` | `message` | Responsive image grid with captions and a fullscreen viewer | [Image Bubble](/ui-kit/react/components/image-bubble) |
 | **Video** | `video` | `message` | Inline player (single) or thumbnail grid with play overlays (multiple) | [Video Bubble](/ui-kit/react/components/video-bubble) |
 | **File** | `file` | `message` | File card with name, size, type icon, and download | [File Bubble](/ui-kit/react/components/file-bubble) |
 | **Audio** | `audio` | `message` | Audio player with waveform, play/pause, duration, and download | [Audio Bubble](/ui-kit/react/components/audio-bubble) |
@@ -105,6 +105,7 @@
 | **Stickers** | `extension_sticker` | `custom` | Sticker image extracted from the message metadata | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) |
 | **Collaborative Document** | `extension_document` | `custom` | Document card with an "Open Document" button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) |
 | **Collaborative Whiteboard** | `extension_whiteboard` | `custom` | Whiteboard card with an "Open Whiteboard" button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) |
+| **Card** | any | `card` | Developer-defined card messages, drawn by the `CometChatCardView` renderer | [Card Bubble](/ui-kit/react/components/card-bubble) |
 | **Group Action** | `groupMember` | `action` | Centered system messages (joined, left, kicked, banned, scope change) | [Group Action Bubble](/ui-kit/react/components/group-action-bubble) |
 | **Call Action** | `audio` / `video` | `call` | Centered call status messages (missed, outgoing, incoming, ended) | [Call Action Bubble](/ui-kit/react/components/call-action-bubble) |
 | **Meeting** | `meeting` | `custom` | Group/conference call invite card with a **Join** button | [Call Bubble](/ui-kit/react/components/call-bubble) |
@@ -137,9 +138,9 @@
 | `toolArguments` | "Tool call" |
 | `toolResults` | "Tool result" |

 ### Preloading

 The AI Assistant Chat panel can be preloaded on hover/focus to reduce perceived latency:

 ```tsx
 import { preloadAIAssistantChat } from "@cometchat/chat-uikit-react";