---
title: 9.8 WhatsApp Forms
description: "Forms let a customer fill in a short, multi-page form inside WhatsApp without leaving the chat: register for an event, request a quote, book an…"
url: "https://peikly.com/docs/whatsapp-forms/"
updated: "2026-10-14"
category: WhatsApp
tags:
  - Manual sync
---

# 9.8 WhatsApp Forms

## What This Feature Does

Forms let a customer fill in a short, multi-page form **inside WhatsApp** without leaving the chat: register for an event, request a quote, book an appointment, answer a survey. Peikly has its own form designer, so you never need Meta's technical tools. Every answer lands in a response inbox, on the contact's profile, in notifications and in your automations, and you can export the answers to CSV or Excel.

A form is built from four parts that work together:

- **The form** (designer): pages, questions, routing and what happens after submission.
- **Data lists** (optional): reusable option lists such as countries, packages or branches, with optional seat limits.
- **Ways to send it**: a template button, an ice breaker or command, the chat, a contact's profile or a workflow.
- **Automation**: triggers, actions and conditions that react to each step of the form.

Read the steps below in order the first time you build one.

## When to Use

- Use to collect structured information (name, email, a package choice, a date) instead of asking question after question in the chat.
- Use to reserve limited places, for example 50 seats per package for a conference.
- Use to open a form from a template button, an ice breaker, a workflow, the chat, or a contact's profile.

## Prerequisites

- A plan that includes WhatsApp Forms, and a connected Meta Platform ([8.1](/docs/connect-to-meta-first-time/)) with at least one WhatsApp number.
- The CompanyAdmin can always use Forms. Other users need the **WhatsApp Forms** permission, which the CompanyAdmin grants on the user's **Data Access** page ([6.5](/docs/user-contact-data-access/)).
- If **Forms** is missing from the **WhatsApp** menu, your plan does not include it, the permission has not been granted, or the feature is not available on your deployment. Ask your CompanyAdmin or support.
- Two Meta permissions are needed, both approved in Meta's dialog when you connect ([8.3](/docs/refresh-meta-permissions/)): one to create, publish and check forms with WhatsApp (also used by ice breakers), and one to send forms to customers. Designing, testing in the simulator, data lists, responses and statistics work without them; publishing, **Send to my phone**, the live preview, retiring a form and ice breakers need them. If one is missing, Peikly tells you which one and links to **Meta Platform** → **Permissions**, where **Re-launch Meta** lets you approve it. The **Forms** list shows the same warning at the top.

## Part 1 — Create a Form

1. In the sidebar, click **WhatsApp** → **Forms**, then **New form**.
2. Pick a starting point: **Event registration** (personal details, contact details, package, summary, confirmation and seat reservation), **Service request**, **Appointment booking**, **Feedback survey**, or **Blank**. Give the form a name and choose the WhatsApp Business Account it belongs to. Each form belongs to one account; templates can only use forms from their own account.
3. Build it in the designer:
   - **Pages** (left): the steps the customer goes through, up to 12. Drag pages to reorder them. The **Summary** and **Confirmation** pages stay at the end. The Summary page shows the customer what they entered before they confirm; turn it off for very short forms.
   - **Questions** (centre): drag questions onto a page, or add them from the palette. Each question has a label, a *required* switch, optional helper text and its own options.
   - **Logic**: send customers to a different page depending on an answer ("if *Package* is *VIP*, go to page 4"). A page can have up to 10 such rules. Without a rule, the next page is the one below.
   - **After submission**: the thank-you text, which contact fields are filled from the answers, which tags are added, whether a new contact is created for an unknown number, and who is notified.
   - The phone on the right shows a live preview of the page you are editing.
4. The **Problems** panel lists everything to fix in plain language (for example "Page 3 has no way to continue", or "Dropdown *City* has 312 options, the most WhatsApp allows is 200") and takes you to the question. A form with problems cannot be published.

Drafts are saved as you work. The **Unsaved changes** marker shows when something has not been saved yet.

### Question types

| Palette item | What the customer sees | Notes |
| --- | --- | --- |
| Short text | One line of text | Label up to 20 characters |
| Paragraph | Multi-line text | Up to 600 characters |
| Number | Number keypad | Optional minimum and maximum |
| Email | Email keyboard | Checked for a valid address |
| Phone | Phone keyboard | Checked for a valid number |
| Website | URL keyboard | Checked for a valid address |
| Date | Date picker | Label up to 40 characters |
| Date range | Start and end date pickers |  |
| Dropdown | A list to pick one option | Up to 200 options |
| Single choice | Radio buttons, one answer | Up to 20 options |
| Multiple choice | Checkboxes, several answers | Up to 20 options |
| Consent | A checkbox with a sentence | Label up to 120 characters; use for "I agree to…" |
| Heading / Text | Shown, not answered | No answer is stored |
| Image / Link | Shown, not answered | Images are limited in size |

