WhatsApp Flow JSON: Screens, Components & Actions

What is Flow JSON?

Flow JSON is the document that describes a WhatsApp Flow — the multi-screen native forms customers fill in inside a chat. It lists every screen, the components on each screen (headings, text, inputs, dropdowns, date pickers, a footer button), how the screens connect and what happens when the customer taps a button. WhatsApp renders it natively on the phone; you author it in Meta's Flow Builder or write it by hand and upload it through the Flows API.

The top level is small: version (the Flow JSON schema version the Flow compiles against, such as 7.3), screens (an array of screen objects), and — only for Flows that call an endpoint — data_api_version (4.0, released in November 2025, adds endpoint security improvements such as a signed flow token; 3.0 is still accepted) plus a routing_model mapping each screen to the screens it may open next. Each screen has a unique id (SUCCESS is reserved), an optional title, a data block declaring the dynamic fields it expects (each with an __example__), terminal: true if it ends the Flow, and a layout of type SingleColumnLayout whose children are its components.

Components bind to data with expressions: ${data.slots} reads data passed to the screen, ${form.name} reads what the customer entered, and since version 4.0 ${screen.APPOINTMENT.form.date} reads another screen's values. Buttons run actions: navigate opens another screen with a payload, data_exchange sends a payload to your Flow endpoint and shows the screen it returns, and complete ends the Flow and sends its payload to your webhook. Flow JSON is the static definition; the Flow endpoint serves the dynamic data that fills it at run time.

Key takeaways

Flow JSON is the static definition of a WhatsApp Flow: screens, components, routing and actions in one versioned document.
The top level needs version and screens; Flows with an endpoint add data_api_version (4.0 is recommended) and a routing_model.
Each screen has an id, a SingleColumnLayout of components, and a terminal screen must include a Footer.
Actions move the customer: navigate to a screen, data_exchange to your endpoint, complete to finish and submit.
Flow JSON content is capped at 10 MB, and the routing model allows at most 10 branches.

Explore a two-screen Flow JSON

9 / 9

{
1  "version": "7.3",
2  "data_api_version": "4.0",
3  "routing_model": {
    "APPOINTMENT": [
      "DETAILS"
    ],
    "DETAILS": []
  },
  "screens": [
    {
      "id": "APPOINTMENT",
      "title": "Book a visit",
      "data": {
        "departments": {
          "type": "array",
4          "__example__": [
            {
              "id": "ortho",
              "title": "Orthodontics"
            }
          ]
        }
      },
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "Dropdown",
            "name": "department",
            "label": "Department",
5            "data-source": "${data.departments}"
          },
          {
            "type": "DatePicker",
            "name": "date",
            "label": "Preferred date"
          },
          {
            "type": "Footer",
            "label": "See free slots",
            "on-click-action": {
6              "name": "data_exchange",
              "payload": {
                "department": "${form.department}",
                "date": "${form.date}"
              }
            }
          }
        ]
      }
    },
    {
      "id": "DETAILS",
7      "terminal": true,
8      "sensitive": [
        "phone"
      ],
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "phone",
            "label": "Phone",
            "input-type": "phone"
          },
          {
            "type": "Footer",
            "label": "Confirm booking",
            "on-click-action": {
              "name": "complete",
9              "payload": {
                "date": "${screen.APPOINTMENT.form.date}",
                "phone": "${form.phone}"
              }
            }
          }
        ]
      }
    }
  ]
}

A booking Flow in the shape WhatsApp expects. Step through the fields that matter: the version, the routing model, a screen's dynamic data, a component's binding and the actions that move between screens.

Key facts at a glance

Flow JSON: key facts and limits

Required top level: version, screens
With an endpoint: data_api_version (4.0 recommended, 3.0 accepted) plus routing_model
Layout: SingleColumnLayout, the only layout type
Reserved screen id: SUCCESS
Routing: At most 10 branches; every route ends at a terminal screen
Size limit: Flow JSON content up to 10 MB
Core actions: navigate, data_exchange, complete
Cross-screen references: ${screen.<id>.form.<field>} from version 4.0

Flow JSON in code

