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

# WhatsApp Flows

> Send a Meta-built in-chat form to a contact from a WhatsApp automation, and what you can and can't do with their answers.

A WhatsApp Flow is Meta's own in-chat form. Instead of sending a contact a link to a web page,
you send them a button inside the conversation; they tap it, a form opens over the chat — text
boxes, dropdowns, dates, whatever you built — and they fill it in without ever leaving
WhatsApp. It is Meta's feature, not DMLY's: you design the form in **Meta's Flow Builder**, and
DMLY sends it.

DMLY's side is one step in the flow builder, **WhatsApp Form (Flow)**. It sends the form's
opening message and waits. Read the two limits below before you build anything around it —
they decide whether this step is any use to you.

<Warning>
  **The answers a contact submits do not come back into DMLY.** No later step can read them, no
  contact field is filled in, and nothing about the submission is stored. Whatever the form
  collects, you collect it in Meta — not here. If you need the answer inside your automation,
  ask for it as a normal question in the flow instead.
</Warning>

<Note>
  **This is WhatsApp only.** The step appears in the builder's **WhatsApp** group and only when
  the automation you have open is on a WhatsApp channel. Open a Messenger, Instagram, Telegram
  or SMS automation and the step is not in the palette at all.
</Note>

## Where it is

There is no **WhatsApp Flows** entry in the sidebar. The only way to reach any of this is
inside a flow:

**Messaging → Automation →** open or create an automation on a WhatsApp channel **→** the
builder canvas **→** the step palette **→ WhatsApp → WhatsApp Form (Flow)**.

Everything else — the list of your forms, the **Sync from Meta** button — lives inside that
step's settings panel once you've dropped it on the canvas.

<Note>
  Automation needs a connected channel before it opens at all. With no channels you'll be asked
  to connect one first — start at [Connect WhatsApp](/channels/whatsapp).
</Note>

## Before you start

<Steps>
  <Step title="Build the form in Meta">
    Design and save the flow in Meta's Flow Builder, in the same WhatsApp Business account your
    DMLY channel uses. DMLY has no way to create, edit or delete a form — it only reads the
    list. If the form doesn't exist in Meta, there is nothing for this step to send.
  </Step>

  <Step title="Note the screen you want it to open on">
    A flow is made of named screens. You'll need the name of the first one — DMLY assumes
    `WELCOME` unless you tell it otherwise.
  </Step>

  <Step title="Connect the WhatsApp channel">
    The form list is pulled from the WhatsApp Business account behind your connected
    [WhatsApp channel](/channels/whatsapp). A channel that isn't fully connected is skipped
    silently — you'll just get no forms and no error.
  </Step>
</Steps>

<Note>
  **The form does not have to be published.** A form still in draft sends too — DMLY notices
  it's a draft and sends it in Meta's test mode automatically, so you can try it end to end
  before you publish. The picker labels each one, so you can see which is which: *Lead form
  (published)*, *Return request (draft)*. This only works when you pick the form from the
  **Form** picker — a draft named by hand in **Flow name (manual)** is sent as if it were
  published, and won't arrive.
</Note>

## Add the step

<Steps>
  <Step title="Drop it on the canvas">
    In an automation on a WhatsApp channel, find **WhatsApp Form (Flow)** in the **WhatsApp**
    group and connect it where the conversation should offer the form.
  </Step>

  <Step title="Pull your forms in">
    Select **Sync from Meta**. DMLY reads the form list from your WhatsApp Business account and
    fills the **Form** picker. It syncs names and statuses only — never the form's contents, so
    a design change in Meta needs no re-sync.

    Until you do this, the picker says *No synced forms yet — press "Sync from Meta", or type
    the flow name below.* Re-run it whenever you add a form in Meta.
  </Step>

  <Step title="Pick the form">
    Choose it under **Form**. Picking it this way is the reliable option: DMLY stores the form's
    Meta ID, so renaming it in Meta later won't break the step.

    If the form isn't in the list, **Flow name (manual)** lets you type its *Exact name in
    Meta's Flow Builder* instead. This matches by name, so it breaks the moment anyone renames
    the form. Use it only as a stopgap.
  </Step>

  <Step title="Write the message and the button">
    **Message** is the text the contact sees, and it takes tokens like `{{first_name}}`.
    **Button text (CTA)** is the label on the button that opens the form — **20 characters
    maximum**, and the field counts them for you.

    The defaults are **Fill the form** and *Tap below — it takes 30 seconds.* Both are worth
    replacing with something specific: *Book your slot*, *Start your claim*.
  </Step>

  <Step title="Set the entry screen">
    **Entry screen** is the screen in your Meta form the contact lands on. Leave it as `WELCOME`
    unless your form's first screen is named something else.
  </Step>

  <Step title="Publish the flow">
    Connect the **COMPLETED** output to whatever should happen next, then
    [publish the automation](/automation/publishing-bots) as usual.
  </Step>