Choice questions use either a fixed list you type in or a **Data list** (see Part 3). A dependent list, such as *City* shown after *Country*, is a data list whose options belong to a parent option.

### Question settings

| Setting | What it does |
| --- | --- |
| **Label** | The question text. A live counter shows the WhatsApp limit for that question type. |
| **Required** | The customer cannot continue without an answer. |
| **Hint under the question** | A short hint shown under the question (up to 80 characters). |
| **Type the options / Use a data list** | Choice questions either hold options you type in (each with a title, an optional description and optional side text such as a price), or point to a data list. The counter shows how many of the allowed options you have used. |
| **Only show options that belong to the answer of…** | For a dependent list: choose the earlier dropdown or single-choice question. The options shown are then limited to those that belong to the answer given there, for example the cities of the chosen country. |
| **Don't save to the contact** (dropdown) | Pick a contact field (name, company, email, mobile, country, city, job title and others) to copy the answer into the contact. |
| **Sensitive** (checkbox) | Stores the answer encrypted. Email and phone questions are always encrypted. |
| **Required format (regular expression)** | For text and number questions: an advanced check on the answer, with its own message when it does not match. |
| **Advanced: name used in automations** | The question key used in automation, for example `full_name` in `{Answer.full_name}`. It is created from the label and can be edited. Keys must be unique in the form. |

Tags are not set per question. Tags to add to the contact are a form-level setting under **After submission**.

## Part 2 — Test Before You Publish

Open the form and use:

- **Test of all paths**: Peikly fills in the form by itself along every route and reports whether each one reaches the confirmation page, whether data lists load and what each step returned (**What happened behind the scenes**). Nothing is saved or reserved.
- **Send to my phone**: sends the draft to your own WhatsApp so you can try it for real. WhatsApp only delivers a form inside an open conversation, so first send any message (for example "hi") from your phone to your business number; Peikly tells you if the conversation is closed. After sending, the dialog checks delivery and shows whether it arrived. Answers you submit this way are marked as tests, never count in statistics, and are hidden in **Responses** until you tick **Include tests** (an empty inbox offers a **Show test responses** button).

**Publish this form** is available only after a clean test of the current version. Any change after the test means you must test again.

Publishing sends the form to WhatsApp and makes it usable by customers. Before you confirm, the dialog reminds you that **a published form cannot be edited**. To change it, use **Make a copy** to create a new draft, publish the copy, then **Deprecate** the old version. Templates and workflows that point to the old version must be checked and pointed to the new one.

## Part 3 — Data Lists

**WhatsApp** → **Data Lists** holds reusable lists such as *Countries*, *Packages* or *Branches*. Use one list in as many forms and questions as you like.

- Create a list by typing options in the grid, or **Import** a CSV or Excel file. The import maps your columns to these fields:

| Column | Required | Meaning |
| --- | --- | --- |
| **Title (what people see)** | Yes | The option text the customer sees |
| **ID (stored in answers)** | No | A stable id. Answers store the id, so keep it fixed if you rename titles. If blank, one is created from the title. |
| **Description** | No | A longer line under the option |
| **Side text (e.g. price)** | No | Short text shown beside the option, up to 20 characters |
| **Parent ID (for dependent lists)** | No | The ID of the parent option (for example the country ID for a city) |
| **Capacity (seats / stock)** | No | Places available for this option |
| **Enabled (yes/no)** | No | Set to *no* to hide an option without deleting it |

The import shows a preview, and you choose **Replace** (the list becomes the file) or **Merge** (rows are matched by ID and the rest is kept).

- A built-in **Countries** list is ready to use.
- **Capacity**: give an option a number of places. Each completed form reserves one, a full option shows as *Sold out*, and two people can never take the last place. The reservations list shows each place with its code and lets you release it.
- **Languages**: add the same list in several languages. The list's first language is its default; the others hold translated titles and descriptions for the same options. When you use a list in a question, you choose which of its languages to show. Choose **Import** with a language to upload translations only; they are matched by ID.
- Changes to a list are live for customers immediately, without republishing the form.
- A list used by a published form cannot be deleted. Remove it from the forms that use it first.

A form's own text (labels and buttons) is in one language. For another language, **Make a copy** of the form and translate the copy.

## Part 4 — Send the Form

Choose the way that fits the moment. Each way ties the answers to the contact and to what sent the form.

### Option A: Template button (campaigns, workflows, scheduled messages)

Use this for broadcasts and for any message sent outside the 24-hour window.

