Pular para o conteúdo

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.

  • Uma conexão de WhatsApp ativa. O Flow pertence à conta de mensagens (WABA) dela.
  • Chave com a permissão templates (criar, editar, publicar) e read (ler e ver as trocas).
  • No webhook do app da Meta, o campo flows assinado.
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": "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}/json troca o JSON (corpo cru, até 10 MiB). O Messajo confere o básico (JSON válido, version e screens) e a Meta valida o resto: os erros dela voltam em 422 flow_invalid_json, com details[].path no formato flow_json:<linha>:<coluna>.
  • Só um DRAFT muda. Publicado → 409 flow_not_editable; faça POST /v1/flows/{id}/clone e edite a cópia.
  • POST /v1/flows/{id}/preview devolve preview_url e expires_at para abrir o Flow no navegador.
  • POST /v1/flows/{id}/publish publica; …/deprecate aposenta; DELETE apaga (só DRAFT); …/sync relê 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.

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

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

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/agendamento
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": "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" }] } }
  • context vem null quando o Flow não saiu pelo Messajo (sem flow_token conhecido).
  • flow_token que você não reconhece → responda { "error": "flow_token_invalid" }: o Messajo devolve 427 à 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 recebe 500 e o contato vê um erro genérico. Cada troca fica em GET /v1/flows/{id}/exchanges por 7 dias (sem os dados), com o resultado e o tempo.

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.

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

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