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

# WhatsApp Forms: Interactive In-Chat Data Collection

> Build multi-screen interactive forms that customers fill in without leaving WhatsApp. Cloud API only; sent from flows and collected as structured submissions.

<Warning>
  **Official Cloud API only.** WhatsApp Forms are built on Meta's technology and require the **WhatsApp Cloud API** connection. On an Unofficial API or Twilio workspace this feature is hidden, and visiting it directly just sends you back to the *More* menu with an explanation. Connect an official Cloud API number to enable it.
</Warning>

## Overview

**WhatsApp Forms** are interactive forms that appear right inside the chat — the customer fills out fields (text, dropdowns, choices, dates) on a WhatsApp card and submits without leaving the conversation. You build a form once, publish it to Meta, and then send it from a flow.

Find them under **More → WhatsApp Forms**. The list shows each form's status (draft / published), how many fields it has, and how many submissions it's received, plus a workspace-wide submissions total.

<Info>
  **Forms vs. Templates:** a [*template*](/features/templates) is a message you send out. A *form* is an interactive card the customer fills in. Use a form when you need structured information back — lead capture, surveys, appointment requests, support intake.
</Info>

## Prerequisites

* The workspace must use the **WhatsApp Cloud API** (official) connection.
* A connected Meta account with valid credentials — publishing fails (and tells you what's missing) if anything is incomplete.
* To actually send a form you use it inside a flow: in the [Flow Builder](/features/flow-builder), the **WhatsApp Form** step sends your published form as an interactive message.

## Build a Form

<Steps>
  <Step title="Open the builder">
    Go to **WhatsApp Forms** and click **Create Form** to open the builder.
  </Step>

  <Step title="Set identity and audience">
    Set the **title** (for your reference only — not shown to the customer), an optional **purpose**, and the **audience type** (see the [audience mapping](#audience-type) table).
  </Step>

  <Step title="Add screens">
    Add one or more **screens** from the left rail. Each screen holds a set of fields; a multi-screen form moves from one screen to the next.
  </Step>

  <Step title="Add fields">
    Add **fields** to each screen (see the [field types](#field-types) table). For each field, set the label, whether it's required, the options (for choice fields), and an optional hint.
  </Step>

  <Step title="Optional settings">
    Set a per-contact **submission limit** with a "limit reached" note, a custom **Send button label**, and a **thank-you note**.
  </Step>

  <Step title="Save draft">
    Click **Save draft** — the form is saved as a *draft*.
  </Step>
</Steps>

The whole form is saved each time, and a live WhatsApp-bubble preview on the right shows how the customer will see each screen.

<Info>
  **Field IDs matter.** Each field has a short ID. That ID is how you reference the field's answer later in your flow — write it as `{{form_<field_id>}}`. Keep each field's ID unique within a form.
</Info>

## Field Types

| Field type      | What it is                                                          |
| --------------- | ------------------------------------------------------------------- |
| **Short text**  | Single-line text.                                                   |
| **Paragraph**   | Multi-line text.                                                    |
| **Email**       | Text checked as a valid email.                                      |
| **Phone**       | Text checked as a valid phone number.                               |
| **Number**      | Numbers only.                                                       |
| **Dropdown**    | Single choice from a list.                                          |
| **Single pick** | Single choice, shown as radio buttons.                              |
| **Multi pick**  | Multiple choices (checkboxes).                                      |
| **Date**        | Date selection.                                                     |
| **Heading**     | A display-only section title — **not collected** in the submission. |

### Audience type

The audience type you pick tells Meta how to classify your form:

| Audience type | Meta classifies it as |
| ------------- | --------------------- |
| Lead capture  | Lead generation       |
| Survey        | Survey                |
| Feedback      | Survey                |
| Appointment   | Appointment booking   |
| Onboarding    | Sign-up               |
| Support       | Customer support      |
| Other         | Other                 |

## Publish to Meta

When you click **Save & publish**, Soneka sends your form to Meta and makes it live for you — no technical steps to do yourself. On success the form's status changes to **published**, the publish time is recorded, and the form becomes selectable in the Flow Builder's WhatsApp Form step.

If publishing fails, the error message is saved on the form and shown so you can fix it and try again. Soneka picks up where it left off rather than starting over.

<Info>
  **Soneka handles the technical side.** You design your screens and fields visually; Soneka turns them into the exact format Meta requires — including making sure every field actually captures its answer, and that multi-screen forms move from screen to screen and send all the answers back at the end. You never have to touch any code.
</Info>

<Warning>
  **Editing un-publishes.** Saving changes to a *published* form drops it back to **draft**. You must publish again before the new version is live.
</Warning>

## Send & Track Submissions

* **Send:** a published form is sent by the Flow Builder's **WhatsApp Form** step as an interactive message. Soneka tags each send so the customer's answers can be matched back to the exact conversation that's waiting.
* **Collect:** when the customer submits, Soneka receives the answers, matches them to the right contact and conversation, and records them as a **submission** (and bumps the form's count).
* **Continue the flow:** the answers flow back into the conversation so later steps can use each one. Reference a field's answer as `{{form_<field_id>}}`.
* **Limit:** if you set a per-contact submission limit, the customer sees your "limit reached" note instead of being able to submit again.

## Manage Forms

* **Duplicate:** makes a copy as a fresh draft (titled "(copy)", with zero submissions) so you can build a variant without touching the live one.
* **Edit:** reopen the builder anytime — remember that saving changes to a published form returns it to draft until you publish again.
* **Delete:** removes the form. Forms belong to your workspace — you can only see, edit, publish, or delete forms in your own workspace.

## Troubleshooting

| Symptom                                                 | Cause & fix                                                                                                                                                                                            |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Forms menu is missing / a link sends you back to *More* | The workspace isn't on the official Cloud API connection. Connect a Cloud API number.                                                                                                                  |
| "No Meta account configured" on publish                 | No Meta account is connected for this workspace — connect Meta first.                                                                                                                                  |
| "Meta credentials missing"                              | The account is connected but its credentials are blank. Re-enter them.                                                                                                                                 |
| Publish fails with a Meta error                         | The exact message is shown on the form. Common causes: an unsupported category, or content Meta rejects. Fix and publish again.                                                                        |
| Submissions never arrive                                | The form must be sent *from the WhatsApp Form step inside a flow*; a form sent any other way can't link the answers back. Also confirm WhatsApp is set up to deliver incoming messages for the number. |
| Edited form behaves like the old version                | Editing drops it to draft — publish again to push the new version live.                                                                                                                                |