Guias
WhatsApp Flows
Criar, publicar e mandar Flows, receber as respostas e usar o endpoint de data exchange do Messajo, que cuida da criptografia da Meta.
Um WhatsApp Flow é um formulário de várias telas que abre dentro do WhatsApp. O Messajo cria e publica o Flow na sua conta de mensagens, manda o Flow numa mensagem, entrega a resposta como evento e, se o Flow busca dados no seu sistema, hospeda o endpoint que a Meta chama: a criptografia RSA/AES fica com o Messajo e o seu servidor recebe JSON em texto claro, assinado.
Antes de começar
Seção intitulada “Antes de começar”- Uma conexão de WhatsApp ativa. O Flow pertence à conta de mensagens (WABA) dela.
- Chave com a permissão
templates(criar, editar, publicar) eread(ler e ver as trocas). - No webhook do app da Meta, o campo
flowsassinado.
Criar e editar o JSON
Seção intitulada “Criar e editar o JSON”curl https://api.messajo.com/v1/flows \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "name": "agendamento", "categories": ["APPOINTMENT_BOOKING"], "flow_json": { "version": "7.0", "screens": [ ... ] } }'O Flow nasce DRAFT (flw_…). Categorias: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY e OTHER.
PUT /v1/flows/{id}/jsontroca o JSON (corpo cru, até 10 MiB). O Messajo confere o básico (JSON válido,versionescreens) e a Meta valida o resto: os erros dela voltam em422flow_invalid_json, comdetails[].pathno formatoflow_json:<linha>:<coluna>.- Só um
DRAFTmuda. Publicado →409flow_not_editable; façaPOST /v1/flows/{id}/clonee edite a cópia. POST /v1/flows/{id}/previewdevolvepreview_urleexpires_atpara abrir o Flow no navegador.POST /v1/flows/{id}/publishpublica;…/deprecateaposenta;DELETEapaga (sóDRAFT);…/syncrelê o status da Meta.
No painel, Flows tem a lista, o editor de JSON com prévia e o link para o construtor visual da Meta.
Mandar o Flow
Seção intitulada “Mandar o Flow”{ "connection_id": "conn_...", "to": "5511999990001", "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Escolha o melhor horário" }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_id": "flw_...", "flow_cta": "Agendar", "flow_action": "navigate", "flow_action_payload": { "screen": "INICIO" } } } }}flow_id aceita o flw_… do Messajo ou o id da Meta. flow_cta vai até 20 caracteres. Sem flow_token, o Messajo gera um (mjft_…) e guarda com o contato, a conversa e a mensagem, para o endpoint saber de quem é a troca. Um Flow num template (botão FLOW) funciona igual.
Receber as respostas
Seção intitulada “Receber as respostas”Quando o contato termina o Flow, chegam message.received (conteúdo reply com kind: "flow") e flow.response:
{ "type": "flow.response", "data": { "flow": { "id": "flw_...", "external_id": "1234567890", "name": "agendamento" }, "flow_token": "mjft_...", "response": { "data": "2026-11-20", "horario": "09:00" }, "message": { "id": "msg_..." }, "contact": { "id": "ctc_..." }, "conversation": { "id": "cnv_..." } }}Outros eventos: flow.status_changed (a Meta publicou, bloqueou ou limitou o Flow), flow.endpoint_alert (alerta de saúde do endpoint: taxa de erro, latência, disponibilidade) e flow.endpoint_error (o app do contato avisou um erro no endpoint).
O endpoint de data exchange do Messajo
Seção intitulada “O endpoint de data exchange do Messajo”Flow que busca dados (tela dinâmica, validação, agendamento) precisa de um endpoint. Dê ao Flow um endpoint com a URL do seu handler:
{ "endpoint": { "url": "https://app.suaempresa.com/flows/agendamento", "headers": [{ "name": "X-Tenant", "value": "loja-1" }] } }O Messajo cadastra na Meta o endereço https://api.messajo.com/meta/flows/<flw_id> e devolve o handler_secret uma vez (gire com POST /v1/flows/{id}/rotate-handler-secret). Sem handler, um Flow com endpoint volta 422 flow_handler_required. A URL do handler segue as regras dos destinos: https e endereço público.
A cada troca, a Meta chama o Messajo; o Messajo confere a assinatura da Meta, decifra, responde sozinho o ping e as notificações de erro, e repassa INIT, BACK e data_exchange para o seu handler:
POST https://app.suaempresa.com/flows/agendamentoContent-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": "agendamento" }, "action": "data_exchange", "screen": "INICIO", "data": { "data": "2026-11-20" }, "flow_token": "mjft_...", "context": { "connection_id": "conn_...", "contact_id": "ctc_...", "message_id": "msg_..." }, "version": "3.0"}Responda 200 com a próxima tela, no formato da Meta:
{ "screen": "HORARIOS", "data": { "horarios": [{ "id": "09", "title": "09:00" }] } }contextvemnullquando o Flow não saiu pelo Messajo (semflow_tokenconhecido).flow_tokenque você não reconhece → responda{ "error": "flow_token_invalid" }: o Messajo devolve427à Meta e o app mostra que o Flow expirou.- Tempo máximo do handler: 7 s; resposta até 256 KiB. Erro, demora ou resposta sem
screen→ a Meta recebe500e o contato vê um erro genérico. Cada troca fica emGET /v1/flows/{id}/exchangespor 7 dias (sem os dados), com o resultado e o tempo.
Verificar a assinatura do handler
Seção intitulada “Verificar a assinatura do handler”O Messajo-Signature é igual ao dos webhooks, com o handler_secret como chave: HMAC-SHA256 de ${t}.${corpo cru}, comparação em tempo constante e tolerância de 5 minutos. Detalhes em Verificar a assinatura.
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)Códigos que a Meta recebe
Seção intitulada “Códigos que a Meta recebe”| HTTP | Quando | O que o app do contato faz |
|---|---|---|
200 |
resposta cifrada | segue o Flow |
421 |
o Messajo não decifrou com a chave atual nem com a anterior | baixa a chave pública de novo e repete |
427 |
o handler respondeu flow_token_invalid |
mostra que o Flow não vale mais |
432 |
a assinatura da Meta (X-Hub-Signature-256) não confere |
erro |
429 |
mais de 1.200 trocas por minuto no Flow | erro |
500 |
o handler falhou | erro genérico |
Chave e rotação
Seção intitulada “Chave e rotação”A Meta cifra cada troca com a chave pública da conta de mensagens. O Messajo gera um par RSA 2048 na primeira vez que um Flow da conta usa o endpoint, envia a chave a todos os números ativos e confere todo dia se a Meta ainda tem a chave certa (reenvia sozinho se faltar). Para trocar: POST /v1/connections/{id}/flow-key/rotate (chave admin); a chave anterior continua decifrando por 24 horas. Publicar sem a chave enviada a pelo menos um número → 409 flow_key_not_uploaded.
Pelo espelho, whatsapp_business_encryption fica bloqueado (403 mirror_path_blocked) quando a chave é do Messajo, para ninguém trocar a chave por fora.
| Código | Quando |
|---|---|
flow_not_found |
o Flow não existe ou é de outra organização |
flow_invalid_json |
JSON recusado (Meta 139001) |
flow_error |
outro erro 139xxx da Meta |