1{
2  "version": "7.3",
3  "data_api_version": "4.0",
4  "routing_model": {
5    "APPOINTMENT": [
6      "DETAILS"
7    ],
8    "DETAILS": []
9  },
10  "screens": [
11    {
12      "id": "APPOINTMENT",
13      "title": "Book a visit",
14      "data": {
15        "departments": {
16          "type": "array",
17          "items": {
18            "type": "object",
19            "properties": {
20              "id": {
21                "type": "string"
22              },
23              "title": {
24                "type": "string"
25              }
26            }
27          },
28          "__example__": [
29            {
30              "id": "ortho",
31              "title": "Orthodontics"
32            }
33          ]
34        }
35      },
36      "layout": {
37        "type": "SingleColumnLayout",
38        "children": [
39          {
40            "type": "Dropdown",
41            "name": "department",
42            "label": "Department",
43            "required": true,
44            "data-source": "${data.departments}"
45          },
46          {
47            "type": "DatePicker",
48            "name": "date",
49            "label": "Preferred date",
50            "required": true
51          },
52          {
53            "type": "Footer",
54            "label": "See free slots",
55            "on-click-action": {
56              "name": "data_exchange",
57              "payload": {
58                "department": "${form.department}",
59                "date": "${form.date}"
60              }
61            }
62          }
63        ]
64      }
65    },
66    {
67      "id": "DETAILS",
68      "title": "Your details",
69      "terminal": true,
70      "sensitive": [
71        "phone"
72      ],
73      "data": {
74        "slots": {
75          "type": "array",
76          "items": {
77            "type": "object",
78            "properties": {
79              "id": {
80                "type": "string"
81              },
82              "title": {
83                "type": "string"
84              }
85            }
86          },
87          "__example__": [
88            {
89              "id": "1030",
90              "title": "10:30 am"
91            }
92          ]
93        }
94      },
95      "layout": {
96        "type": "SingleColumnLayout",
97        "children": [
98          {
99            "type": "RadioButtonsGroup",
100            "name": "slot",
101            "label": "Pick a time",
102            "required": true,
103            "data-source": "${data.slots}"
104          },
105          {
106            "type": "TextInput",
107            "name": "name",
108            "label": "Full name",
109            "required": true
110          },
111          {
112            "type": "TextInput",
113            "name": "phone",
114            "label": "Phone",
115            "input-type": "phone",
116            "required": true
117          },
118          {
119            "type": "Footer",
120            "label": "Confirm booking",
121            "on-click-action": {
122              "name": "complete",
123              "payload": {
124                "department": "${screen.APPOINTMENT.form.department}",
125                "date": "${screen.APPOINTMENT.form.date}",
126                "slot": "${form.slot}",
127                "name": "${form.name}",
128                "phone": "${form.phone}"
129              }
130            }
131          }
132        ]
133      }
134    }
135  ]
136}

Two screens, one endpoint call, one completion payload. Use the newest version Meta lists as supported when you build yours.

How does Flow JSON work?

Choose a version and declare capabilities
Set version to a schema version Meta lists as supported for publishing — 7.3 is the newest in Meta's changelog at the time of writing, and versions up to 5.0 can no longer be published. Add data_api_version and routing_model only if the Flow uses an endpoint.
Lay out the screens
Give each screen an upper-case id that says what it is for (APPOINTMENT, DETAILS), a short title and a SingleColumnLayout of components. Mark the last screen terminal: true and give it a Footer.
Declare dynamic data
List every field a screen receives in its data block as a JSON Schema type with an __example__, then bind components to it with ${data.field}.
Wire the actions
Use navigate for moves that need no server, data_exchange when your endpoint must compute the next screen, and complete on the terminal Footer with exactly the payload you want at the webhook.
Upload and validate
Upload the file as a FLOW_JSON asset with POST /{FLOW_ID}/assets. The response lists validation_errors, and a Flow with errors cannot be published.

Example: A two-screen booking Flow in Chennai

A Chennai dental clinic's booking Flow has two screens. APPOINTMENT shows a Dropdown of departments bound to ${data.departments} and a DatePicker; its Footer runs data_exchange so the clinic's endpoint can return only the free slots for that date. DETAILS is terminal: it lists the slots as radio buttons, asks for name and phone — with phone marked sensitive, so the completion summary masks it — and its Footer runs complete with the form values and ${screen.APPOINTMENT.form.department}. The routing_model is just {"APPOINTMENT": ["DETAILS"], "DETAILS": []}. The whole file is under 4 KB, lives in the clinic's Git repository and is uploaded by its deploy pipeline, which fails the build if validation_errors is not empty.

