Connect Your API to a WhatsApp Flow (data_exchange)

Yes — a Flow can read from your API while the customer is filling it in. That is what a data_exchange Flow is: the customer picks a date and the next screen shows the slots that are actually free, because your backend decided them. You do not implement any of Meta’s cryptography. Pilot Status is the endpoint Meta calls. We decrypt the request, POST plain JSON to a URL you control, and encrypt your answer on the way back.

A NAVIGATE Flow — one whose screens are all fixed in the Flow JSON — needs none of this. Everything on this page is only for Flows whose screens call your backend. See Flows for the difference.This page is the request-by-request contract. For the same feature in product terms — what to set up, in what order, and what a person sees when it is wrong — read Flows with live data.

The shape of one exchange

The customer fills a screen

Meta sends an encrypted request — AES-GCM, key RSA-OAEP-wrapped under the public key registered for that phone number — to the endpoint registered on the Flow, which is us.

We decrypt and forward

A plain JSON POST to your URL, with an HMAC signature header. No RSA, no AES-GCM, no inverted IV on your side.

You answer with the next screen

200 with { "screen": "...", "data": { ... } }.

We encrypt the reply

Meta renders the screen you named.

What we `POST` to you

{
  "version": "3.0",
  "action": "data_exchange",
  "screen": "PICK_SLOT",
  "data": { "day": "2026-09-10" },
  "flow_token": "a1b2c3...",
  "flow_id": "1122334455",
  "number_id": "cmm0abc123"
}

Field	Description
`version`	Meta’s protocol version, echoed from its request.
`action`	`INIT` when the form opens, `BACK` when the customer steps back, `data_exchange` when they submit a screen.
`screen`	The screen they were on. Can be `null` — Meta does not populate it on `INIT`, because no screen has been shown yet.
`data`	What that screen collected. `{}` when there is nothing.
`flow_token`	The one-time token minted when the Flow was sent. `null` when absent.
`flow_id`	Meta’s Flow id — the same value the endpoint URL was registered with.
`number_id`	The Pilot Status id of the number the Flow is running on.

action is never null, and a request without one is never forwarded. Every call Meta makes carries INIT, BACK, data_exchange or ping. A decrypted payload that carries none of them is dropped before it reaches you, because forwarding it would put our signature on something that is not a Flow exchange — and your endpoint would have no way to tell it apart from one we vouched for on purpose.

A file picked with PhotoPicker or DocumentPicker reaches us in THIS exchange, and never in the nfm_reply. That is why a Flow with no endpoint receives no attachment at all. Pilot Status re-hosts the file and publishes it on the submission as flowMedia / media — the event is emitted as soon as the submission is stored and the re-host runs after it, so status is ordinarily PENDING when the event lands, and flowMedia[].url is a link that already works: fetching it waits for the transfer instead of 404ing. The shape, and what to do with that, are in Receive Flow responses. Meta’s own limits (one picker per screen, 25 MiB, 20 days on its CDN) are in Flows.

The signature

When the Flow has a signing secret, the forward carries x-pilot-status-signature: the hex-encoded HMAC-SHA256 of the raw request body, keyed with that secret. It is the same header and the same scheme as Pilot Status outbound webhooks — if you already verify those, you need no second code path. Compute the HMAC over the bytes as received, before any JSON parsing.

No secret configured means no header. The forward still happens, unsigned, and anyone who can reach your URL can then post a plausible body to it. Set the secret.

What you must return

Plain JSON, 2xx, naming the next screen:

{
  "screen": "CONFIRM",
  "data": { "slots": ["09:00", "11:30", "16:00"] }
}

Rule	Detail
Status	Must be `2xx`. Anything else is treated as a failure.
Body	Must be valid JSON.
`screen`	Required. The name of the next screen, as it appears in your Flow JSON.
`data`	Optional. Omitted or `{}` is fine.
`version`	Do not send it. We echo Meta’s own version; yours is ignored.

