WhatsApp Flows

A WhatsApp Flow is a structured, multi-screen experience that runs inside WhatsApp. The customer taps a button and steps through screens with inputs like text fields, dropdowns, date pickers, and checkboxes, then submits, all without leaving the chat.

Sign-up & onboarding

Lead capture

Surveys & feedback

Bookings & reservations

You design and publish a flow in WhatsApp Manager, then reference it by its flowId. This page covers how to send one through the API.

Sending a flow

A flow is delivered as a message whose single call-to-action button opens the flow. Send it with message.flowMessage:

curl -X POST "https://api.connectly.ai/v1/businesses/<business_id>/send/messages" \
  -H "X-API-Key: <YOUR_KEY>" -H "Content-Type: application/json" \
  -d '{
    "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
    "message": {
      "text": "Complete this quick form to get started",
      "flowMessage": {
        "flowId": "1234567890123456",
        "flowToken": "ref-000123",
        "flowCta": "Get started",
        "flowAction": "data_exchange",
        "flowMessageVersion": "3"
      }
    }
  }'

Field	Description
`flowId` / `flowName`	Identifier or name of your flow. Provide exactly one.
`flowToken`	Your own reference string. WhatsApp returns it unchanged in the flow response webhook, so you can match the response to this send. See flow_token.
`flowCta`	Text on the button that opens the flow.
`flowAction`	`navigate` or `data_exchange`. See navigate vs data_exchange.
`flowActionPayload`	Screen and data to start with. Required or forbidden depending on `flowAction`, see below.
`flowMessageVersion`	WhatsApp Flow message version. Currently `"3"`.

WhatsApp only allows a pre-approved template as the first message to a customer you have not been messaging. To reach someone new, put the flow on a template as a flow button, see Opening a conversation with a template.

navigate vs data_exchange

A flow opens in one of two modes. Choose based on how the first screen is built.

	`navigate`	`data_exchange`
Who builds the first screen	You. A static screen already defined in the flow.	Your endpoint, at open time.
`flowActionPayload.screen`	Required. Must be the flow’s entry screen id.	Must be omitted. The endpoint decides the first screen.
`flowActionPayload.data`	Optional. Passed to that screen.	Optional starting data for the endpoint.
Endpoint needed to open	No. Renders on the device.	Yes. WhatsApp calls your endpoint.
Use it for	Static flows, or when you already know the entry screen.	Dynamic flows whose content is fetched live.

These two mistakes return a 400 from the API, instead of a 200 that fails silently at WhatsApp:

data_exchange with a flowActionPayload.screen. The endpoint owns the first screen, so no screen may be specified.
navigate without a flowActionPayload.screen, or omitting flowAction (it defaults to navigate). Navigate always needs the entry screen.

A navigate example, opening at a specific screen:

"flowMessage": {
  "flowId": "1234567890123456",
  "flowToken": "ref-000123",
  "flowCta": "Get started",
  "flowAction": "navigate",
  "flowMessageVersion": "3",
  "flowActionPayload": { "screen": "SIGN_UP" }
}

flowActionPayload.data passes starting values to that screen — useful for pre-filling context the flow should carry, like a phone number or your own session reference:

"flowActionPayload": {
  "screen": "SIGN_UP",
  "data": { "phone": "+16044441111", "session_ref": "1001" }
}

Every property in flowActionPayload.data must be declared in the entry screen’s data schema in the Flow JSON. To correlate the flow response back to a specific send, prefer a unique flowToken per send — it is echoed unchanged in the response webhook.

The screen value must exactly match the flow’s entry screen id. WhatsApp rejects any other value.

Endpoints (data_exchange)

A data_exchange flow calls an endpoint you host to build each screen. Your endpoint implements the WhatsApp Flows data-exchange contract: WhatsApp calls it (encrypted) when the flow opens and on each screen submit, and it returns the next screen and its data. See WhatsApp Flow endpoints for the full contract: request lifecycle, encryption, dynamic screen data, a complete example implementation, and troubleshooting.

Opening a data_exchange flow triggers a call to your endpoint. If it is unreachable or errors, WhatsApp shows “Something went wrong” when the customer opens the flow. The send itself still succeeded; only the open failed.

flow_token

flowToken is any string you generate to identify a send, for example an order or record id. It is not a credential and does not need to be secret. WhatsApp stores it and returns it unchanged in the flow response webhook when the customer completes the flow, so you can tie the response back to the right customer and context.

Opening a conversation with a template

WhatsApp requires the first message to a customer to be a pre-approved template. To start a flow with someone you have not been messaging, attach the flow to a template as a flow button in WhatsApp Manager, where it is bound to your flowId, mode, and entry screen. Then send the template:

curl -X POST "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages" \
  -H "X-API-Key: <YOUR_KEY>" -H "Content-Type: application/json" \
  -d '{
    "number": "+16044441111",
    "templateName": "your_flow_template",
    "language": "en",
    "parameters": [
      { "name": "button_1_custom_wa_flow_action_data", "value": "{\"first_name\":\"Sam\"}" }
    ]
  }'

button_N_custom_wa_flow_action_data (where N is the flow button’s position, 1-based) passes starting data for the first screen as a JSON string. It is optional. See Send template messages for the full parameter reference.

Get Started

Campaigns

Messaging

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Resources

Sign-up & onboarding

Lead capture

Surveys & feedback

Bookings & reservations

Sending a flow

navigate vs data_exchange

Endpoints (data_exchange)

flow_token

Opening a conversation with a template

Sign-up & onboarding

Lead capture

Surveys & feedback

Bookings & reservations

​Sending a flow

​navigate vs data_exchange

​Endpoints (data_exchange)

​flow_token

​Opening a conversation with a template

Sending a flow

navigate vs data_exchange

Endpoints (data_exchange)

flow_token

Opening a conversation with a template