Interactive Flow Token
An Interactive Flow Token — passed as `flow_token` in the WhatsApp Business API — is a string you generate and attach to a WhatsApp Flow when you send it, so that when the user completes the Flow and submits their answers, you can match that submission back to the exact person, conversation, and pending action in your backend. Think of it as a claim ticket: you hand it out when the Flow starts, the user hands it back when they finish, and it tells your system precisely whose form this is. Because a Flow (an in-chat multi-screen experience for bookings, lead capture, KYC, order forms, and more) collects data outside the normal message stream, the flow_token is the thread that stitches the response back into your CRM, order record, or ticket without guessing.
In one line
The Interactive Flow Token (flow_token) is a string you set when sending a WhatsApp Flow and receive back on submission — it links a Flow response to the correct user, conversation, and backend record so nothing gets misrouted.What an Interactive Flow Token actually is
When you send a WhatsApp Flow to a customer, the interactive message payload includes a `flow_token` field alongside the Flow ID and action. You choose that value. It can be a UUID, a signed reference, or an opaque ID that maps to a row in your database — for example a booking draft, a lead record, or a pending order. WhatsApp treats it as an opaque pass-through: Meta does not interpret it, store business meaning in it, or validate its contents. It simply carries your token out to the user's device with the Flow and returns it to you intact when the Flow reaches its terminal screen or exchanges data with your endpoint. That round trip is the entire point — the token is the only reliable handle that ties an anonymous-looking Flow response back to the specific context you had in mind when you sent it.
- You generate the value at send time — Meta never assigns it
- It travels inside the interactive Flow message, not the visible text
- It comes back in the completion payload (and in data-exchange requests for dynamic Flows)
- It is opaque to WhatsApp: no character it contains changes Flow behaviour
Why it matters for correlation and routing
WhatsApp Flows deliberately move data collection off the linear chat timeline. A user might open a Flow, fill three screens over several minutes, and submit — and by then several other messages may have arrived on the same number. Without a flow_token you would be left matching submissions by phone number and timestamp, which breaks the moment a customer has two Flows open, retries a form, or shares a device. The token removes that ambiguity: your webhook handler reads the flow_token, looks it up, and knows this is the KYC form for lead #48213, not a generic form from an unknown sender. That is what lets you auto-advance a workflow, write answers to the right CRM record, trigger the correct follow-up utility template, and keep an audit trail — all without a human deciding which submission belongs to whom.
- Disambiguates concurrent or repeated Flow submissions from one number
- Lets your backend resume the exact workflow the user was in
- Enables clean idempotency — reject a token you have already processed
- Supports auditing: every submission maps to a known intent
How it flows through a real WhatsApp Flow
The lifecycle is short and predictable. First, your system decides to send a Flow — say, an appointment booking — and creates a pending record; you mint a flow_token that points at that record and place it in the Flow message you send through the WhatsApp Business API. Second, the customer interacts with the Flow inside WhatsApp. If the Flow is dynamic (endpoint-driven), Meta calls your data-exchange endpoint on each screen transition and includes the flow_token so you can serve the right screen data. Third, on completion the user's client returns a payload to WhatsApp, which delivers it to your webhook — the flow_token is present so you can finalise. Your handler validates the token, checks it has not already been consumed, writes the collected fields, and closes the loop, often by sending a confirmation utility template. Every delivered template message in that chain is billed by Meta per delivered message by category (utility, marketing, or authentication); a Flow submission inside the free 24-hour service window does not itself add a per-conversation charge, because Meta bills per delivered message, not per conversation.
- Send: mint token → attach to Flow → dispatch via the API
- Interact: dynamic Flows echo the token to your endpoint per screen
- Complete: submission returns to your webhook carrying the token
- Reconcile: validate, de-duplicate, persist, then confirm
Common mistakes to avoid
The failure modes are almost always about treating the token as trusted or reusable when it is neither. Because it is opaque and round-trips through the user's device, you must not assume it is confidential or tamper-proof; never encode raw secrets, and prefer a random ID or a signed reference you can verify server-side. Reusing one token across many sends destroys correlation — every submission then points at the same record. Skipping idempotency invites double-processing when a client retries. And forgetting that the token can arrive later than you expect (users abandon and return) means your record must still exist when the submission lands.
- Do not put secrets, PII, or auth material directly in the token — use a reference
- Do not reuse a token across multiple Flow sends — mint a fresh one each time
- Do handle it as untrusted input: validate or verify a signature before acting
- Do enforce idempotency so a resubmitted token is not processed twice
- Do keep the referenced record alive long enough for late submissions
- Do map an unknown or expired token to a graceful fallback, not a crash
Frequently asked questions
What is a flow_token in the WhatsApp Business API?+
Who generates the Interactive Flow Token — Meta or the business?+
Is the flow_token secure or confidential?+
Can I reuse the same flow_token for multiple Flows?+
Does sending a WhatsApp Flow cost extra?+
What happens if a flow_token is missing or unknown at my webhook?+
How does the token work with dynamic (endpoint-driven) Flows?+
How do I prevent processing the same submission twice?+
Build WhatsApp Flows that never lose a submission
Talk to an InfiQ onboarding specialist and we'll wire your flow_token handling, webhooks, and confirmation templates so every Flow response lands on the right record the first time.