How WhatsApp Flows Work

WhatsApp Flows are Meta's in-chat forms. A customer taps a button in a message, a form opens inside WhatsApp, they fill it in screen by screen, and their answers come back to you. This page explains how Flows work on Meta's side. For building and managing them in Avox, see Flows.

Flow JSON#

Every Flow is described by one JSON document, the Flow JSON. Its main parts:

Field	What it holds
`version`	The Flow JSON version. Avox's blank Flow starts at `"6.0"`.
`screens`	The list of screens, in any order. Each has a unique `id`.
`data_endpoint_uri`	Your endpoint's URL, for Flows that fetch live data. Avox fills this in from the endpoint URL you enter.

This is the blank Flow Avox's editor starts with when you build from scratch:

{
  "version": "6.0",
  "screens": [
    {
      "id": "MAIN",
      "title": "New Flow",
      "terminal": true,
      "success": true,
      "data": {},
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "Form",
            "name": "form",
            "children": [
              { "type": "TextInput", "name": "full_name", "label": "Full name", "input-type": "text", "required": true },
              { "type": "Footer", "label": "Submit", "on-click-action": { "name": "complete", "payload": {} } }
            ]
          }
        ]
      }
    }
  ]
}

Screens and components#

A screen is one page of the form. It has an id, a title shown at the top, and a layout holding its components:

Text - headings and body text, such as TextHeading and TextBody.
Inputs - fields the customer fills in, such as TextInput and Dropdown. Each has a name that labels its answer, and can be required.
Form - groups the inputs on a screen.
Footer - the button at the bottom of the screen. Its on-click-action decides what the button does.

A screen marked terminal: true is a last screen - the Flow can finish there.

9:41

Riverside Cafe

Tell us how we did

Quick feedback

It takes less than a minute.

Rating

Excellent

Anything else?

text

Actions#

A component's on-click-action tells WhatsApp what to do when the customer taps it. Avox's Actions panel lists every action your Flow uses and explains it:

Action	What it does
`complete`	Submits the form and closes the Flow, returning the collected data to WhatsApp.
`navigate`	Moves to another screen in this Flow without submitting anything.
`data_exchange`	Sends this screen's data to your endpoint and waits for its response before continuing.
`update_data`	Updates this screen's own data without leaving it.
`open_url`	Opens an external URL in the customer's browser.

Categories#

Each Flow belongs to one or more of Meta's categories: Sign up, Log in, Appointment booking, Lead generation, Shopping, Contact us, Customer support, Survey, and Other.

Static Flows and endpoint Flows#

Static Flows contain everything in the Flow JSON. They work as soon as they're published.
Endpoint Flows use data_exchange to ask your own server for live data while the customer fills them in - free appointment slots, a price, a sign-in check.

For an endpoint Flow, Meta calls your server directly and encrypts every request:

1
You register a public key
You create an RSA key pair and register the public key with Meta. Avox generates the pair in your browser and registers the public half for you; the private key stays with you.
2
Meta encrypts each request
Meta encrypts the request with a fresh AES key, and encrypts that AES key with your public key.
3
Your server decrypts and answers
Your server decrypts the AES key with its private key, decrypts the request, and encrypts its response with the same AES key and an inverted IV.
4
Meta health-checks the endpoint
Meta sends action: "ping" requests to check your endpoint. Your server answers with {"data": {"status": "active"}}, encrypted.

If your server can't decrypt a request, it should answer with HTTP status 421, which tells Meta to fetch your public key again. Avox's endpoint snippet does all of this - see Live endpoints.

Sending a Flow#

A published Flow is sent as an interactive Flow message: some text and a button (the call to action) that opens the Flow. In Avox, the automation action Use Flows sends one, with the button label you choose. See Actions.

When the customer finishes, WhatsApp sends their answers back as a reply. Avox stores each completed response, and the count for the last 30 days appears on Overview.

The status lifecycle#

Meta status	Meaning	Shown in Avox as
`DRAFT`	Created but not published. It can be edited and deleted.	Draft on Meta
`PUBLISHED`	Live. It can be sent, and it can no longer be deleted.	Published
`DEPRECATED`	Retired for good. It can't be sent again, and this can't be undone.	Deprecated
`THROTTLED`	Meta has temporarily limited how often it can be sent.	Throttled
`BLOCKED`	Meta has stopped it from being sent.	Blocked

Publishing is one-way. Once published, a Flow is retired by deprecating it.
Throttled and Blocked are Meta's decisions about a Flow's health. Meta tells Avox when they happen, Avox updates the status, and it emails the Switchboard's Admins.
In Avox, Create & publish creates the Flow on Meta, uploads its JSON, and publishes it in one step. Meta's validator checks the JSON during upload; if it finds problems, the Flow isn't published.