To finish the Flow, return the reserved SUCCESS screen. ⚠️ This shape is Meta’s own convention, not ours: we forward screen and data to Meta untouched, so extension_message_response never appears anywhere in Pilot Status — do not look for it in our API reference.

{
  "screen": "SUCCESS",
  "data": { "extension_message_response": { "params": { "flow_token": "a1b2c3..." } } }
}

What comes back on the submission is only what you named in params, and the answers are not in it. Meta unwraps that object into the nfm_reply, so in a data_exchange Flow data.response publishes exactly the shape above and nothing more — {"flow_token": "a1b2c3..."} — while the same submission had already handed {"observacao": "Aobaaa", "foto": [ … ]} to your endpoint. The answers went to you, screen by screen. They never travelled back through Meta.Read them in data.submitted, which carries the data_exchange requests we forwarded, each with its screen and its timestamp — see Receive Flow responses. A plain Flow with no endpoint is the other case: nothing collected the answers on the way, so there response is where all of them are.

A 200 that names no screen is refused on purpose. It is the one failure mode that looks like success from your side and is invisible from the customer’s: Meta renders a payload without a screen as nothing at all, so the person sits in front of a form that never advances and never errs.We treat it exactly like a failed call instead — the customer gets a retryable error on the screen they are already looking at, and the exchange is recorded as a failure you can find.

Answer fast

Meta holds the request open while a person watches a spinner, and there is no retry — a slow answer is a failed screen, not a delayed one. Our forward is abandoned after a few seconds (8 s by default), which is deliberately tighter than the budget for ordinary webhooks: those are notifications nobody is waiting for. Do the slow work after you reply.

What we handle without calling you

Meta’s ping never reaches your endpoint. It is Meta’s health check, and we answer it ourselves. A health check that depends on a third party being awake reports the wrong thing to the wrong party — your server being down for a deploy would make Meta mark the endpoint unhealthy for every Flow on that number.So: do not implement ping, and do not expect to see it in your logs.

When your API fails

Whatever the cause — down, timed out, non-2xx, unparseable body, no screen — the customer never sees your infrastructure and never sees a broken screen.

What happened	What the customer sees
Your API failed, and we know which screen they were on	The same screen, with a generic retryable error over it. Nothing they typed is lost.
Your API failed on `INIT` or `BACK`, where Meta sent no screen name	Meta’s own failure screen. There is no screen to echo, and the only always-valid name is `SUCCESS` — which would close the form and tell them they submitted something you never processed.

A failure on your side is never reported to Meta as a key problem. The 421 response that tells Meta “re-download my public key” is returned for exactly one thing: we could not decrypt. Meta caches that fetch, so using it for an outage of yours would make the lie outlive the outage.

Seeing what happened

The Flow’s screen in the dashboard lists the recent exchanges: the action, the screen, the outcome, your HTTP status and how long you took. Bodies are recorded only on a failure — a successful exchange keeps timing and shape and neither body, not the one we forwarded nor the one you answered — and the whole record expires after 24 hours.

“Not in this trace” is not “not kept”. What the customer typed into a data_exchange screen is stored and published: it is data.submitted on the submission, each entry carrying the screen it was filled on and the moment it happened, on the flow.response_received event and at GET /v1/flows/{id}/responses, for 31 days.A day longer than the response itself, deliberately. The exchange is captured while the person is still filling, minutes before the submission that creates the response row — on an identical window the exchanges would expire first, and a response’s last minutes on the endpoint would publish an empty list. The full shape is in Receive Flow responses.

submitted is legitimately shorter than this list, and that is not a gap. Only data_exchange exchanges are captured. INIT carries the state we seeded — the params the Flow was sent with, handed straight back — and BACK is navigation; neither is an answer, so neither is stored. Count the rows here and the entries there and the two will not match.It is append-only and never de-duplicated: someone who walks back a screen and re-submits it produces a second, genuine entry, and the timestamp is what separates the two runs under one flow_token. And it is the request Meta sends us — never what your endpoint replied, which is why extension_message_response still appears nowhere in Pilot Status.

