Skip to main content
Your Bring Your Own Agent (BYOA) can reply with flexible, interactive cards — buttons, images, progress bars, layouts — instead of plain text. You design each card in Card Builder 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. 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.
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.

​
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 — see Building an Order Status Card 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.
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.

​
Reference

Card JSON Schema

The complete schema your agent’s card JSON must conform to.

Open Card Builder

Design and export cards visually — palette, canvas, elements, actions, and variables.

Worked example

Build an interactive Order Status card from scratch, step by step.