Flow JSON

Flow JSON is the format Meta uses to describe a WhatsApp Flow: which screens it has, which fields and texts appear on them and what each button does. WhatsApp reads this description and renders the form inside the chat.

What is Flow JSON?

Behind every WhatsApp Flow is a description in JSON format, the Flow JSON. It defines which screens the flow has, which components sit on them and what happens when a button is tapped: go to the next screen, send data to a server or complete the flow. Components include headings, text, input fields, selection lists, a date picker, opt-in checkboxes and photo or document upload.

The main top-level parts:

  • version: the format version. It decides which components are available.
  • screens: the list of screens and their components.
  • routing_model: the allowed paths between screens. Required for flows with a data endpoint.
  • data_api_version: the data API version, also only for flows with an endpoint.

Example: a one-screen flow

This Flow JSON describes a callback request. One screen with a required phone number field, and the footer button completes the flow and returns the entry:

{
  "version": "7.3",
  "screens": [
    {
      "id": "CALLBACK",
      "title": "Callback",
      "terminal": true,
      "layout": {
        "type": "SingleColumnLayout",
        "children": [
          {
            "type": "TextInput",
            "name": "phone",
            "label": "Phone number",
            "input-type": "phone",
            "required": true
          },
          {
            "type": "Footer",
            "label": "Submit",
            "on-click-action": {
              "name": "complete",
              "payload": { "phone": "${form.phone}" }
            }
          }
        ]
      }
    }
  ]
}

A real flow usually has several screens, choice fields and a consent checkbox. The principle stays the same: each screen is an entry in screens, and each button carries an action.

Versions and limits

Meta keeps developing the format, and new components arrive with new versions. Photo and document upload, for example, need version 4.0 or later, rich text needs 5.1. Older versions are eventually frozen: flows on them can no longer be published or updated, but can still be sent. Once a version expires, customers can no longer open flows built on it.

There are fixed limits too. A Flow JSON file may be at most 10 MB, a routing model has at most 10 branches, and each screen has caps, such as 50 components and one footer with the button.

Flow JSON, builders and messages

  • Flow JSON describes the form itself, its structure and logic.
  • A visual builder generates that JSON so nobody has to write it by hand.
  • The message that delivers a flow is something else: an interactive message or a template with a Flow button that only points to the published flow.

Flow JSON is also not the same as the automations in a flow builder. Those describe steps that run in the background, not a form inside the chat.

Why Flow JSON matters

  • Know the limits: if you know what the format allows, you won't plan forms that Meta later rejects.
  • Troubleshooting: when Meta rejects a flow, the reason is often in the JSON, for example a component the chosen version does not support yet.
  • Keep versions in view: when Meta freezes a version, flows on it need a newer version before their next change.

Flow JSON in SendSeven

In SendSeven's builder for WhatsApp Flows (beta) you don't write Flow JSON by hand. You build the flow in a visual editor, and SendSeven generates Flow JSON version 7.3, the version Meta currently recommends. The JSON tab shows two versions: the Builder JSON, which you can edit, and the WhatsApp JSON generated from it, which is read-only. The API also takes the Builder JSON.

You don't paste ready-made Flow JSON from other sources. Flows you built in Meta's own builder can be imported. Whether a flow needs a data endpoint is set in the builder: static flows are available from the Basic plan, dynamic ones from the Scale plan.

WhatsApp Flows is in beta. What a sent and a completed flow cost is explained in the WhatsApp Flows entry.

GDPR-compliant, EU-hosted. 14-day free trial.