Setting it up, in order

Three things have to be true before Meta calls your API, and they become true in this order. Skip one and you get a Flow that looks configured, raises no error anywhere, and is never called.

1. The key — on the NUMBER

Generate one with us, or import the one you already use. Meta stores exactly one public key per phone number, so this is a property of the number and never of a Flow.

2. The forwarding URL — on the FLOW

Where we POST the decrypted exchange. One number serves several forms, and each form is usually a different service on your side, so this is per Flow.

3. endpoint_uri — at Meta, on the Flow

Meta only calls an endpoint it has registered, and saving the URL in step 2 registers nothing at Meta. Registration is a request of its own — POST /v1/flows/{flowId}/endpoint — because performing it as a side effect of a rename would hijack the Flow of someone already running their own endpoint. Until it is done, Meta refuses to publish the Flow at all.

	Level	Where it is set
Key — what decrypts Meta’s request	Per number	`POST /v1/numbers/{numberId}/flow-endpoint-key`, or the Flows screen in the dashboard
Endpoint URL — where we forward	Per Flow	`PUT /v1/flows/{flowId}/endpoint`, or the Flows screen in the dashboard
`endpoint_uri` — where Meta calls	Per Flow, stored at Meta	`POST /v1/flows/{flowId}/endpoint`, or Register at Meta on the Flows screen in the dashboard

The key is per NUMBER, however it is presented next to a Flow. Changing it changes decryption for every data_exchange Flow on that phone number, not just the one you were looking at.

A destination saved on a number with no key is a Flow that will never be called. Meta has nothing to encrypt with, so it never reaches us, so the destination is never used — and nothing on either side reports it. That is what numberHasKey and the warnings list exist for; FLOW_ENDPOINT_NUMBER_HAS_NO_KEY is the one that matters.

Every one of these endpoints requires flows:manage — including the reads. endpointUri and metaEndpointUri embed the number’s endpoint token, and that token is the only thing the public endpoint authenticates on, while the matching public key is published by Meta. Whoever holds both can forge a request we will decrypt and forward to your webhook under our signature. That is also why the value is deliberately absent from GET /v1/flows: a read-only credential is still a credential.

Step 1 — the key: generate, or import your own

Generate (we mint the pair)
Import (you already have one)

We create an RSA-2048 pair, store the private half encrypted, and register the public half with Meta for that number.

curl -X POST "https://pilotstatus.com.br/v1/numbers/{numberId}/flow-endpoint-key" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Generating REPLACES the key Meta holds for that phone number. Meta stores one public key per number — registering ours overwrites whatever was there.If you already run your own data_exchange endpoint on that number, it stops decrypting the moment we register. That is why replacing a live key requires {"confirm": true} and is otherwise refused with FLOW_ENDPOINT_KEY_REQUIRES_CONFIRMATION.First-time setup does not ask, and neither does retrying a pair Meta never accepted (uploadedAt: null) — a retry re-uploads the same stored public half rather than minting another, so there is nothing to destroy in either case.

Hand us the private key you already use. Nothing changes at Meta — the public key registered there stays exactly as it is, which is what makes importing the safe option when a setup of yours is already working. The only Graph call on this path is a read.

curl -X POST "https://pilotstatus.com.br/v1/numbers/{numberId}/flow-endpoint-key" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADAN...\n-----END PRIVATE KEY-----\n"
  }'

We derive the public half from the key you sent and compare it with the one Meta reports. The three outcomes are not symmetric:

What Meta reports	What happens
It holds exactly this key	Stored, `uploadedAt` stamped with the moment we proved it, `metaStatus: "VALID"`.
It holds a different key	Refused, and nothing is written — `400 FLOW_ENDPOINT_KEY_IMPORT_MISMATCH`. Storing it would leave a number reporting `configured: true` that decrypts nothing, and the symptom would land days later on your customer’s phone as a form that never advances.
It could not be asked, or holds nothing	Stored anyway, with `uploadedAt: null` and `metaStatus` `UNKNOWN` / `NOT_SET`. An import that vanishes because a Graph call failed is worse than one you can see and re-check.

