> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-feature-card-builder.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Messages

> Let your LangGraph BYOA agent reply with rich, interactive cards designed in Card Builder.

Your [Bring Your Own Agent (BYOA)](/ai-agents/cometchat-ag-ui-byoa) can reply with flexible, interactive cards — buttons, images, progress bars, layouts — instead of plain text. You design each card in [Card Builder](/card-builder/overview) so it renders uniformly, and your agent returns the card as JSON.

## Enable card messages

1. Open your BYOA agent in the dashboard.
2. Turn on **Enable card messages**.

Card messages are **opt-in** and off by default.

## How it works

When card messages are enabled, CometChat gives your agent a **card reference — working examples plus a field reference** — describing the same structure documented in the [Card JSON Schema](/card-builder/schema). Your agent returns a card simply by responding with **JSON that follows that reference**, and CometChat renders it as a native card in the chat.

You only supply **what** card to send — the **how** is automatic. The format CometChat uses to recognize a card in your agent's response is part of the injected reference and is handled for you, **as long as card messages stays enabled**. This holds even if you use your own instructions or a predefined card: keep the feature on and just provide the card content. Don't disable it and try to emit cards from the raw schema alone — your agent won't have the format, and the card won't render.

<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>

## Keep cards uniform

Because the agent has the card reference, it *can* generate cards freely — but free-form generation drifts in layout and styling. To keep every card consistent, design it once and reuse it:

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. Have your agent **return that exact JSON** for the relevant reply, rather than composing a card from scratch.

<Note>
  A fixed card renders exactly as designed. If it includes `{{placeholder}}` variables, your agent must fill them in with real values **before** returning the JSON — CometChat passes the JSON through as-is and does not resolve placeholders.
</Note>

## Reference

<CardGroup>
  <Card title="Card JSON Schema" icon="code" href="/card-builder/schema">
    The complete schema your agent's card JSON must conform to.
  </Card>

  <Card title="Open Card Builder" icon="window-restore" href="/card-builder/overview">
    Design and export cards visually — 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>
</CardGroup>