Skip to content

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.

  • 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.
Janela do terminal
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, with details[].path as flow_json:<line>:<column>.
  • Only a DRAFT changes. Published → 409 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.

{
"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.

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).

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/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:

{ "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.

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.

verify.ts
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.py
"""Verify a Messajo webhook signature.
Usage: python3 verify.py <secret> <Messajo-Signature header> < raw_body
Exit code 0 = valid signature, 1 = invalid.
"""
import hashlib
import hmac
import sys
import 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)
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

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.

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