User Guide

Your first widget

Seven steps from creating a widget to attaching it to the agent and testing it in the playground.

🚀 Your first widget

In this guide you build a small order-status widget, attach it to the agent and test it in the playground. About 10 minutes.

1️⃣ Open the Widgets page

Pick a project and go to Builder → Widgets in the sidebar. The page has two tabs:

My widgets — saved widgets.
Create widgets — the template gallery.

The Widgets page — Builder → Widgets: the “My widgets” and “Create widgets” tabs, with Import and Custom widget in the header.

2️⃣ Start from a template

On Create widgets click a template card — a dialog shows it live with its description — then click Use this template. To start from a blank card use Custom widget in the page header.

Templates: Hotel booking, Order list, Lifecycle, Lead form, Analytics.

Template dialog — Clicking a template card shows the live widget, its description and “Use this template”.

3️⃣ Write the layout (Code)

The Code tab takes JSX. The preview on the right updates as you type:

<Card gap={3}>
  <Row align="center" gap={2}>
    <Title value={order.title} size="lg" />
    <Spacer />
    <Badge label={order.status} color="info" />
  </Row>
  <Text value={order.eta} color="secondary" size="sm" />
  <Button label="Track" onClickAction={{ functionName: 'track' }} block />
</Card>

The editor — JSX code and the schema panel on the left, the live preview on the right.

4️⃣ Define the schema

In the Schema tab of the bottom panel, describe the fields the agent has to fill:

{
  "type": "object",
  "properties": {
    "order": {
      "type": "object",
      "properties": {
        "title":  { "type": "string" },
        "status": { "type": "string" },
        "eta":    { "type": "string" }
      },
      "required": ["title", "status"]
    }
  },
  "required": ["order"]
}

You can also write the data first and press Infer from data to generate the schema.

5️⃣ Add sample data (Default)

The Default tab feeds the editor preview only:

{
  "order": {
    "title": "Order #10241",
    "status": "Shipping",
    "eta": "Arrives on August 12"
  }
}

The + button stores the current payload as Example 1, which is handy for testing different states.

6️⃣ Add a function

On the Functions tab create a function named track. The simplest type is send_message, which posts a message into the conversation when the button is clicked. Use call_api to call your backend instead.

7️⃣ Save and attach it to the agent

Type a name in the editor header and click Save.
Go to Builder → Functions and add a function.
Set Action to Show widget and select your widget.
Write the function name and description — the agent decides to call it from that description.
Attach the function to your agent.

Function action — The “Action” field of the function form: Call API, Show widget, Call API + show widget.

✅ Test it

Open the Playground and ask something that matches the description (for example “Where is my order?”). The agent calls the function and the widget renders in the conversation. Click the button to verify the widget function too.