🧩 UI widgets

UI widgets are interactive cards your agent renders inline in a conversation instead of plain text: forms, order lists, pricing tables, charts, booking cards. The visitor clicks buttons and submits forms without leaving the chat.

Widgets are built under Builder → Widgets in a project and attached to the agent under Builder → Functions.

🎯 What they are for

• Collect structured data — lead forms, requests, booking details.
• Display information — order status, product list, a small report chart.
• Run actions — call an API, send a message, open a link from a button.
• Conditional content — one widget holding both an “offer” and a “confirmed” state.
• Share — export a widget as a .widget file and import it into another project.

🔄 How a widget reaches the chat

A widget never renders on its own — an agent function always renders it:

• 1. Build and save the widget on the Widgets page.
• 2. On the Functions page create a function and set Action to Show widget or Call API + show widget, then pick the widget.
• 3. The visitor asks something and the agent calls that function.
• 4. The agent fills the widget data according to its schema (or the API response is used).
• 5. The widget renders inside the conversation — both in the playground and in the site chat widget.
• 6. When the visitor clicks a button, the widget's own functions run.

🧱 Core concepts

• Code — the layout. Written as JSX, stored as a JSON tree.
• Schema — the data contract. The agent fills exactly these fields.
• Default — sample data used only for the editor preview.
• Examples — extra named payloads for testing different states.
• Functions — what happens on interaction: call API, set variables, send message, open link, dismiss.
• States — show or hide a part of the tree based on conditions.

📊 Data priority

At render time data is resolved in this order:

API response  >  function (action) data  >  Default example  >  empty values from the schema

So Default never overrides live data — it only exists for the editor.

📂 Import and export

Export in the editor downloads a .widget file containing the tree, schema, examples, functions and states. Import on the Widgets page loads it back. An imported widget must be re-attached to a function in the new project.

🚧 Not available yet

• The Map component.
• The iframe-based client function.
• An AI builder that generates a widget from a prompt.

➡️ Next

• Your first widget — quickstart
• The editor: Code, Schema, Preview
• Attaching a widget to the agent