# WhatsApp Flows

> Create, publish and send Flows, receive the responses and use Messajo's data exchange endpoint, which handles Meta's encryption.

A [WhatsApp Flow](https://developers.facebook.com/docs/whatsapp/flows) is a multi-screen form that opens inside WhatsApp. Messajo creates and publishes the Flow in your messaging account, sends it in a message, delivers the response as an event and, when the Flow fetches data from your system, **hosts the endpoint** Meta calls: the RSA/AES encryption stays with Messajo and your server gets plain, signed JSON.

## Before you start

- An active WhatsApp connection. The Flow belongs to its messaging account (WABA).
- A key with `templates` (create, edit, publish) and `read` (read and see the exchanges).
- In your Meta app's webhook, the `flows` field subscribed.

## Create and edit the JSON

```bash
curl https://api.messajo.com/v1/flows \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_...",
    "name": "booking",
    "categories": ["APPOINTMENT_BOOKING"],
    "flow_json": { "version": "7.0", "screens": [ ... ] }
  }'
```

The Flow starts as `DRAFT` (`flw_…`). Categories: `SIGN_UP`, `SIGN_IN`, `APPOINTMENT_BOOKING`, `LEAD_GENERATION`, `CONTACT_US`, `CUSTOMER_SUPPORT`, `SURVEY` and `OTHER`.

- `PUT /v1/flows/{id}/json` replaces the JSON (raw body, up to 10 MiB). Messajo checks the basics (valid JSON, `version` and `screens`) and Meta validates the rest: its errors come back as `422` [`flow_invalid_json`](/en/errors#flow_invalid_json), with `details[].path` as `flow_json:<line>:<column>`.
- Only a `DRAFT` changes. Published → `409` [`flow_not_editable`](/en/errors#flow_not_editable); call `POST /v1/flows/{id}/clone` and edit the copy.
- `POST /v1/flows/{id}/preview` returns `preview_url` and `expires_at` to open the Flow in the browser.
- `POST /v1/flows/{id}/publish` publishes; `…/deprecate` retires; `DELETE` deletes (only `DRAFT`); `…/sync` reloads the status from Meta.

In the panel, **Flows** has the list, the JSON editor with preview and the link to Meta's visual builder.

## Sending the Flow

```json
{
  "connection_id": "conn_...",
  "to": "5511999990001",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "body": { "text": "Pick the best time" },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_id": "flw_...",
        "flow_cta": "Book",
        "flow_action": "navigate",
        "flow_action_payload": { "screen": "START" }
      }
    }
  }
}
```

`flow_id` takes Messajo's `flw_…` or Meta's id. `flow_cta` is up to 20 characters. Without a `flow_token`, Messajo generates one (`mjft_…`) and stores it with the contact, conversation and message, so the endpoint knows whose exchange it is. A Flow in a template (**FLOW** button) works the same way.

## Receiving the responses

When the contact finishes the Flow, `message.received` (`reply` content with `kind: "flow"`) and `flow.response` arrive:

```json
{
  "type": "flow.response",
  "data": {
    "flow": { "id": "flw_...", "external_id": "1234567890", "name": "booking" },
    "flow_token": "mjft_...",
    "response": { "date": "2026-11-20", "time": "09:00" },
    "message": { "id": "msg_..." },
    "contact": { "id": "ctc_..." },
    "conversation": { "id": "cnv_..." }
  }
}
```

Other events: `flow.status_changed` (Meta published, blocked or throttled the Flow), `flow.endpoint_alert` (endpoint health alert: error rate, latency, availability) and `flow.endpoint_error` (the contact's app reported an endpoint error).

## Messajo's data exchange endpoint

A Flow that fetches data (dynamic screens, validation, booking) needs an endpoint. Give the Flow an `endpoint` with the URL of **your** handler:

```json
{ "endpoint": { "url": "https://app.yourcompany.com/flows/booking", "headers": [{ "name": "X-Tenant", "value": "store-1" }] } }
```

Messajo registers `https://api.messajo.com/meta/flows/<flw_id>` with Meta and returns the `handler_secret` **once** (rotate it with `POST /v1/flows/{id}/rotate-handler-secret`). Without a handler, a Flow with an endpoint returns `422` [`flow_handler_required`](/en/errors#flow_handler_required). The handler URL follows the [destination](/en/webhooks/destinations/) rules: `https` and a public address.

On each exchange Meta calls Messajo; Messajo checks Meta's signature, decrypts, answers `ping` and error notifications by itself, and forwards `INIT`, `BACK` and `data_exchange` to your handler:

```http
POST https://app.yourcompany.com/flows/booking
Content-Type: application/json
Messajo-Signature: t=1763000000,v1=5257a869…
Messajo-Flow-Id: flw_...
Messajo-Request-Id: req_...
User-Agent: Messajo-Flows/1

{
  "type": "flow.data_exchange",
  "flow": { "id": "flw_...", "external_id": "1234567890", "name": "booking" },
  "action": "data_exchange",
  "screen": "START",
  "data": { "date": "2026-11-20" },
  "flow_token": "mjft_...",
  "context": { "connection_id": "conn_...", "contact_id": "ctc_...", "message_id": "msg_..." },
  "version": "3.0"
}
```

Reply `200` with the next screen, in Meta's format:

```json
{ "screen": "TIMES", "data": { "times": [{ "id": "09", "title": "09:00" }] } }
```

- `context` is `null` when the Flow was not sent through Messajo (no known `flow_token`).
- A `flow_token` you don't recognize → reply `{ "error": "flow_token_invalid" }`: Messajo returns `427` to Meta and the app shows the Flow has expired.
- Handler time limit: **7 s**; response up to 256 KiB. Error, timeout or a response without `screen` → Meta gets `500` and the contact sees a generic error. Each exchange stays in `GET /v1/flows/{id}/exchanges` for 7 days (without the data), with the result and duration.

### Verifying the handler signature

`Messajo-Signature` is the same as for webhooks, with the `handler_secret` as the key: HMAC-SHA256 of `${t}.${raw body}`, constant-time comparison and a 5-minute tolerance. Details in [Verify the signature](/en/webhooks/verify-signature/).

<Code code={nodeSnippet} lang="ts" title="verify.ts" />

<Code code={pythonSnippet} lang="python" title="verify.py" />

### Codes Meta receives

| HTTP | When | What the contact's app does |
|---|---|---|
| `200` | encrypted response | continues the Flow |
| `421` | Messajo could not decrypt with the current or the previous key | downloads the public key again and retries |
| `427` | the handler replied `flow_token_invalid` | shows the Flow is no longer valid |
| `432` | Meta's signature (`X-Hub-Signature-256`) does not match | error |
| `429` | more than 1,200 exchanges per minute on the Flow | error |
| `500` | the handler failed | generic error |

### Key and rotation

Meta encrypts each exchange with the **messaging account's public key**. Messajo generates an RSA 2048 pair the first time a Flow in the account uses the endpoint, uploads the key to every active number and checks daily that Meta still has the right key (it uploads again if missing). To change it: `POST /v1/connections/{id}/flow-key/rotate` (`admin` key); the previous key keeps decrypting for **24 hours**. Publishing without the key uploaded to at least one number → `409` [`flow_key_not_uploaded`](/en/errors#flow_key_not_uploaded).

Through the [mirror](/en/operate/migrate/), `whatsapp_business_encryption` is blocked (`403 mirror_path_blocked`) when the key is Messajo's, so nobody replaces the key from outside.

## Errors

| Code | When |
|---|---|
| [`flow_not_found`](/en/errors#flow_not_found) | the Flow does not exist or belongs to another organization |
| [`flow_invalid_json`](/en/errors#flow_invalid_json) | JSON rejected (Meta `139001`) |
| [`flow_error`](/en/errors#flow_error) | another Meta `139xxx` error |
