Guides
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 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
Section titled “Before you start”- An active WhatsApp connection. The Flow belongs to its messaging account (WABA).
- A key with
templates(create, edit, publish) andread(read and see the exchanges). - In your Meta app’s webhook, the
flowsfield subscribed.
Create and edit the JSON
Section titled “Create and edit the JSON”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}/jsonreplaces the JSON (raw body, up to 10 MiB). Messajo checks the basics (valid JSON,versionandscreens) and Meta validates the rest: its errors come back as422flow_invalid_json, withdetails[].pathasflow_json:<line>:<column>.- Only a
DRAFTchanges. Published →409flow_not_editable; callPOST /v1/flows/{id}/cloneand edit the copy. POST /v1/flows/{id}/previewreturnspreview_urlandexpires_atto open the Flow in the browser.POST /v1/flows/{id}/publishpublishes;…/deprecateretires;DELETEdeletes (onlyDRAFT);…/syncreloads 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
Section titled “Sending the Flow”{ "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
Section titled “Receiving the responses”When the contact finishes the Flow, message.received (reply content with kind: "flow") and flow.response arrive:
{ "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
Section titled “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:
{ "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. The handler URL follows the destination 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:
POST https://app.yourcompany.com/flows/bookingContent-Type: application/jsonMessajo-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:
{ "screen": "TIMES", "data": { "times": [{ "id": "09", "title": "09:00" }] } }contextisnullwhen the Flow was not sent through Messajo (no knownflow_token).- A
flow_tokenyou don’t recognize → reply{ "error": "flow_token_invalid" }: Messajo returns427to 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 gets500and the contact sees a generic error. Each exchange stays inGET /v1/flows/{id}/exchangesfor 7 days (without the data), with the result and duration.
Verifying the handler signature
Section titled “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.
import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 300;const DIGITS = /^\d+$/;
/** * Checks the Messajo-Signature header ("t=<unix s>,v1=<hex>[,v1=<hex>…]"). * `rawBody` must be the exact body received, before any JSON parsing. */export function verify( header: string, rawBody: string, secret: string, nowSeconds: number = Math.floor(Date.now() / 1000)): boolean { const timestamps: string[] = []; const signatures: string[] = []; for (const part of header.split(",")) { const [key, value = ""] = part.trim().split("=", 2); if (key === "t") { timestamps.push(value); } else if (key === "v1") { signatures.push(value); } } const [rawTimestamp = ""] = timestamps; if (timestamps.length !== 1 || !DIGITS.test(rawTimestamp)) { return false; } const timestamp = Number(rawTimestamp); if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) { return false; } const expected = Buffer.from( createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex") ); return signatures.some((signature) => { const received = Buffer.from(signature); return ( received.length === expected.length && timingSafeEqual(received, expected) ); });}"""Verify a Messajo webhook signature.
Usage: python3 verify.py <secret> <Messajo-Signature header> < raw_bodyExit code 0 = valid signature, 1 = invalid."""
import hashlibimport hmacimport sysimport time
TOLERANCE_SECONDS = 300
def verify(header: str, raw_body: bytes, secret: str, now: int | None = None) -> bool: """`raw_body` must be the exact bytes received, before any JSON parsing.""" timestamps, signatures = [], [] for part in header.split(","): key, _, value = part.strip().partition("=") if key == "t": timestamps.append(value) elif key == "v1": signatures.append(value) if len(timestamps) != 1 or not (timestamps[0].isascii() and timestamps[0].isdigit()): return False timestamp = int(timestamps[0]) now = int(time.time()) if now is None else now if abs(now - timestamp) > TOLERANCE_SECONDS: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, signature) for signature in signatures)
if __name__ == "__main__": secret, header = sys.argv[1], sys.argv[2] sys.exit(0 if verify(header, sys.stdin.buffer.read(), secret) else 1)Codes Meta receives
Section titled “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
Section titled “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.
Through the mirror, whatsapp_business_encryption is blocked (403 mirror_path_blocked) when the key is Messajo’s, so nobody replaces the key from outside.
Errors
Section titled “Errors”| Code | When |
|---|---|
flow_not_found |
the Flow does not exist or belongs to another organization |
flow_invalid_json |
JSON rejected (Meta 139001) |
flow_error |
another Meta 139xxx error |