1. Open **WhatsApp** → **Templates** → **New template** (or edit one). Follow [9.3](/docs/whatsapp-templates/) for the name, language and body.
2. Add a button and choose **Open a form**. Pick one of your **published** forms from the same WhatsApp Business Account. Set the button text (for example *Register now*).
3. Submit the template to Meta and wait for approval, as for any template ([9.3](/docs/whatsapp-templates/)). A template can have one form button.
4. Send the template from a campaign ([9.4](/docs/whatsapp-campaigns/)), a workflow step ([11.36](/docs/whatsapp-form-triggers-activities-and-conditions/)), the chat or the scheduler. Each recipient gets their own session, so every answer is linked to the contact and the campaign that produced it.

A form that is not published, or that belongs to another account than the template's number, does not appear in the **Open a form** list.

### Option B: Ice breaker or command (first contact and typed commands)

Use this when a customer starts a chat with your number. Open **WhatsApp** → **Ice Breakers** (CompanyAdmin). The page is titled **Ice breakers and commands** and needs a connected WhatsApp number, which you choose at the top.

1. Add up to **4 ice breakers**: the starter questions a customer sees when they first open the chat. Each is up to 80 characters, with no emoji.
2. Add up to **30 commands**: shortcuts the customer sees when they type "/", for example `/rsvp`. Each has a name (up to 32 characters) and a hint, and it can have no emoji.
3. For each one, tick **When someone taps this, reply with a form** (for a command: **uses**) and pick a published form. Then write the **Message that comes with the form** (up to 1024 characters) and the **Button text** (up to 20 characters, default "Open form").
4. Save. Peikly sends the list to WhatsApp. **Import** adopts ice breakers that already exist on the number at WhatsApp.

WhatsApp cannot attach a form to an ice breaker itself. When a customer taps the ice breaker, or types the command, Peikly recognises the text and replies with the form straight away. Workflows on the same message still run.

### Option C: The chat (within 24 hours)

In a WhatsApp conversation, the **Send form** button (next to **Send Template**) opens the list of published forms. Choose one, edit the message and send. The button is greyed out when the conversation window is closed or the contact is not linked to a contact yet, and its tooltip says why. Outside the window, use Option A.

### Option D: The contact's profile

On a contact's profile, the **Forms** card has **Send a form**: choose the form, edit the message and send. This also needs the 24-hour window to be open.

### Option E: A workflow

In a workflow, use **Send WhatsApp Form** ([11.36](/docs/whatsapp-form-triggers-activities-and-conditions/)). It needs the 24-hour window, so use a template button when the contact may not have written to you recently.

## Part 5 — Use the Answers in Automation

Form triggers, actions and conditions are described in [11.36](/docs/whatsapp-form-triggers-activities-and-conditions/). The most useful pieces for forms are:

Recipes that work well:

- **Confirmation message:** trigger *WhatsApp Form Submitted* (choose the form) → *Send WhatsApp* with the text "Thanks {Answer.full_name}". Use a template if the window may be closed.
- **Hot-lead follow-up:** trigger *WhatsApp Form Page Completed* on the package page → condition *Form Answer* `package` is `vip` → add the tag *vip* and notify your sales user.
- **Reminder for people who stopped:** trigger *WhatsApp Form Abandoned* → wait one day → send a template with a form button.
- **Keep contact details up to date:** *Update Contact from Form Answers* in the workflow, or the **Save to contact field** settings on the question, both work. Use only empty fields if you do not want to overwrite existing details.

Form triggers can start for a number that is not a contact yet. Put **Add/Upsert Contact** before steps that need a contact.

## Part 6 — Build a Form with the Assistant

Use **⚡ Quick Actions** → **Create WhatsApp Form**, or ask the support assistant to make a form. Describe what it is for in your own words, for example "a birthday registration in Arabic for 12 May at 7 pm". The assistant asks for:

- the language every customer-facing text is written in,
- the event or appointment date and time, if there is one,
- any must-have questions.

It then creates a **draft** in the designer and opens it. The draft is never published, and it does not start sending anything. Review the questions, run **Test of all paths**, fix anything in the Problems panel, then publish.

**Lists of options.** When a question needs a real list (countries, cities, branches, packages, services, time slots), the assistant does not type the options into the question. It first looks through your existing **Data Lists** ([Part 3](/docs/whatsapp-forms/)) for a similar one, such as a list named *Packages* when you ask for packages, and uses it. For countries it uses the built-in **Countries** list. If you have nothing similar, it creates a new data list with a handful of sample options in the form's language and attaches it. The assistant tells you which lists it reused and which it created. Short fixed choices such as Yes/No or a rating stay inside the question.

Sample lists are placeholders. Open **WhatsApp** → **Data Lists**, replace them with your real options and add seat limits if you need them. Changes are live in the form at once. Dependent lists (such as cities that depend on a country) are not created by the assistant.

What the assistant does **not** do:

- It does not invent seat limits, prices or dates you did not give it.

## Responses

