cometchat · mathews-cometchat · Jun 25, 2026 · Jun 28, 2026 · Jun 28, 2026
diff --git a/ai-agents/ag-ui-card-messages.mdx b/ai-agents/ag-ui-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your AG-UI BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/ai-agents/ag2-card-messages.mdx b/ai-agents/ag2-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your AG2 BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/ai-agents/agent-builder/card-messages.mdx b/ai-agents/agent-builder/card-messages.mdx
@@ -0,0 +1,59 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your agent reply with rich, interactive cards — designed in Card Builder — instead of plain text."
+---
+
+The **Card Messages** tool lets your agent reply with flexible, interactive cards — buttons, images, progress bars, layouts — instead of plain text. You design each card once in [Card Builder](/card-builder/overview) so it always renders uniformly, then tell the agent when to send it.
+
+## Enable the Card Messages tool
+
+1. Open your agent and go to **Tools**.
+2. Find **Card Messages** (a built-in system tool) and toggle it **on**.
+3. A **Design interactive cards with Card Builder** prompt appears — click **Open Card Builder** to start designing.
+
+## How it works
+
+Card Messages is a built-in **system tool**. When you enable it, the agent can call the tool to fetch a **card reference — working examples plus a field reference** (describing the structure documented in the [Card JSON Schema](/card-builder/schema)) — and then generate a conforming card in its reply.
+
+That means the agent *can* compose cards freely — but free-form generation drifts in layout and styling from one reply to the next. To keep every card consistent, **design it once in Card Builder and give the agent the exported JSON** to reuse, as shown below.
+
+<Note>
+You supply **what** card to send — the **how** is automatic. Enabling the tool also teaches the agent the format CometChat uses to recognize a card in its reply, so cards render with no extra work. This holds even when you paste a predefined card into the Instructions: keep the tool **on** — that's what supplies the format. With the tool off, pasted card JSON won't render as a card.
+</Note>
+
+<Note>
+A reply is delivered as an ordered sequence of **elements** — plain-text segments and at most **one card**. So an agent can send a card on its own, or with text before and/or after it, in a single reply. To present multiple sections *inside* the card, use layout elements (`row`, `column`, `grid`, `tabs`, `accordion`) rather than sending a second card.
+</Note>
+
+## Design a card and add it to your agent
+
+Once the tool is on, the workflow is:
+
+1. **Design your card** visually in [Card Builder](/card-builder/overview) — see [Building an Order Status Card](/card-builder/example-order-status) for a full walkthrough.
+2. Use **Export → Copy Card JSON** to copy the finished card.
+3. Add the JSON to the agent's **[Instructions](/ai-agents/agent-builder/instructions)** and specify **when** to send it.
+
+<Note>
+A fixed card renders exactly as designed. If it includes `{{placeholder}}` variables, instruct the agent to fill them in before sending.
+</Note>
+
+<Tip>
+With several card types, you can return the card JSON from a **[Custom API Tool](/ai-agents/agent-builder/tools/overview)** instead of pasting it into the instructions — keeping the agent's instructions concise and focused.
+</Tip>
+
+## Design cards in Card Builder
+
+Card Builder is the visual editor where you compose and save your cards.
+
+<CardGroup>
+  <Card title="Open Card Builder" icon="window-restore" href="/card-builder/overview">
+    Learn the editor — palette, canvas, elements, actions, and variables.
+  </Card>
+  <Card title="Worked example" icon="list-check" href="/card-builder/example-order-status">
+    Build an interactive Order Status card from scratch, step by step.
+  </Card>
+  <Card title="Card JSON Schema" icon="code" href="/card-builder/schema">
+    The complete schema a card's JSON must conform to.
+  </Card>
+</CardGroup>
diff --git a/ai-agents/agno-card-messages.mdx b/ai-agents/agno-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your Agno BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/ai-agents/crew-ai-card-messages.mdx b/ai-agents/crew-ai-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your CrewAI BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/ai-agents/langgraph-card-messages.mdx b/ai-agents/langgraph-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your LangGraph BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/ai-agents/mastra-card-messages.mdx b/ai-agents/mastra-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your Mastra BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/ai-agents/vercel-card-messages.mdx b/ai-agents/vercel-card-messages.mdx
@@ -0,0 +1,9 @@
+---
+title: "Card Messages"
+sidebarTitle: "Card Messages"
+description: "Let your Vercel AI BYOA agent reply with rich, interactive cards designed in Card Builder."
+---
+
+import CardMessages from '/snippets/ai-agents/card-messages.mdx';
+
+<CardMessages />
diff --git a/card-builder/building-cards.mdx b/card-builder/building-cards.mdx
@@ -0,0 +1,92 @@
+---
+title: "Building Cards"
+sidebarTitle: "Building Cards"
+description: "Walk through the Card Builder editor — the canvas, the element palette, and the properties panel — to design, style, and save a card in the CometChat Dashboard."
+---
+
+This guide walks through designing a card in Card Builder, from a blank canvas to a saved template.
+
+<Frame>
+  <video autoPlay loop muted playsInline className="w-full rounded-xl" aria-label="Building a card in Card Builder — adding a progress bar and status rows with variables" src="/images/card-builder/build-2-details.mp4" />
+</Frame>
+
+## The Editor
+
+Card Builder is organized into three areas:
+
+| Area | What it does |
+| --- | --- |
+| **Palette** (left) | The elements and ready-made components you can add to a card. |
+| **Canvas** (center) | A live preview of your card as you build it. Select an element here to edit it. |
+| **Properties** (right) | Settings for the selected element, the card structure (tree), and overall card style. |
+
+The top bar holds the card name, import and export, undo/redo, and **Save**.
+
+<Frame>
+  <img src="/images/card-builder/editor.png" alt="Card Builder editor: the element palette on the left, the card canvas in the center, and the structure tree and properties on the right" />
+</Frame>
+
+## 1. Start a Card
+
+When you open Card Builder, choose a starting point:
+
+- **Template library** — pick a ready-made template (Product Card, Order Confirmation, and more) and customize it.
+- **Blank card** — start from scratch.
+
+<Frame>
+  <img src="/images/card-builder/template-library.png" alt="The Card Builder template library, showing saved templates and ready-made templates to start from" />
+</Frame>
+
+## 2. Add Elements
+
+Click an element in the palette to add it to your card. New elements are placed relative to your current selection — inside a selected layout element, or after the selected element. You can add content such as text, images, and buttons, and arrange them using layout elements like rows, columns, and grids. For the full list, see [Elements & Actions](/card-builder/elements).
+
+You can also add a **component** — a pre-built group of elements (for example a product card or an order timeline) — and then edit its pieces.
+
+## 3. Arrange the Layout
+
+By default, elements stack vertically. To change the layout:
+
+- **Row** — place elements side by side.
+- **Column** — group elements vertically inside a row.
+- **Grid** — arrange elements in a grid.
+- **Carousel** — let users scroll horizontally through items.
+
+Use the structure tree in the properties panel to drag elements into a new order, nest them inside layouts, or remove them.
+
+## 4. Style the Card
+
+Select an element to edit its properties, or click an empty area of the card to edit the overall **card style**:
+
+- **Background** — set a fill color, or make it transparent.
+- **Corner radius** — round the card's corners.
+- **Border** — add a border color and width.
+- **Padding** — control the spacing inside the card.
+
+### Light and Dark Mode
+
+Colors are set separately for **light** and **dark** mode, so your card looks right in both. You can set a color for one mode and leave the other transparent.
+
+## 5. Make It Interactive
+
+Add an **action** to a button, icon button, link, or chip so it does something when tapped — open a URL, start a chat, send a message, make a call, and more. See [Elements & Actions](/card-builder/elements#actions) for the full list.
+
+## 6. Use Variables
+
+Insert [variables](/card-builder/elements#variables) — placeholders such as `{{user.name}}` or `{{order.id}}` — from the variable picker wherever you enter text or a URL. They're filled with real values when the card is sent, so a single card personalizes for every recipient. Available variables depend on where the card is used.
+
+## 7. Notifications (Push)
+
+A card is a message in CometChat. When that message triggers a push notification, the push can't show the full rich card — so the **Notification** tab is where you define the **notification text** for the message: the title and body shown in the push. A device preview shows how it will appear, and you can insert [variables](#6-use-variables) into the title and body so the notification is personalized per recipient.
+
+<Frame>
+  <img src="/images/card-builder/notification.png" alt="The Notification tab in Card Builder, with a device preview showing how the push notification appears" />
+</Frame>
+
+## 8. Save
+
+Give the card a name in the top bar and click **Save**. Saved cards are stored as templates so you can open them again from the template library, edit them, and reuse them.
+
+---
+
+Next: [Elements & Actions](/card-builder/elements) — a reference of everything you can add to a card.
diff --git a/card-builder/elements.mdx b/card-builder/elements.mdx
@@ -0,0 +1,91 @@
+---
+title: "Elements & Actions"
+sidebarTitle: "Elements & Actions"
+description: "A reference of everything a card can contain — content, layout, and interactive elements, the actions a card can trigger, and the ready-made components you can add to a card."
+---
+
+A card is made up of **elements** arranged on the canvas. Interactive elements can trigger **actions**, and **components** give you ready-made groups of elements to start from. This page lists what's available.
+
+## Elements
+
+### Content
+
+| Element | Description |
+| --- | --- |
+| **Text** | A line or paragraph of text, with heading and body styles. |
+| **Markdown** | Rich text written in Markdown. |
+| **Image** | An image from a URL. |
+| **Icon** | An icon from the built-in library or a custom image. |
+| **Avatar** | A circular user or entity image. |
+| **Badge** | A small label, often for status or counts. |
+| **Chip** | A compact, tappable tag. |
+| **Code block** | Pre-formatted, monospaced text. |
+
+### Layout
+
+| Element | Description |
+| --- | --- |
+| **Row** | Arranges elements side by side. |
+| **Column** | Groups elements vertically, usually inside a row. |
+| **Grid** | Arranges elements in a grid. |
+| **Accordion** | Collapsible sections that expand on tap. |
+| **Tabs** | Switch between sections of content. |
+| **Divider** | A horizontal line to separate content. |
+| **Spacer** | Empty space to control vertical rhythm. |
+
+Rows, columns, and grids can also have their own background color, corner radius, and border.
+
+### Interactive
+
+| Element | Description |
+| --- | --- |
+| **Button** | A labeled button that triggers an action. |
+| **Icon button** | An icon-only button that triggers an action. |
+| **Link** | Tappable text that triggers an action. |
+
+### Data
+
+| Element | Description |
+| --- | --- |
+| **Table** | Rows and columns of structured data. |
+| **Progress bar** | A visual indicator of progress. |
+
+## Actions
+
+Add an action to a button, icon button, link, or chip to make it interactive. When a user taps the element, the action runs.
+
+| Action | What it does |
+| --- | --- |
+| **Open URL** | Opens a web address. |
+| **Chat with user** | Starts a one-to-one conversation with a user. |
+| **Chat with group** | Opens a group conversation. |
+| **Send message** | Sends a message on the user's behalf. |
+| **Copy to clipboard** | Copies text to the clipboard. |
+| **Download file** | Downloads a file. |
+| **Initiate call** | Starts a voice or video call. |
+| **API call** | Makes a request to a configured endpoint. |
+| **Custom callback** | Triggers custom handling in your app. |
+
+## Variables
+
+Variables are placeholders you insert into text and URL fields, written as `{{name}}` (for example `{{user.name}}`). They're replaced with real values when the card is sent, letting one card adapt to each recipient. Insert them from the variable picker wherever you enter text.
+
+## Components
+
+Components are pre-built groups of elements you can add to a card and then edit. They're a fast way to start a common card:
+
+| Component | Use case |
+| --- | --- |
+| **Product Card** | A product with image, details, and a call to action. |
+| **Order Confirmation** | Order summary with status. |
+| **Order Tracking** | A delivery timeline. |
+| **Event Card** | Event details with date and location. |
+| **Announcement** | News or an update. |
+| **Quick Reply Buttons** | Tappable response options. |
+| **Feedback** | A quick rating or response prompt. |
+| **Data Table** | Structured rows of data. |
+| **Carousel** | A horizontally scrollable set of cards. |
+
+## Fallback Text
+
+Every card includes **fallback text** — what a CometChat UI Kit renders if it can't display the card itself (for example, if the card JSON is malformed or the client doesn't support cards). Always set it so the message still conveys its meaning.