Rendering Custom UI in the Chat Widget
If your MCP tool returns a payload in the shape below, the chat widget will render it as a real interactive component (product card, swipeable carousel, etc.) instead of plain text. CTAs are plain links — they open in a new tab.
How It Works
Your tool returns JSON wrapped in a __widgetUI envelope. The widget detects it, validates the shape, and renders the matching component. Anything unrecognized falls back to text.
Available Shapes
Product Card — Single Product
Product Grid — Multiple Products
Renders as a swipeable carousel; one card at a time with dot pagination
If
itemshas length 1, the widget renders a single fixed-width card automatically.
Tool Description Matters More Than the Schema
The AI only emits these payloads when your tool description tells it to. Be explicit and tell it not to also describe the products in text:
“Display a visual grid of products to the user. Use this whenever the user is browsing or asking to see products — instead of describing them in text. After calling this tool, your text response should be empty or a single short lead-in. Never list, summarize, or describe the products in prose.”
If the AI keeps double-narrating (“Here are some options:” + the cards), tighten the description further.
Field Rules
imageandcta.hrefmust be valid URLspriceis a pre-formatted string (e.g. "€93.50", "$214.99") — no currency math on the widget sideswatchesis optional; values are CSS colors- Extra fields (was, discount, available, etc.) are silently ignored — safe to include for your own tool's logic
What CTAs Do
Every cta.href renders as a link that opens in a new tab. The customer's site decides what that URL does (product page, checkout, etc.). The widget does not fire events back to the host page — keep all interactivity behind the URL.
Coming Soon
- Choice-grid (chips that send a reply back into the chat) — schema is defined, renderer not yet wired. Ping us if you need it.
Did this answer your question?