# WhatsApp Forms

> 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.

## 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.

> Forms vs. Templates: a template 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.

## 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, the WhatsApp Form step sends your published form as an interactive message.

## Build a form

1. Go to WhatsApp Forms and click Create Form to open the builder.
2. Set the title (for your reference only — not shown to the customer), an optional purpose, and the audience type (see the audience table below).
3. 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.
4. Add fields to each screen (see the field-type table). For each field, set the label, whether it's required, the options (for choice fields), and an optional hint.
5. Optionally set a per-contact submission limit with a "limit reached" note, a custom Send button label, and a thank-you note.
6. Click Save draft — the form is saved as a draft.

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

> 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.

## Field types

These are the field types you can add to a form:

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, WaDesk 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. WaDesk picks up where it left off rather than starting over.

> WaDesk handles the technical side. You design your screens and fields visually; WaDesk 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.

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

## Send & track submissions

- Send: a published form is sent by the Flow builder's WhatsApp Form step as an interactive message. WaDesk tags each send so the customer's answers can be matched back to the exact conversation that's waiting.
- Collect: when the customer submits, WaDesk 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.