**WhatsApp** → **Forms** → **Responses** is your inbox.

- One row per submission, with a column per question using the questions' own labels. Filter by date, status or source, and search.
- Open a row to see all answers, the contact (or create one), the source, any reservation code, and add a note.
- Mark responses **New**, **Handled** or **Archived**, in bulk if you like.
- **Export** to CSV or Excel.
- Email, phone and sensitive answers are stored encrypted.

Each contact's profile shows their submissions in the **Forms** card and in the **Timeline**.

## Notifications

Whenever a form is submitted, CompanyAdmins and every user with the Forms permission get a notification, narrowed by the form's own setting (everyone with access, selected people, or nobody). A burst of submissions is summed up in one notification. You are also notified if WhatsApp blocks or throttles a form.

## Statistics

**WhatsApp** → **Forms** → **Statistics** shows all forms together or one form at a time, for the dates you choose:

- Sent, opened, submitted and abandoned, with open and completion rates and the median time to complete.
- A daily trend, results by source (campaign, template, chat, ice breaker, workflow) and the busiest hours.
- For one form: a page-by-page funnel showing where people give up, the answers chosen for each choice question, and how full each reserved option is.

Test submissions are left out unless you tick **Include tests**.

### People Who Did Not Finish

When you view one form, its statistics page lists the people who did not finish it, one row per person, using their latest attempt. Two views are available:

- **Started, not finished**: people who opened the form and stopped. The row shows the last page they reached (for example "3/5") and when they were last active.
- **Sent, never opened**: people who received the form but never opened it.

A person who went back later and finished is not listed. **Remind** sends the form again to that contact with a message you write. It follows the same 24-hour window rule as **Send a form**. Long lists show the most recent people first; narrow the date range to see the rest.

## Contact Potential

A contact who opens a form they were sent scores higher than one who ignored it, and completing a form scores highest ([5.8](/docs/contact-potential-lead-scoring/)).

## Limits

| Item | Limit |
| --- | --- |
| Pages per form | 12 |
| Questions per page | 45 |
| Routing rules per page | 10 |
| Page title / button text | 30 / 35 characters |
| Question label | 20 characters (short text, number, email, phone, website, dropdown), 30 (choice), 40 (date), 120 (consent), 80 (heading) |
| Helper text | 80 characters |
| Options: dropdown / single or multiple choice | 200 / 20 |
| Option title / description / side text | 30 / 300 / 20 characters |
| Ice breakers / commands | 4 / 30; ice breaker text 80 characters, no emoji |

## Errors, Messages, and Common Fixes

| Message | Why It Happens | How to Fix |
| --- | --- | --- |
| **Forms** is missing from the WhatsApp menu | Not in your plan, no permission, or unavailable on this deployment | Ask your CompanyAdmin; check your plan |
| `Run the test first. A form can only be published after it passed the test in its current state.` | The form changed after its last test, or was never tested | Run **Test of all paths**, then publish |
| `Publish the form before sending it to customers.` | Only published forms can be sent | Publish the form first |
| A form in the **Open a form** list is missing | It is not published, or belongs to another WhatsApp Business Account than the template's number | Publish it, or choose a number from the same account |
| `WhatsApp only allows a form inside an open conversation` | The contact has not written to you in 24 hours | Send a template with a form button instead |
| **Sold out** shown on an option | Its capacity is used up | Raise the capacity on the data list, or release unused reservations |
| The form shows *temporarily unavailable* | Peikly could not reach its storage for a moment | Ask the customer to try again; contact support if it persists |
| A form shows **Blocked** or **Throttled** | WhatsApp paused it because its connection to Peikly was unhealthy | Open the form to see the reason; Peikly rechecks automatically |
| Ice breaker won't save | Longer than 80 characters, contains an emoji, or more than 4 ice breakers | Shorten it, remove the emoji, or delete another |
| `WhatsApp Forms can't … because Meta hasn't granted the permission …` | Meta was connected without a permission forms need, or it was later revoked | Open **Meta Platform** → **Permissions**, click **Re-launch Meta** and approve it ([8.3](/docs/refresh-meta-permissions/)) |
| `WhatsApp Forms needs your Meta account connected.` | Meta is not connected, or the connection was removed | Connect Meta from the plug icon in the top bar ([8.1](/docs/connect-to-meta-first-time/)) |
| A form cannot be edited | It is published | Use **Make a copy** to create an editable new version |
| The form does not start when the customer taps a command | The command was typed without its slash, or the name differs | Customers must type the slash and the exact command name |
| The assistant created a list with options that are not yours | It had no similar list, so it made a sample one | Edit the list under **WhatsApp** → **Data Lists** and replace the samples |
| The assistant did not use my existing list | The names were too different to match | Choose your list on the question in the designer (**Use a data list**) |