Receive WhatsApp Flow Responses on Your Webhook

A customer opens your Flow, fills it in, taps Submit — and the webhook that reaches you looks empty. The message is there, but its text is the single word Sent. Nothing was lost. The answers travel on a different event, and that event has to be subscribed to explicitly.

What Meta actually delivers

A submitted Flow does not arrive as a text message. It arrives as an interactive reply of type nfm_reply, with three fields:

Field	What it is
`response_json`	The answers — a JSON string, not an object.
`body`	A short label Meta renders in the chat bubble: `Sent`, or `Enviado` in Portuguese.
`name`	The Flow’s name.

Why the message text says `Sent`

Because that is the only thing in the payload that is message text. The chat bubble, chat_messages.text, content on message.* events and GET /v1/messages all carry the same value, and that value is Meta’s body (falling back to the Flow name when body is blank).

The answers are deliberately not folded into content. It is a public contract: an integrator reading content is promised message text. Putting a JSON blob there would break every consumer that renders or matches on it, and would spill names, phone numbers and document numbers into a plain-text field with no schema — irreversibly, once a customer has started parsing it.The answers get a surface of their own instead, where they are structured, correlatable by flow_token, and pruned on a retention window.

The answers arrive on `flow.response_received`

You have to subscribe to the event. A webhook whose events list contains only messages never receives it — and nothing reports an error, which is exactly what “my webhook arrives empty” looks like from the outside.Flows run on Meta (Cloud API) numbers, whose webhooks are subscribed by Meta’s own field names (messages, flows, …). flow.response_received is a Pilot Status event delivered alongside them, in the canonical { event, data } shape — like the normalized call.* events. Add it to the list.

Dashboard
API

Open Webhooks (/webhooks), edit the webhook attached to the Flow’s number, and tick flow.response_received in the event picker. events is replaced wholesale when you save, so keep the events you already had.

curl -X PATCH "https://pilotstatus.com.br/v1/webhooks/wh_01HZX..." \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["messages", "flow.response_received"] }'

events replaces the whole list on PATCH — there is no merge. Send every event you want, not just the new one.

The payload

{
  "event": "flow.response_received",
  "data": {
    "event": "flow.response_received",
    "flowId": "flw_local_1",
    "metaFlowId": "1122334455",
    "flowToken": "a1b2c3d4e5f6...",
    "messageId": "wamid.HBgNNTU2Nzk5...",
    "whatsappNumberId": "cmm0abc123",
    "from": "+5567999999999",
    "receivedAt": "2026-09-03T14:21:07.000Z",
    "response": {
      "resolucao": "resolvido",
      "nota_atendimento": "9",
      "comentario": "Teste",
      "nome_indicado": "Bruno",
      "telefone_indicado": "6799..."
    },
    "responseRaw": null
  }
}

Field	Presence	Description
`flowId`	nullable	The local Flow id — the same `id` used everywhere in `/v1/flows`. `null` when the submission cannot be tied back to a Flow we know.
`metaFlowId`	nullable	Meta’s own Flow id.
`flowToken`	nullable	The one-time token minted when the Flow was sent, when it can be read.
`messageId`	always	The wamid of the message carrying the submission.
`whatsappNumberId`	always	The Pilot Status id of the number that received it.
`from`	always	Who answered, in E.164.
`receivedAt`	always	ISO 8601.
`response`	nullable	The answers, already parsed. An object.
`responseRaw`	nullable	The raw bytes — only when the parse failed.

response and responseRaw are two halves of one field, and the failing half is the one worth handling. Meta sends the answers as a JSON string; when that string parses, you get response and responseRaw is null. When it does not, you get responseRaw with the bytes exactly as they arrived and response is null.The submission is never dropped for being unparseable — losing what a customer typed is worse than handing you something you have to look at. So read both, and do not assume response is an object without checking.

Chatwoot shows `content: null` — that is Chatwoot

Chatwoot has no reader for nfm_reply. A Flow submission that reaches Chatwoot through its own native WhatsApp Cloud channel lands as a message with content: null — no text, no answers. It is a limitation of Chatwoot’s WhatsApp parser, not of the number or of the Flow, and no setting on our side changes what its parser understands. On that channel Pilot Status is not in the path at all, so there is nothing we can add to the thread: this event is the way to read those answers.

On the API-mirror channel, we do add them. When the conversation is mirrored by Pilot Status, a submission is posted twice: the public bubble is replaced with a short fixed line (📋 Formulário respondido) instead of Meta’s label, and the answers go into a private note on the same conversation — one field: value line per answer, agents only, never shown to the customer.The note is a convenience for humans and is capped per value; the event is the machine-readable copy and is never truncated. See Chatwoot.

Reading answers later

The event is the live channel. The stored copy is at GET /v1/flows/{id}/responses, joined to the contact who answered, and kept for 30 days.

curl "https://pilotstatus.com.br/v1/flows/flw_local_1/responses?page=1&pageSize=30" \
  -H "x-api-key: ps_your_key_here"

The retention window is enforced on read, so a submission past its expiry is never served — pull what you need to keep into your own store rather than treating this endpoint as the archive.

Minimal example

Node + Express. It verifies the signature over the raw body, then reads the answers.

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

const app = express();

// Raw body: the signature is over the bytes we sent. `JSON.stringify(req.body)`
// reorders keys and fails verification on legitimate requests.
app.post("/hooks/whatsapp", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_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 { event, data } = JSON.parse(req.body.toString("utf8"));
  if (event !== "flow.response_received") return res.sendStatus(200);

  const answers = data.response ?? safeParse(data.responseRaw);
  console.log("flow answers from", data.from, answers);

  // Answer fast; do the slow work after.
  res.sendStatus(200);
});

function safeParse(raw) {
  if (!raw) return null;
  try { return JSON.parse(raw); } catch { return { unparsed: raw }; }
}

app.listen(3000);

Still empty? Check these, in order

Is flow.response_received in the webhook's events?

GET /v1/webhooks and read the list back. A webhook with ["messages"] receives inbound messages and nothing else.

Is the webhook on the right number?

Webhooks are scoped per number, and a Flow is answered on the number that sent it.

Is the webhook active, and is the delivery being attempted?

GET /v1/webhooks/{id}/logs shows recent attempts. A paused webhook (active: false) delivers nothing.

Are you reading content instead of data.response?

content is Meta’s label and always will be. The answers are in data.response.

Are you reading the delivery LOG rather than the delivery?

On a number configured to keep no customer content, the answers are still delivered to your endpoint in full — it is the stored copy of the payload that is blanked (from, response and responseRaw nulled). A log entry that looks empty next to a 200 is that redaction, not a failed delivery.

Flows — lifecycle, publishing, cloning
Connect your API to a Flow — the data_exchange half
Webhook events
Flows API

Get Started

Core Concepts

Guides

Integrations

Dashboard

Trust & Data

Plans & Support

Changelog

Receive WhatsApp Flow Responses on Your Webhook

What Meta actually delivers

Why the message text says `Sent`

The answers arrive on `flow.response_received`

The payload

Chatwoot shows `content: null` — that is Chatwoot

Reading answers later

Minimal example

Still empty? Check these, in order

​What Meta actually delivers

​Why the message text says Sent

​The answers arrive on flow.response_received

​The payload

​Chatwoot shows content: null — that is Chatwoot

​Reading answers later

​Minimal example

​Still empty? Check these, in order

​Related

What Meta actually delivers

Why the message text says `Sent`

The answers arrive on `flow.response_received`

The payload

Chatwoot shows `content: null` — that is Chatwoot

Reading answers later

Minimal example

Still empty? Check these, in order

Related