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

# Flow

> Send a WhatsApp interactive Flow message

## Request

Use `type` as `interactive` and set `interactive.type` to `flow`.

Use this endpoint to send a Flow **inside the 24h Customer Service Window**. To send a Flow **outside the 24h window**, wrap it in an approved template with a Flow button and use [Send Template](/api-reference/messages/send-template) instead.

### Field types

* `to`: string (required)
* `type`: string = `interactive` (required)
* `interactive`: object (required)
* `interactive.type`: string = `flow` (required)
* `interactive.header`: object (optional)
* `interactive.header.type`: string (optional, usually `text`)
* `interactive.header.text`: string (optional)
* `interactive.body`: object (required)
* `interactive.body.text`: string (required)
* `interactive.footer`: object (optional)
* `interactive.footer.text`: string (optional)
* `interactive.action`: object (required)
* `interactive.action.name`: string = `flow` (required)
* `interactive.action.parameters`: object (required)
* `interactive.action.parameters.flow_message_version`: string = `3` (required)
* `interactive.action.parameters.flow_token`: string (required, unique per send)
* `interactive.action.parameters.flow_id`: string (required if `flow_name` is not provided)
* `interactive.action.parameters.flow_name`: string (required if `flow_id` is not provided)
* `interactive.action.parameters.flow_cta`: string (required)
* `interactive.action.parameters.flow_action`: string = `navigate` or `data_exchange` (optional, default `navigate`)
* `interactive.action.parameters.flow_action_payload`: object (required when `flow_action` is `navigate`)
* `interactive.action.parameters.flow_action_payload.screen`: string (required when `flow_action` is `navigate`)
* `interactive.action.parameters.flow_action_payload.data`: object (optional)
* `interactive.action.parameters.mode`: string = `published` or `draft` (optional, default `published`)
* `tags`: array of strings (optional)
* `metadata`: object | string (optional)

### Field behavior and limits

* `interactive.body.text` is required, max 1024 characters.
* `interactive.header.text` is optional, max 60 characters.
* `interactive.footer.text` is optional, max 60 characters.
* `interactive.action.parameters.flow_cta` is the button label, max 20 characters and must not contain emojis or markdown.
* `interactive.action.parameters.flow_token` must be unique per send. It is echoed back in the inbound payload when the user submits the Flow, so use it to correlate the response with the original send.
* `interactive.action.parameters.flow_id` is the ID issued by Meta when the Flow is published. `flow_name` is supported as an alternative.
* `interactive.action.parameters.mode` defaults to `published`. Use `draft` only while testing — `draft` mode delivers only to numbers registered as testers in Meta.
* `interactive.action.parameters.flow_action_payload.screen` must match the ID of the first screen to render. `data` is forwarded as the initial state of that screen.
* When `flow_action` is `data_exchange`, omit `flow_action_payload`. The Flow's data endpoint configured in Meta is called to populate the first screen.
* Flow messages render on the WhatsApp native mobile app. WhatsApp Web shows a simplified fallback.

```json theme={null}
{
  "to": "+573001112233",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": { "type": "text", "text": "Agendamiento" },
    "body": { "text": "Por favor completá los datos para reservar tu cita." },
    "footer": { "text": "Tomará menos de 1 minuto" },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "f4c3b1a0-8d2e-4a51-9c77-2a18bd0e6f12",
        "flow_id": "1234567890123456",
        "flow_cta": "Reservar",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "APPOINTMENT_DETAILS",
          "data": {
            "patient_name": "Juan",
            "preferred_specialty": "cardiology"
          }
        }
      }
    }
  },
  "tags": ["appointment"],
  "metadata": { "source": "crm-webhook" }
}
```

## Handling the response

When the user completes and submits the Flow, an inbound event arrives with the structured fields the user filled in, plus the same `flow_token` you sent. Use the token to correlate the response with the original send.

For the conceptual model, screen design, and pricing, see [WhatsApp Flows](/guides/whatsapp/flow-messages). For the authoritative Flow JSON schema and screen elements, see [Meta's Flow documentation](https://developers.facebook.com/docs/whatsapp/flows).