# How WhatsApp Flows Work

> Meta's WhatsApp Flows explained - Flow JSON, screens and components, actions, endpoints, encryption, and the status lifecycle.

Source: https://docs.theavoxai.com/whatsapp/flows

**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](https://docs.theavoxai.com/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:

```json
{
  "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.

## 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](https://docs.theavoxai.com/flows#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](https://docs.theavoxai.com/automation/actions#use-flows).

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](https://docs.theavoxai.com/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.