> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# In-call forms

> Show a form inside the widget during a call: build it with the widget step, pick inputs and validation, and choose how it appears to the visitor.

An in-call form is a widget step in your script. When the conversation reaches it, the agent says the step's phrase and the visitor sees a form in the widget: a few fields to fill in, a list to pick from, or a card of information. The answer goes straight into the conversation, so the agent can confirm it and move on.

Use forms for anything that is slow or error-prone to say out loud: email addresses, dates, multiple-choice questions, order details, or a summary the visitor should read.

<ol />

![The Callers widget during a call showing a booking form with name, email and preferred slot fields](https://mintcdn.com/voxiaai/wqnSuR-gwKpmU86L/images/documentation/widget-campaigns/form-popover.png?fit=max\&auto=format\&n=wqnSuR-gwKpmU86L\&q=85\&s=ce3e3dc8200b4382494b05c4876cf0a1)

A form during a voice call: title, required fields, a single-choice question, and Skip / Submit. Submit stays disabled until the required fields are filled.

> [!NOTE]
>
> Forms work on web calls only. Add a widget step to a Voice agent with the widget enabled (see [Installing the widget](https://docs.callers.ai/documentation/widget-agents/installing-the-widget.md)). The **Widget** button appears in the script footer once the widget is on.

## Add a widget step

**1. Insert the step**

In the script editor, click **Widget** in the footer where you want the form. If your organization has saved templates, a picker opens first; choose one or click **Create New**.

**2. Write the phrase**

Fill in **Widget Phrase**, what the agent says when the form appears, for example "I've put a short form on your screen. Fill it in when you're ready."

**3. Design the form**

The widget editor opens. Give it a name (used in the script and the library), choose a mode, and add elements (below).

**4. Choose how it appears**

Pick a placement and whether the form can be submitted (see [Presentation](#presentation)).

**5. Add it**

Click **Add** (or **Save** for an existing step), then save the agent.

To reuse a form across agents, click the **Save as template** icon in the editor header. Templates live in the [Widgets library](https://docs.callers.ai/documentation/widget-agents/styling-the-widget.md#the-widgets-library).

## Form modes

| Mode | Where | What the visitor sees |
| - | - | - |
| **Form** | **Design** tab, display mode **Form** | All elements on one screen with **Skip** and **Submit**. |
| **Stepped** | **Design** tab, display mode **Stepped** | One element per screen with a progress bar, **Back**, **Next**, and **Submit** on the last screen. |
| **JSON** | **JSON** tab | A **Widget Data** block showing the JSON you wrote, a free-text **Response** box, and **Skip** / **Submit**. Use it to show structured data (an order, a quote) and collect a reply. Variables can be inserted. |
| **A2UI** | **A2UI** tab | A custom layout built from components such as **Text**, **Text Field**, **Choice Picker**, **Check Box**, **Date & Time**, **Button**, **Row**, **List**, and **Card**. Each input binds to a **Data path** like `/email`. |
| **Widget Generation** | **Widget Generation** tab | You write a **Prompt**; the AI generates the widget during the call from the conversation and variables. |

> [!NOTE]
>
> The **A2UI** and **Widget Generation** tabs are enabled per account. Contact [support@callers.ai](mailto:support@callers.ai) to turn them on.

Switching between the **Design** tab and **A2UI** discards the current content, because the two formats can't be converted. The editor asks you to confirm.

## Elements

Click **Add Element** in the **Design** tab. Elements come in two groups.

### Inputs

| Element | Collects | Settings |
| - | - | - |
| **Short Text** | A single line of text. | **Required**, **Max characters** → **Max length**, **Answer validation** → **Pattern (regex)**. |
| **Long text** | A paragraph. | **Required**, **Max characters** → **Max length**. |
| **Number** | A number. | **Required**, **Value range** → **Min** and **Max**. |
| **Dropdown** | One option from a list. | **Required**, options. |
| **Single Choice** | One option, shown as radio buttons. | **Required**, options. |
| **Multiple Choice** | Several options, shown as checkboxes. | **Required**, options. |

Every input has a question (the label the visitor sees), an optional description, a placeholder, and a **Name**. The name is the key in the submitted answer. It is lowercased automatically and may only contain letters, digits, and underscores. Names must be unique within the form.

For choice elements, click **Add choice** and give each option a label and a value. The label is what the visitor sees; the value is what the agent receives.

### Display

| Element | Use it for |
| - | - |
| **Title** | A heading. |
| **Description** | Explanatory text. |
| **Info Block** | A highlighted note, for example terms or a summary. |

Display elements have no answer settings. Use the sidebar menu to **Duplicate** or **Delete** an element, and the arrows to reorder.

> [!TIP]
>
> The agent reasons on your labels, names, and option values when it reads the answer. Name fields for what they hold (`preferred_date`, not `field_3`) and keep option values meaningful.

### Required fields and validation

* A required field shows a red `*`. In **Form** mode, **Submit** stays disabled until every required field has a value. In **Stepped** mode, **Next** stays disabled until the current field is answered.
* On submit, text length, regex pattern, and number range are checked. The visitor sees messages such as "This field is required", "Invalid format", "Must be at most 120 characters", or "Must be at least 1".
* **Skip** ignores all validation and sends an empty answer, which shows as "Skipped" in the transcript. Write the next step so it copes with a skipped form.

## Presentation

The **Widget behavior** section in the editor header sets where the form appears and whether it can be answered.

| Placement | Where it shows |
| - | - |
| **Popover** (default) | A separate panel over the conversation. |
| **Inline card** | A card inside the transcript. |
| **Message bubble** | Inside the agent's message. |

![Three widget screenshots showing a form as a popover panel, as an inline card, and inside the agent's message bubble](https://mintcdn.com/voxiaai/wqnSuR-gwKpmU86L/images/documentation/widget-campaigns/forms-presentation-modes.png?fit=max\&auto=format\&n=wqnSuR-gwKpmU86L\&q=85\&s=d130af7bd79d42ce74b9c7fce1af5298)

The same form in the three placements. Popover takes over the widget footer; Inline card and Message bubble keep the form in the transcript.

**View only** makes the widget display-only: no inputs, no **Skip** or **Submit**. Use it for confirmations and summaries. A visitor can reopen a view-only popover with **View widget**.

Rules:

* **Stepped** and **JSON** widgets always use **Popover**. Switching to **Stepped** resets presentation to **Popover**, and **Stepped** can't be **View only**.
* An interactive popover takes over the widget's footer until the visitor answers or skips.
* After the call ends, every widget becomes read-only in the call history.

> [!NOTE]
>
> **Widget behavior** is enabled per account. Without it, forms appear as interactive popovers. Contact [support@callers.ai](mailto:support@callers.ai) to turn it on.

### Close the form when the conversation moves on

In the agent's **General Settings** → **Technical Settings**, **Close widget form on new message** hides an open form as soon as any new message appears in the conversation, including another widget. The agent keeps waiting for an answer, and the visitor can still reply out loud. The setting appears only when the widget is enabled.

## How answers reach the agent

While an interactive form is open, the agent waits for the visitor to submit or skip. On submit, the answers (field names and values) are added to the transcript as a structured message, and the agent continues the script with them in context.

A form with a **Short Text** named `email`, a **Dropdown** named `preferred_date`, and a **Multiple Choice** named `topics` produces an answer like this, keyed by each element's **Name**. Choice elements send the option values, not the labels; **Multiple Choice** sends the selected values as one comma-separated string:

```json theme={"dark"}
{ "email": "dana@example.com", "preferred_date": "2026-10-29", "topics": "billing,onboarding" }
```

In the Web SDK this is the `content` of `onWidgetInputSent` (as a JSON string), sent together with the `id` of the form message as `widgetMessageId`. A skipped form sends `{}`.

* Answers are **not** stored as agent variables. A later step can't reference them with `{{field}}`.
* To pass an answer to an [action](https://docs.callers.ai/documentation/build-your-agent/agent-actions.md), add an action to the widget step with **Add Action (Optional)** or give a later action a transcript variable whose description names the answer field.
* Widget steps support [post-call key questions](https://docs.callers.ai/documentation/using-callers/key-questions.md); click the step number to add them.
* Developers can read form answers in the SDK transcript events. See [Events and transcript](https://docs.callers.ai/sdk/events-and-transcript.md#form-answers-and-typed-messages). Forms also work in headless and React Native integrations that render the widget's messages themselves; see [Headless and React Native](https://docs.callers.ai/sdk/headless-and-react-native.md).

## Test it

Run a **Web Call** test from the agent header (**Test** → **Web Call**) and go through every widget step. Check that each form appears in the right placement, submit each field type once, skip one form, and look at the transcript to confirm the agent received the values you expect. A phone test call doesn't show widgets.

## Troubleshooting

> **The Widget button isn't in the script footer**
>
> The agent must be a Voice agent with **Enable widget** switched on in **Channels** → **Widget**, and the widget feature must be enabled for your account.

> **The agent keeps waiting after a view-only widget**
>
> A view-only widget has nothing to submit, but the step still expects the conversation to continue. Keep the **Widget Phrase** short and make sure the next step asks the visitor something, so the conversation moves on.

> **Save fails with 'Fix required fields'**
>
> Every input needs a unique **Name**, every choice element needs at least one option with both a label and a value, and display elements need content.

> **A later action doesn't get the form value**
>
> Answers aren't variables. Attach the action to the widget step itself, or describe the field in the action's transcript variable so the agent fills it from the conversation.

## Related

> **[Installing the widget](https://docs.callers.ai/documentation/widget-agents/installing-the-widget.md)**
>
> Enable web calls and embed the widget.

> **[Styling the widget](https://docs.callers.ai/documentation/widget-agents/styling-the-widget.md)**
>
> Themes and the Widgets library.

> **[Steps](https://docs.callers.ai/documentation/build-your-agent/customizing-steps.md)**
>
> Every step type in the script editor.

> **[Actions](https://docs.callers.ai/documentation/build-your-agent/agent-actions.md)**
>
> Send form answers to your systems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.