Common wrong turns

Common mistakes with Flow JSON

Using data_exchange without an endpoint
data_exchange only works when the Flow has data_api_version, a routing_model and an endpoint_uri. For a static form, use navigate between screens and complete at the end.
Forgetting __example__
Every field declared in a screen's data block needs an example value. Without it validation fails and the Flow cannot be published.
Heavy completion payloads
The complete payload reaches your webhook inside the flow response message. Send only the fields you will store, and never base64 images.
Assuming an edit reaches every customer
Uploading new Flow JSON to a published Flow returns it to Draft, and only messages sent after you publish again use the new file; Flows already delivered keep the old one. Make the webhook accept both payload shapes for a while, keep every version in Git, and clone instead when the live version must keep running untouched.
Routes that don't match the buttons
If a navigate action or an endpoint response targets a screen the routing_model does not allow, the transition fails on the device and counts towards client error alerts. Generate both from one source.

Why does Flow JSON matter?

Every behaviour of a Flow — which questions are asked, in what order, what is checked on the device and what goes to your server — lives in this one file. Teams that treat it as code, with version control, review and automated validation, ship Flows that work first time. Teams that hand-edit it under pressure meet validation errors that block publishing, broken screen transitions that count against client error rates, and edits to a live Flow that never reach the customers who already received the old version.

Good practice

Best practices for Flow JSON

Keep Flow JSON in Git and upload it from CI, failing the build on any validation_errors.
Name screens after their purpose; the ids appear in endpoint requests and logs.
Mark personal fields with sensitive (version 5.1 and later) so the completion summary masks them.
Prefer navigate when no server data is needed — every data_exchange adds latency and a failure point.

Flow JSON FAQs

Where do I write Flow JSON?+

In Meta's Flow Builder in WhatsApp Manager, or in any editor and then uploaded through the Flows API. The Builder shows a live preview; the API route (`POST /{FLOW_ID}/assets`) suits teams that keep Flow JSON in version control and deploy it from CI.

Which Flow JSON version should I use?+

Use the newest version Meta lists as supported for publishing, unless you depend on behaviour that changed. Newer versions add components and features such as cross-screen references (4.0) and `sensitive` fields (5.1); older versions may remain valid only for sending existing Flows.

What is the difference between Flow JSON and a Flow endpoint?+

Flow JSON is the static definition of screens and actions; the endpoint is a server that returns dynamic data while the Flow runs. Every Flow has Flow JSON, but only Flows whose screens depend on live data need an endpoint.

What is routing_model in Flow JSON?+

It maps each screen id to the screens it can move to next, and it is required when the Flow uses an endpoint. You list forward moves only — back navigation is automatic — with at most 10 branches, and every route must end at a terminal screen.

See InfiQ pricing

Flow JSON

What is Flow JSON?

Explore a two-screen Flow JSON

Flow JSON: key facts and limits

Flow JSON in code

How does Flow JSON work?

Choose a version and declare capabilities

Lay out the screens

Declare dynamic data

Wire the actions

Upload and validate

Example: A two-screen booking Flow in Chennai

Common mistakes with Flow JSON

Using data_exchange without an endpoint

Forgetting example

Heavy completion payloads

Assuming an edit reaches every customer

Routes that don't match the buttons

Why does Flow JSON matter?

Best practices for Flow JSON

Flow JSON FAQs

See how this works on InfiQ

Try it on the official WhatsApp Business API

See how this works on InfiQ

Flow JSON

What is Flow JSON?

Explore a two-screen Flow JSON

Flow JSON: key facts and limits

Flow JSON in code

How does Flow JSON work?

Choose a version and declare capabilities

Lay out the screens

Declare dynamic data

Wire the actions

Upload and validate

Example: A two-screen booking Flow in Chennai

Common mistakes with Flow JSON

Using data_exchange without an endpoint

Forgetting __example__

Heavy completion payloads

Assuming an edit reaches every customer

Routes that don't match the buttons

Why does Flow JSON matter?

Best practices for Flow JSON

Flow JSON FAQs

See how this works on InfiQ

Try it on the official WhatsApp Business API

See how this works on InfiQ

Forgetting example