> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp Flows
> What WhatsApp Flows are, and how to send one through the API
A [WhatsApp Flow](https://developers.facebook.com/docs/whatsapp/flows) 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.
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`:
```bash theme={null}
curl -X POST "https://api.connectly.ai/v1/businesses//send/messages" \
-H "X-API-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](#flow_token). |
| `flowCta` | Text on the button that opens the flow. |
| `flowAction` | `navigate` or `data_exchange`. See [navigate vs data\_exchange](#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](#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:
```json theme={null}
"flowMessage": {
"flowId": "1234567890123456",
"flowToken": "ref-000123",
"flowCta": "Get started",
"flowAction": "navigate",
"flowMessageVersion": "3",
"flowActionPayload": { "screen": "SIGN_UP" }
}
```
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.
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](/message-api/webhook-api) 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:
```bash theme={null}
curl -X POST "https://api.connectly.ai/v1/businesses//send/whatsapp_templated_messages" \
-H "X-API-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](/messaging/template-messages) for the full parameter reference.