# Custom form

> Show one specific form in the chat, with exactly the fields you need, and save every answer.

A custom form shows the same form in the chat every time, with exactly the fields you choose. Use it for things like exchange requests, free-trial sign-ups, or warranty registrations. Every submitted form is saved to **Activity → Collected Data**.

**Where to find it:** open your agent, go to **Build → Actions**, and select **Custom form**.

![A chat where a fitness studio's agent shows a Claim your free class form](https://hourzero.dev/marketing/app/fitness-trial-light.webp "A free-class sign-up form: two fields, a Cancel button, and a custom submit button.")

## How it works

1. **Customer asks**: "Can I exchange my jacket for a bigger size?"
2. **Form appears**: The agent shows your form in the chat.
3. **Customer submits**: They fill it in and select your submit button.
4. **Answer saved**: It appears on Activity → Collected Data.

A custom form is always a form. If you'd rather have the agent pick up details from the conversation, use [Collect data](https://hourzero.dev/docs/ai-agent-management/actions/collect-data) with the **Auto** method instead.

> [!NOTE]
> Forms appear in your website chat: Chat Bubble, Center Stage, and Chat Iframe. Messaging apps such as WhatsApp and Slack only receive text, so turn this action off for those channels in the Playground.

## Example: an exchange request form

This example builds a form Acme Support shows when a customer wants a different size.

1. Open **Build → Actions** and select **Custom form**.
2. In **Action name**, enter `Exchange request`.
3. In **When should the agent use it?**, enter:

   ```text
   Show this form when a customer wants to exchange an item for a
   different size. Don't show it for refunds or damaged items.
   ```

4. Leave **Form configuration** set to **Dashboard fields**.
5. In the **Form builder**, select the title "Tell us what you need" and type `Request an exchange`. Select **Add description** and enter `We'll check stock and email you about your new size.`
6. The form starts with one field called **Details**. Select its label and type `Order number`. In **Field settings**, set **Field type** to **Short text**.
7. Select **Add field**, name it `Item`, and set **Field type** to **Short text**.
8. Select **Add field**, name it `New size`, set **Field type** to **Select**, and enter `XS, S, M, L, XL` in **Options**.
9. Select **Add field**, name it `Notes`, set **Field type** to **Long text**, and turn off **Required field**.
10. Select the submit button ("Submit") and type `Request exchange`.
11. Under **After submission**, enter `Thanks! We've saved your exchange request.`
12. Select **Create action**.

> [!TIP]
> Keep the success message honest. "We've saved your exchange request" is true the moment the form is submitted. "Your exchange is confirmed" is not, unless something else actually confirms it.

## Build your form

Everything in the **Form builder** is edited in place, the way the customer will see it:

- **Title and description:** select the title to change it. Select **Add description** for a line of text under it.
- **Fields:** select a field's label to rename it. Select **Add helper text** to show a hint under the field.
- **Field settings:** select a field (or its gear icon) to choose its **Field type** (**Short text**, **Long text**, **Email**, **Phone**, **Number**, **Yes / no**, or **Select**), its **Options** for a select field, and whether it's a **Required field**. Select **Remove** to delete it.
- **Submit button:** select the button text to change it.
- **After submission:** the message that replaces the form once it's submitted.

A form needs at least one field and can have up to 20.

## What the customer sees

When the agent shows the form, the customer fills it in and selects your submit button. If a required field is empty, the form asks them to complete it. Once submitted, the form is replaced by your success message.

The customer can also select **Cancel**. Nothing is saved, and the form shows "Form cancelled."

Showing the form doesn't save anything. Only a submitted form creates an entry on **Activity → Collected Data**. To send each new entry to another tool, set up a [webhook](https://hourzero.dev/docs/integrations/webhooks) for the `submission.created` event.

## Test it

1. In **Playground**, check that the form is switched on for your channel in the **Capabilities** tab, and select **Save draft**.
2. Ask "Can I swap my jacket for a large?" The form should appear.
3. Try to submit it with a required field empty, then fill it in and submit.
4. Start a new chat, show the form again, and select **Cancel**.
5. Open **Activity → Collected Data**, filter by **Playground**, and check that only the submitted form was saved.
6. Ask something unrelated. The agent should not show the form.
7. Publish the channel when you're happy.

## Let your website supply the form

Sometimes the right fields depend on your website, for example a different form for each product. A developer can make your website provide the form's fields instead of setting them in the dashboard.

1. Under **Form configuration**, choose **Website form schema**.
2. In **Form handler name**, enter the name your developer registered, for example `delivery_question`.
3. Under **Form copy**, fill in **Form title**, **Submit button**, and **Success message**. These are used when your website doesn't provide its own.

> [!IMPORTANT]
> Website forms only work in the chat embedded on your own website with the Hourzero script: Chat Bubble, Center Stage, or [Chat Iframe](https://hourzero.dev/docs/integrations/chat-iframe#website-actions-and-website-forms) installed with **Script**. They don't appear in a Chat Iframe installed as **Iframe only**, the Playground preview, or messaging apps, so test them on your live site.

### For developers

Register a schema factory on the page where the chat is embedded. Its name must match **Form handler name**:

```js
window.hourzero("registerFormSchema", {
  delivery_question: async (args, user) => ({
    title: "Ask about your delivery",
    fields: [
      {
        name: "order_number",
        label: "Order number",
        type: "text",
        validation: { required: { value: true } },
      },
      {
        name: "question",
        label: "Question",
        type: "textarea",
        placeholder: "How can we help?",
      },
    ],
    submitButtonText: "Send question",
    successMessage: "Your question has been saved.",
  }),
});
```

- Call it after the embed script loads, or set up the `window.hourzero` queue first, as shown on [Custom action](https://hourzero.dev/docs/ai-agent-management/actions/custom-action).
- `user` is the same object website handlers receive, including the signed-in user's `user_id` and `user_metadata` when your website uses [identity verification](https://hourzero.dev/docs/integrations/identity-verification).
- Field `type` can be `text`, `textarea`, `email`, `phone`, `number`, `boolean`, or `select`. A `select` field needs an `options` array of strings.
- Field `name` must use lowercase letters, numbers, and underscores, and start with a letter. Names must be unique.
- Fields support `label`, `placeholder` (shown as helper text), `defaultValue`, and `validation.required.value`. Fields are optional unless marked required.
- Optional `title`, `description`, `submitButtonText`, and `successMessage` replace the dashboard copy. A schema needs 1 to 20 fields.
- The factory only supplies the form. Submissions are checked and saved by Hourzero, not sent to your website. Don't treat a submitted form as proof of who the customer is.

## Next steps

- [Collect data](https://hourzero.dev/docs/ai-agent-management/actions/collect-data): Gather details from the chat without a form.
- [Leads and collected data](https://hourzero.dev/docs/ai-agent-management/submissions): Find, filter, and export submitted forms.
- [Custom button](https://hourzero.dev/docs/ai-agent-management/actions/custom-button): Send customers to a page instead of showing a form.
- [Actions overview](https://hourzero.dev/docs/ai-agent-management/actions/overview): Compare all actions and choose where each one runs.
