Web chat widgets and forms

Widgets and forms let an agent render rich UI inside a web chat instead of replying with plain text. A widget is a structured card (a product carousel, an order tracker, a one-time-code prompt); a form is a typed data-collection panel (inputs, ratings, selects) the user fills in and submits. Both are configured on the agent version and triggered by the LLM during a conversation. These render in the embeddable container described in Web widgets overview. This page covers what the agent can show; the Web widget is where it appears.

How the LLM triggers them

Widgets and forms are exposed to the model as tools. The model decides when to call them, fills in the parameters, and the result is delivered to the chat UI.

Widgets become a tool named show_<widget_type>_widget (for example show_carousel_widget). The tool’s parameters are the widget’s content fields, so the model both chooses to show the widget and supplies its data in one call.
Forms become a tool named show_form_<form_id> (for example show_form_contact_info). The form tool takes no parameters — the field definitions live in the config, and the user fills them in. The tool description defaults to Show the '<name>' form to collect structured data from the user. unless you set a custom description.

The same catalog is available on both transports, with one delivery difference:

Transport	Delivery
WebRTC (live web chat)	The model gets the `show_*` tools live; calling one fires a LiveKit RPC that renders the widget/form in the open session.
Rich text	The same `show_*` tools are offered; each call appends a `{type, data}` entry that is emitted in the response payload for the client to render.

On the rich-text path, a form is emitted with type: "form" and the full form definition as its data. A widget is emitted with type: "<widget_type>" and the model-supplied content as its data.

Enabling widgets

Widgets are configured under built_in_tools.widgets on the agent version. The allowed field is an optional list of widget types.

Field	Type	Default	Description
`allowed`	list of widget type	omitted	Widget types the agent may show. If omitted or `null`, all widget types are enabled.

WidgetType enumerates the available widgets:

Widget type	What it shows
`detail`	A detail page: title, optional image, text/markdown body, optional price, and a source link. Good for product pages, recipes, or articles.
`carousel`	A scrollable grid of items with images, optional pricing, ratings, and add-to-cart buttons.
`info`	Structured key-value information in labeled sections, with optional action buttons and external links.
`list`	A list of items with optional images, badges, and per-item buttons. Supports multi-select with checkboxes and auto-numbering.
`action_grid`	A grid of quick-action buttons with icons for the user to pick from.
`collect_otp`	A one-time-code entry prompt for a code sent to a masked destination.
`collect_phone_number`	A phone-number entry prompt.
`order_tracker`	An order status tracker with carrier, tracking number, dates, and line items.
`comparison`	A side-by-side comparison of items by price and labeled attributes.

Carousel items

Each item in a carousel carries an id, title, and image (required), plus optional link, price, vipPrice (a discounted/VIP price), and rating (a number such as 4.5). The widget itself accepts index (starting item, default 0), window (visible items, default 3), and show_add_to_cart to render an Add to Cart button on each item.

List items

A list item carries an id and title (required), plus optional subtitle, image, value (right-aligned text such as a price), strike_value (strikethrough, e.g. an original price), badge, and per-item actions. Each action has a label and an action identifier sent back when clicked, plus an optional dismiss flag (default true) that closes the widget after the click. Set selectable: true to enable multi-select checkboxes and numbered: true to auto-number items; pair multi-select with submit_label (use {n} for the selected count) and submit_action.

action_grid icons

Each action_grid item takes an id, label, and action_value (sent back when clicked). The optional icon is one of: suitcase, ruler, truck, credit, headset, star, reload. The grid title defaults to How can I help?.

order_tracker status

The status field is one of ordered, shipped, in_transit, or delivered. Required fields are order_id, status, carrier, tracking_number, ordered_date, estimated_delivery, and items (each with name, color, size, quantity).

Forms

Forms are configured under built_in_tools.forms. The forms list must contain at least one form, and form IDs must be unique within the agent.

Form definition

Field	Type	Default	Description
`id`	string	required	Unique form ID within the agent. Used to name the `show_form_<id>` tool.
`name`	string	required	Display name in the builder UI.
`description`	string	none	Tool description that tells the LLM when to show this form.
`title`	string	none	Title shown in the rendered form.
`submit_label`	string	`Submit`	Label on the submit button.
`fields`	list of field	required	At least one field. Non-`display` field IDs must be unique within the form.

Field types

FormFieldType enumerates the field types:

Field type	Renders as
`input`	A single-line text input.
`textarea`	A multi-line text input.
`boolean`	A yes/no toggle, labeled with `true_label` / `false_label`.
`rating`	A star rating. `max_rating` sets the number of stars (between 2 and 10, default 5).
`single_select`	A choice of one option from `options`.
`multi_select`	A choice of multiple options from `options`.
`display`	Read-only display text; not part of the submitted data.

Field reference

Field	Type	Default	Description
`id`	string	required	Unique identifier within the form, used as the JSON key in submission data.
`type`	field type	required	One of the field types above.
`label`	string	required	The field’s label.
`placeholder`	string	none	Placeholder text.
`required`	boolean	`false`	Whether the field must be filled before submit.
`default_value`	any	none	Prefilled value. String for `input`/`textarea`/`single_select`, bool for `boolean`, number for `rating`, list of strings for `multi_select`.
`options`	list of `{label, value}`	none	Choices for `single_select` and `multi_select`.
`display_mode`	`dropdown` \| `buttons`	`dropdown`	How `single_select`/`multi_select` options render.
`allow_other`	boolean	none	When `true`, select fields add an Other choice with a free-text input.
`true_label`	string	none	Label for the `true` button on a `boolean` field (e.g. `Yes`).
`false_label`	string	none	Label for the `false` button on a `boolean` field (e.g. `No`).
`max_rating`	integer	5	Number of stars on a `rating` field. Must be between 2 and 10.
`validation`	string	none	Regex pattern for validating text input values.
`validation_message`	string	none	Error message shown when validation fails.

The validation regex must be 200 characters or fewer, must compile, and may not contain nested quantifiers (such as (a+)+), which are rejected to avoid catastrophic backtracking.

Limits

Limit	Value
`rating` / `max_rating` stars	2–10 (default 5)
Minimum fields per form	1
Minimum forms in `FormsConfig`	1
`validation` regex length	200 characters
Form IDs	unique within the agent
Non-`display` field IDs	unique within a form

Web widget overview

The embeddable container where these widgets and forms render.

Text, voice, and quick actions

How the web widget runs in text and voice mode and surfaces quick actions.

​How the LLM triggers them

​Enabling widgets

​Widget catalog

​Carousel items

​List items

​Forms

​Form definition

​Field types

​Field reference

​Limits

​Related

Web widget overview

Text, voice, and quick actions

How the LLM triggers them

Enabling widgets

Widget catalog

Carousel items

List items

Forms

Form definition

Field types

Field reference

Limits

Related