uploadedAt: null is the “not confirmed” signal, and a 200 alone does not say it. Read the field. The same null on a generated key means “we hold a pair Meta has never accepted”, and both are repaired the same way: POST again to upload the stored public half.

A passphrase is used ONCE and is NOT stored. We open the PEM with it, store the key normalised and encrypted at rest, and after that the passphrase has no reader — there is nothing left for it to open. Storing the armoured bytes instead would fail to open on every request Meta makes, surfacing as a 421 that blames a stale Meta key.Keep your own copy. We cannot give it back, and we never ask for it again.

-d '{ "privateKey": "...", "passphrase": "the passphrase that opens it" }'

Send passphrase only when the key actually has one — an empty string is not “no passphrase” to a PEM reader, and offering one for an unprotected key fails the parse. A passphrase with no privateKey is refused (FLOW_ENDPOINT_KEY_PASSPHRASE_ORPHAN) rather than ignored: without the key, that same request generates a fresh pair and replaces your registration at Meta.

Read the state back at any time — what we hold, when Meta last confirmed it, and whether Meta’s copy still agrees with ours:

curl "https://pilotstatus.com.br/v1/numbers/{numberId}/flow-endpoint-key" \
  -H "x-api-key: ps_your_key_here"

{
  "configured": true,
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...",
  "uploadedAt": "2026-09-02T10:00:00.000Z",
  "endpointUrl": "https://pilotstatus.com.br/api/flows/endpoint/AbC123...",
  "metaStatus": "VALID"
}

UNKNOWN is not NOT_SET. A Graph call that failed says nothing about what Meta holds. Reading it as “no key” leads to rotating — and rotating replaces a key that was probably fine.

endpointUrl stops before the Flow id: the token segment identifies the number, and the segment after it identifies the Flow. The full address Meta must call is {endpointUrl}/{metaFlowId}, which is what endpointUri on the endpoint resource already spells out for you.

Step 2 — the forwarding URL, on the Flow

curl -X PUT "https://pilotstatus.com.br/v1/flows/{flowId}/endpoint" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.your-company.com/flows/booking" }'

{
  "flowId": "flw_local_1",
  "url": "https://api.your-company.com/flows/booking",
  "hasSecret": true,
  "endpointUri": "https://pilotstatus.com.br/api/flows/endpoint/AbC123.../1122334455",
  "metaEndpointUri": null,
  "drift": false,
  "numberHasKey": true,
  "numberKeyUploadedAt": "2026-09-02T10:00:00.000Z",
  "warnings": ["FLOW_ENDPOINT_META_URI_UNKNOWN"],
  "secret": "9f2c…"
}

secret comes back on exactly one response in the life of a secret: the request that minted it. It is stored encrypted and there is no read path back. Copy it now — secret: null on a later save means “one already existed and was kept”, not “there is none”. hasSecret answers that question.Lost it? {"url": "...", "rotateSecret": true} mints a fresh one, which is also the only exit from a secret that leaked.

The URL must be https:// — refused otherwise, with no flag to allow http://. The body we forward is your end user’s form answers, decrypted by us one hop earlier; over http:// that is personal data in the clear, put there by the only participant that had already removed the encryption.{"url": null} clears the destination and keeps the secret, so re-pointing the Flow later does not force you to redeploy a verifier for a value that never leaked.

PUT and PATCH are the same operation here — the resource has one settable field, so there is nothing for “replace” and “merge” to disagree about. GET the same path for the state without writing.The number is not a parameter: it comes from the API key (a number-scoped key names its own; an account-wide key narrows with x-whatsapp-number-id). Naming it in the body is refused with FLOW_NUMBER_FROM_KEY, and a key bound to a number outside the Flow’s WABA gets 422 FLOW_NUMBER_WABA_MISMATCH rather than an answer about a number that could never send this Flow.

Step 3 — register us at Meta

