Flow Templates

A Flow template is a regular template with a Flow Trigger button. When the customer taps the button, WhatsApp opens a WhatsApp Flow — a multi-screen form inside the chat — and sends the answers back to your webhook when the customer completes it. You build and publish the Flow itself in Meta’s WhatsApp Manager. In the Gateway, you only reference it by its Flow ID.

Before you start

Your WhatsApp Business account must be eligible for Flows. If it is not, Meta rejects the template.
The Flow must already exist in WhatsApp Manager under the same WhatsApp Business account as your Gateway app. Copy its Flow ID from WhatsApp Manager → Flows.
Publish the Flow before you send it to real customers.

The Gateway asks only for the Flow ID. You do not send the Flow name or the Flow JSON when you create the template — Meta resolves the Flow from its ID.

Create the template in the panel

Follow the normal Create Template steps. In Step 4 — Template Content:

Fill in the body and, if you need them, the header and footer.
Click + Add Button and select Flow Trigger.
Fill in the Flow Trigger fields:

Field	Required	Description
Flow ID	Yes	The unique identifier Meta assigned to your Flow.
Flow Action	Yes	How the Flow starts. Navigate opens a fixed screen. Data Exchange asks your Flow endpoint for the first screen and its data.
Flow Screen	With Navigate	The ID of the screen the Flow opens on, exactly as defined in the Flow JSON (for example `WELCOME_SCREEN`).
Button label	Yes	The text on the button. Maximum 25 characters.

Click Next, review the summary, and click Create.

Make sure your WhatsApp Business account is eligible for Flows before you submit. Otherwise, Meta may reject the template.

Navigate vs. Data Exchange

Flow Action	Use it when	First screen comes from
Navigate	The Flow is static, or you can pass all initial data when you send the message.	The Flow Screen you set on the template. You can pre-fill its data with `flow_action_data` at send time.
Data Exchange	The Flow needs live data from your server (availability, prices, account details).	Your Flow endpoint, which Meta calls when the customer opens the Flow.

Send a Flow template

Send the template with the template message request. Add a button component with sub_type: "flow" and the index of the Flow button.

Field	Type	Required	Description
`type`	string	Yes	`"button"`
`sub_type`	string	Yes	`"flow"`
`index`	string	Yes	Position of the Flow button on the template, starting at `"0"`.
`parameters[].type`	string	Yes	`"action"`
`parameters[].action.flow_token`	string	No	Your own identifier for this Flow session. It comes back in the completion webhook, so you can match the answers to an order, user, or conversation. Defaults to `"unused"`.
`parameters[].action.flow_action_data`	object	No	Navigate only. Initial data passed to the first screen. Keys must match the data model of that screen in the Flow JSON.

curl -X POST https://api.gateway.connexease.com/v1/wa/message \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "905321234567",
    "type": "template",
    "template": {
      "name": "delivery_survey",
      "language": { "code": "tr" },
      "components": [
        {
          "type": "body",
          "parameters": [{ "type": "text", "text": "ORD-20261016" }]
        },
        {
          "type": "button",
          "sub_type": "flow",
          "index": "0",
          "parameters": [
            {
              "type": "action",
              "action": {
                "flow_token": "order-ORD-20261016",
                "flow_action_data": { "order_id": "ORD-20261016" }
              }
            }
          ]
        }
      ]
    }
  }'

import requests

requests.post(
    "https://api.gateway.connexease.com/v1/wa/message",
    headers={"Authorization": "Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "Content-Type": "application/json"},
    json={
        "messaging_product": "whatsapp",
        "to": "905321234567",
        "type": "template",
        "template": {
            "name": "delivery_survey",
            "language": {"code": "tr"},
            "components": [
                {"type": "body", "parameters": [{"type": "text", "text": "ORD-20261016"}]},
                {
                    "type": "button",
                    "sub_type": "flow",
                    "index": "0",
                    "parameters": [{
                        "type": "action",
                        "action": {
                            "flow_token": "order-ORD-20261016",
                            "flow_action_data": {"order_id": "ORD-20261016"}
                        }
                    }]
                }
            ]
        }
    }
)

await fetch('https://api.gateway.connexease.com/v1/wa/message', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    to: '905321234567',
    type: 'template',
    template: {
      name: 'delivery_survey',
      language: { code: 'tr' },
      components: [
        { type: 'body', parameters: [{ type: 'text', text: 'ORD-20261016' }] },
        {
          type: 'button',
          sub_type: 'flow',
          index: '0',
          parameters: [{
            type: 'action',
            action: {
              flow_token: 'order-ORD-20261016',
              flow_action_data: { order_id: 'ORD-20261016' }
            }
          }]
        }
      ]
    }
  }),
});

If the template has no body variables and you don’t need a flow_token, you can still send the button component with an empty action object. Use a unique flow_token per send whenever you need to tie the answers back to a record in your system.

Receive the Flow response

When the customer completes the Flow, the Gateway forwards an incoming message to your webhook. The message has type: "interactive" and interactive.type: "nfm_reply".

{
  "from": "905399876543",
  "id": "wamid.xxx",
  "timestamp": "1792148400",
  "type": "interactive",
  "context": {
    "from": "905321234567",
    "id": "wamid.ORIGINAL_TEMPLATE_MESSAGE"
  },
  "interactive": {
    "type": "nfm_reply",
    "nfm_reply": {
      "name": "flow",
      "body": "Sent",
      "response_json": "{\"flow_token\":\"order-ORD-20261016\",\"rating\":\"5\",\"comment\":\"Fast delivery\"}"
    }
  }
}

Field	Type	Description
`context.id`	string	The `wamid` of the template message that opened the Flow.
`interactive.nfm_reply.response_json`	string	A JSON string with the values the customer submitted, plus the `flow_token` you sent. Parse it before use.
`interactive.nfm_reply.body`	string	The text shown in the chat after submission.

The envelope is the same as every other incoming message — see Incoming Message Events.

Troubleshooting

Symptom	Likely cause
Template is rejected	The WhatsApp Business account is not eligible for Flows, or the Flow ID belongs to a different WhatsApp Business account.
Send returns a parameter error	The `index` does not point to the Flow button, or `flow_action_data` keys don’t match the first screen’s data model.
Flow opens on the wrong screen	Flow Screen on the template doesn’t match a screen ID in the Flow JSON.
No completion webhook	The customer closed the Flow without submitting, or the Flow’s terminal screen doesn’t complete the Flow.

Sandbox

WhatsApp

Templates

Webhooks

Reference

Before you start

Create the template in the panel

Navigate vs. Data Exchange

Send a Flow template

Receive the Flow response

Troubleshooting

​Before you start

​Create the template in the panel

​Navigate vs. Data Exchange

​Send a Flow template

​Receive the Flow response

​Troubleshooting

Before you start

Create the template in the panel

Navigate vs. Data Exchange

Send a Flow template

Receive the Flow response

Troubleshooting