</Steps>

An empty **Message**, an empty button label, a button label over 20 characters, or a missing
form name each raise an amber warning on the step. None of them stop you saving or publishing —
they are reminders, not blocks. The form warning also checks the *name* rather than the picked
form, so a step with a hand-typed name and nothing selected raises nothing at all.

## What COMPLETED actually means

The step has one output, **COMPLETED**. It is tempting to read that as "the contact submitted
the form". It isn't.

**COMPLETED fires on the contact's next message, whatever that message is.** They submit the
form — it fires. They ignore the form and type *hi* — it fires just the same. The step cannot
tell the two apart, and it does not know whether anyone filled anything in.

So treat **COMPLETED** as *the contact said something after we sent the form*. Don't build a
branch behind it that assumes you now have their details, and don't thank them for a submission
you can't confirm happened. A neutral follow-up — an offer to help, a handover to a
teammate — survives both outcomes.

## What you get back

Nothing you can use in DMLY. This is the thing to understand before you plan around this step:

* **The submitted answers are not captured.** No later step can read a field the contact filled
  in. There is no token for it.
* **No contact fields are updated** from a submission.
* **The conversation records that you sent the form**, and the step is counted in the
  automation's stats — but not what came back.

If you need an answer inside your automation, ask for it in the flow itself, where the reply is
captured and can be branched on. The **Request Phone Number** step is the example worth copying:
it asks for a number and actually keeps it, saving it to the contact.

<Tip>
  This step is at its best when the form is the *destination*, not a data-collection stage — a
  Meta lead form your team works from in Meta, a claim or intake form whose answers you read on
  Meta's side. Use the automation to get the right people to the form at the right moment, and
  handle the answers where they land.
</Tip>

## Troubleshooting

<Accordion title="The step isn't in the palette">
  The automation isn't on a WhatsApp channel. The **WhatsApp** group of steps only appears on a
  WhatsApp automation. Rebuild it on a [WhatsApp channel](/channels/whatsapp) — there's no way
  to add this step to a Messenger, Instagram, Telegram or SMS flow.
</Accordion>

<Accordion title="Sync from Meta returns nothing">
  Either your WhatsApp Business account genuinely has no flows in it — build one in Meta's Flow
  Builder first — or the channel isn't carrying the credentials the sync needs, in which case it
  is skipped without an error. Reconnect the channel and try again.
</Accordion>

<Accordion title="It says the forms came from a sandbox catalog">
  *Forms refreshed (sandbox catalog) — connect a live WhatsApp number to pull real Meta Flows.*
  means you're on a demo setup, and the forms listed are samples, not yours. Connect a live
  WhatsApp number.
</Accordion>

<Accordion title="A template says Requires WA Flow">
  Ready-made automations in the [template library](/automation/templates) that contain this step
  carry a **Requires WA Flow** chip until your workspace has a synced form. It's a reminder, not
  a block — install the template now and sync a form afterwards. Until you do, the step has no
  form to send.
</Accordion>

<Accordion title="The form stopped sending after we renamed it in Meta">
  The step was matching by name. Open it, run **Sync from Meta**, and pick the form from the
  **Form** picker instead of typing its name — that matches on the form's ID and survives
  renames.
</Accordion>

<Accordion title="Nothing arrives and the flow stalls at this step">
  A send that fails outright fails the step rather than waiting, and the reason is written to
  your [logs](/troubleshooting/logs) — look for a `send_failed` entry with the error from Meta.
</Accordion>

## Next

<Columns cols={2}>
  <Card title="Flow builder" icon="diagram-project" href="/automation/flow-builder">
    The canvas this step lives on, and how a contact reaches it.
  </Card>

  <Card title="Connect WhatsApp" icon="whatsapp" href="/channels/whatsapp">
    The channel this step needs, and where the form list comes from.
  </Card>

  <Card title="Template library" icon="file-lines" href="/automation/templates">
    Ready-made automations, including the ones that use this step.
  </Card>
</Columns>