Meta only calls an endpoint it has registered on the Flow. Step 2 registered nothing — this is the request that does:

curl -X POST "https://pilotstatus.com.br/v1/flows/{flowId}/endpoint" \
  -H "x-api-key: ps_your_key_here"

It writes endpointUri — our proxy URL for this Flow — into the Flow’s endpoint_uri at Meta, and answers with the same state the GET returns:

{
  "flowId": "flw_local_1",
  "url": "https://api.your-company.com/flows/booking",
  "hasSecret": true,
  "endpointUri": "https://pilotstatus.com.br/api/flows/endpoint/AbC123.../1122334455",
  "metaEndpointUri": "https://pilotstatus.com.br/api/flows/endpoint/AbC123.../1122334455",
  "drift": false,
  "numberHasKey": true,
  "numberKeyUploadedAt": "2026-09-02T10:00:00.000Z",
  "warnings": []
}

The body is optional, and confirmOverwrite (boolean) is the only field it accepts — the number comes from the key, as everywhere in /v1. There is no secret on this response: POST never mints one.

The dashboard performs the same act. On the Flows screen, under Point Meta here, the Register at Meta button calls this route; a 409 opens a confirmation showing the address you are about to displace, and confirmOverwrite is what its Take it over anyway button sends.

Without this call a data_exchange Flow cannot be published at all. Meta refuses publish with “Publishing without specifying ‘endpoint_uri’ is forbidden”, and nothing else in Pilot Status writes that field.

Why this is a second request and not a flag on the save. PUT is you describing your webhook; POST is us telling Meta to route the Flow through us. Fused into one act, a tenant who runs their own Flow endpoint would lose every exchange the next time they corrected a typo in a URL — the rename would silently re-point the Flow. They are separate so that re-pointing is something you do on purpose.

It is idempotent. A Flow whose endpoint_uri is already ours answers 200 and writes nothing at Meta. The check reads Meta live, not the hourly-synced metaEndpointUri column — that column is silent about a URI registered in the last hour, which is exactly the window in which two people wire the same Flow.

409 FLOW_ENDPOINT_URI_WOULD_OVERWRITE — Meta already points this Flow somewhere else. The response names it, and only it:

{
  "error": "…",
  "errorEN": "Meta already points this Flow at another endpoint. …",
  "code": "FLOW_ENDPOINT_URI_WOULD_OVERWRITE",
  "currentEndpointUri": "https://someone-else.example/flows/1122334455"
}

Re-sending the same request with {"confirmOverwrite": true} takes it over — and taking it over removes every exchange of this Flow from whoever is answering it today. Meta’s write is a plain overwrite: no merge, no undo, and nothing tells the displaced endpoint it stopped being called. Find out what is on the other end of currentEndpointUri first.Ours is deliberately not echoed back: our URL embeds the number’s endpoint token, and that token is the credential of the proxy. currentEndpointUri is theirs, which is what you need to recognise them.

422 FLOW_ENDPOINT_NUMBER_HAS_NO_KEY — the number holds no Flow endpoint key, so there is no URL to register in the first place. Generate it (step 1) and register again.

Read the endpoint back at any time:

curl "https://pilotstatus.com.br/v1/flows/{flowId}/endpoint" \
  -H "x-api-key: ps_your_key_here"

Field	Read it as
`endpointUri`	Where Meta should call — ours, for this Flow.
`metaEndpointUri`	Where Meta is calling, as the hourly sync last read it.
`drift`	`true` only when both are known and differ: Meta is calling someone else and every exchange bypasses us silently.
`warnings`	Every reason this Flow will not work, as stable codes.

