🔌 Attaching a widget to the agent

A widget never appears on its own — a function under Builder → Functions renders it. Once that function is attached to an agent, the agent decides when to call it.

🎬 Three actions

Pick one in the Action field of the function form:

• Call API — the classic function: the agent calls your endpoint and answers from the response. No widget involved.
• Show widget — no endpoint. The agent fills the data following the widget schema and the widget renders. Good for forms, choice cards and informational displays.
• Call API + show widget — the endpoint is called first and its response becomes the widget data. Good for live data (order status, account details).

🧩 How to configure it

• 1. Click Add function.
• 2. Choose the Action. With Show widget the endpoint, payload and authorization sections disappear entirely — such a function has none.
• 3. Pick the widget from the Widget list (it holds this project's widgets).
• 4. Fill the name, when to use it and what it returns — the agent decides to call the function from exactly these texts.
• 5. Attach the function to an agent.

🔀 Response mapping

With Call API + show widget the endpoint response rarely matches the widget schema. Response mapping says which path goes into which field:

{ "orders": "data.items" }

The data.items array from the response is placed into the widget's orders field.

🧪 Testing

• In the Playground, ask something that matches the function description.
• If the agent calls the function, the widget renders next to the answer.
• If the function fails, the widget is not rendered at all — a widget is never built on an error payload.
• Click the buttons to test the widget's own functions too.

💬 How it is stored in the conversation

• The widget is stored with the message — reopening the chat renders it again.
• One answer can render several widgets.
• If the visitor dismisses a widget, that is remembered in their browser.
• The same rendering works in the chat widget on your site.

📋 In the functions table

A widget-backed function shows the widget's name instead of a URL, so you can see at a glance which function renders which widget.