Flow

​

Request

​

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 (optional when flow_action is navigate, must be omitted when flow_action is data_exchange)
• interactive.action.parameters.flow_action_payload.screen: string (optional, default FIRST_ENTRY_SCREEN)
• interactive.action.parameters.flow_action_payload.data: object (optional, must be a non-empty object when provided)
• 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 is optional. If omitted, Meta uses FIRST_ENTRY_SCREEN. When provided, it must match the ID of the first screen to render.
• interactive.action.parameters.flow_action_payload.data is the input data for the first screen. When provided, it must be a non-empty object.
• When flow_action is data_exchange, flow_action_payload must be omitted. Meta calls the Flow’s data endpoint to populate the first screen.
• Flow messages render on the WhatsApp native mobile app. WhatsApp Web shows a simplified fallback.

{
  "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