Warning	Meaning
`FLOW_ENDPOINT_NO_DESTINATION`	Nothing to forward to. Normal for a `NAVIGATE`-only Flow.
`FLOW_ENDPOINT_NUMBER_HAS_NO_KEY`	The one that silences a Flow. No keypair on the number. Meta has nothing to encrypt with, so we are unreachable by construction.
`FLOW_ENDPOINT_KEY_NOT_AT_META`	A pair is stored here and Meta never accepted it (`uploadedAt: null`). The endpoint answers `421` to everything until the upload is retried.
`FLOW_ENDPOINT_META_URI_UNKNOWN`	Meta has no `endpoint_uri` on this Flow — or the hourly sync has not written this row yet. The column cannot tell the two apart, and inventing the distinction would be worse than naming the ambiguity.
`FLOW_ENDPOINT_META_DRIFT`	Meta has an `endpoint_uri` and it is not ours.

Treat the list as open, not closed: keep any code you do not recognise on screen. A warning you cannot spell is still a warning, and dropping it is how a screen reports “everything is fine” over a server that just said otherwise.

Error codes

Every failure of these endpoints answers the same envelope — one shape, one spelling:

{ "error": "<Portuguese>", "errorEN": "<English>", "code": "<CODE>" }

FLOW_ENDPOINT_URI_WOULD_OVERWRITE is the one failure here that adds a fourth key, currentEndpointUri. The key (/v1/numbers/{numberId}/flow-endpoint-key):

Code	Status	Meaning
`FLOW_ENDPOINT_KEY_REQUIRES_CONFIRMATION`	400	Generating over a key that is live at Meta. Send `{"confirm": true}`.
`FLOW_ENDPOINT_KEY_IMPORT_REQUIRES_CONFIRMATION`	400	Importing over a key that is live. Nothing is registered at Meta by an import, but the private half stored here is replaced — and if Meta cannot confirm the new one, the number is left holding a key that may decrypt nothing.
`FLOW_ENDPOINT_KEY_IMPORT_MISMATCH`	400	The key you sent is not the one Meta has registered. Nothing was written.
`FLOW_ENDPOINT_KEY_PASSPHRASE_REQUIRED`	400	The PEM is passphrase-protected and no `passphrase` came with it.
`FLOW_ENDPOINT_KEY_PASSPHRASE_WRONG`	400	The passphrase does not open the key. The key itself was not rejected — it simply was not opened.
`FLOW_ENDPOINT_KEY_PASSPHRASE_ORPHAN`	400	`passphrase` with no `privateKey`. Refused rather than ignored: without the key, this request generates a pair and replaces your registration at Meta.
`FLOW_ENDPOINT_KEY_PEM_INVALID`	400	`privateKey` is not a readable PEM, is not RSA, or is under 2048 bits. Send the whole `.pem`, `-----BEGIN …-----` lines included.
`FLOW_ENDPOINT_KEY_IMPORT_INVALID`	400	`privateKey` or `passphrase` is present but not a string.
`FLOW_ENDPOINT_KEY_UNAVAILABLE`	500	Ours. The private half cannot be stored encrypted, and we refuse to generate rather than store it in the clear.
`FLOW_NUMBER_NOT_FOUND`	404	The number in the path is not the one this key is bound to. Never `403`, and the same body whether the id is another tenant’s or another of yours.

The forwarding URL (/v1/flows/{flowId}/endpoint):

Code	Status	Meaning
`FLOW_ENDPOINT_URL_REQUIRED`	400	`url` absent, or present and unusable. It may be `null` explicitly — never by omission, because a forgotten field would otherwise wipe a working configuration.
`FLOW_ENDPOINT_URL_NOT_HTTPS`	400	The destination is not `https://`. The refused URL is not echoed back — it may carry a token in its query string.
`FLOW_ENDPOINT_ROTATE_INVALID`	400	`rotateSecret` is not a boolean. `"true"` is not coerced: reading it as `false` would answer `200` to someone rotating a leaked secret while the old one stayed live.
`FLOW_ENDPOINT_SECRET_UNAVAILABLE`	500	Ours. The signing secret cannot be stored encrypted, and forwarding unsigned is not an option we take.
`FLOW_NUMBER_WABA_MISMATCH`	422	Your key’s number is not in the WABA that owns this Flow and can never send it.
`FLOW_NOT_FOUND`	404	No Flow with that id for this credential.
`FLOW_ENDPOINT_CONFIRM_INVALID`	400	`POST` only. `confirmOverwrite` is not a boolean. `"false"` is a truthy string and is refused rather than read as consent.
`FLOW_ENDPOINT_URI_WOULD_OVERWRITE`	409	`POST` only. Meta already points this Flow at another endpoint, named in `currentEndpointUri`. `409` and not `400`: nothing about the request is malformed — it is the state at Meta that blocks it.
`FLOW_ENDPOINT_NUMBER_HAS_NO_KEY`	422	`POST` only. The number holds no endpoint key, so there is no URL to register. Generate the key first.

FLOW_ENDPOINT_NUMBER_HAS_NO_KEY is the one spelling that appears twice — as a warnings entry on a read or a save, and as a 422 on the registration. That is the same fact in two roles: saving a destination on a key-less number is allowed to succeed with a warning, and registering at Meta cannot succeed at all.

Shared by both: FLOW_BODY_INVALID (400, malformed body — a truncated one is never treated as empty), FLOW_UNKNOWN_FIELDS (400), FLOW_NUMBER_FROM_KEY (400, the body named the number), FLOW_REQUIRES_META_NUMBER (422), INTERNAL_ERROR (500).

Never assume the set is closed — branch on the codes you handle and fall through to code for the rest.

Minimal example

Node + Express. One screen that answers with the slots for a chosen day.

const express = require("express");
const crypto = require("node:crypto");

const app = express();

app.post("/flows/booking", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the signature over the RAW body.
  const expected = crypto
    .createHmac("sha256", process.env.FLOW_ENDPOINT_SECRET)
    .update(req.body)
    .digest("hex");
  const got = req.get("x-pilot-status-signature") ?? "";
  if (expected.length !== got.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
    return res.sendStatus(401);
  }

  const { action, screen, data } = JSON.parse(req.body.toString("utf8"));

  // 2. `screen` is null on INIT — there is no screen yet.
  if (action === "INIT") {
    return res.json({ screen: "PICK_DAY", data: { days: nextSevenDays() } });
  }

  if (screen === "PICK_DAY") {
    return res.json({ screen: "PICK_SLOT", data: { slots: slotsFor(data.day) } });
  }

  if (screen === "PICK_SLOT") {
    // Reply first; book after. Meta is holding this request open.
    res.json({ screen: "SUCCESS", data: {} });
    queueBooking(data);
    return;
  }

  // Never return 200 without a `screen` — we refuse it, and rightly.
  return res.status(400).json({ error: "unexpected screen" });
});

app.listen(3000);

Never send version back. It is Meta’s protocol version, echoed from its request — a wrong one fails the whole exchange rather than one field.

Flows — lifecycle, publishing, cloning
Flows with live data — the same setup without the HTTP contract
Receive Flow responses — the submitted answers, on a webhook
Flows API

Get Started

Core Concepts

Guides

Integrations

Dashboard

Trust & Data

Plans & Support

Changelog

Connect Your API to a WhatsApp Flow (data_exchange)

The shape of one exchange

What we `POST` to you

The signature

What you must return

Answer fast

What we handle without calling you

When your API fails

Seeing what happened

Setting it up, in order

Step 1 — the key: generate, or import your own

Step 2 — the forwarding URL, on the Flow

Step 3 — register us at Meta

Error codes

Minimal example

​The shape of one exchange

​What we POST to you

​The signature

​What you must return

​Answer fast

​What we handle without calling you

​When your API fails

​Seeing what happened

​Setting it up, in order

​Step 1 — the key: generate, or import your own

​Step 2 — the forwarding URL, on the Flow

​Step 3 — register us at Meta

​Error codes

​Minimal example

​Related

The shape of one exchange

What we `POST` to you

The signature

What you must return

Answer fast

What we handle without calling you

When your API fails

Seeing what happened

Setting it up, in order

Step 1 — the key: generate, or import your own

Step 2 — the forwarding URL, on the Flow

Step 3 — register us at Meta

Error codes

Minimal example

Related