Guías
WhatsApp Flows
Crear, publicar y enviar Flows, recibir las respuestas y usar el endpoint de data exchange de Messajo, que se encarga del cifrado de Meta.
Un WhatsApp Flow es un formulario de varias pantallas que se abre dentro de WhatsApp. Messajo crea y publica el Flow en tu cuenta de mensajería, lo envía en un mensaje, entrega la respuesta como evento y, si el Flow busca datos en tu sistema, aloja el endpoint que llama Meta: el cifrado RSA/AES queda con Messajo y tu servidor recibe JSON en texto claro, firmado.
Antes de empezar
Sección titulada «Antes de empezar»- Una conexión de WhatsApp activa. El Flow pertenece a su cuenta de mensajería (WABA).
- Clave con el permiso
templates(crear, editar, publicar) yread(leer y ver los intercambios). - En el webhook de la app de Meta, el campo
flowssuscrito.
Crear y editar el JSON
Sección titulada «Crear y editar el JSON»curl https://api.messajo.com/v1/flows \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "name": "reservas", "categories": ["APPOINTMENT_BOOKING"], "flow_json": { "version": "7.0", "screens": [ ... ] } }'El Flow nace DRAFT (flw_…). Categorías: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY y OTHER.
PUT /v1/flows/{id}/jsonreemplaza el JSON (cuerpo crudo, hasta 10 MiB). Messajo revisa lo básico (JSON válido,versionyscreens) y Meta valida el resto: sus errores vuelven en422flow_invalid_json, condetails[].pathen el formatoflow_json:<línea>:<columna>.- Solo cambia un
DRAFT. Publicado →409flow_not_editable; hazPOST /v1/flows/{id}/cloney edita la copia. POST /v1/flows/{id}/previewdevuelvepreview_urlyexpires_atpara abrir el Flow en el navegador.POST /v1/flows/{id}/publishpublica;…/deprecatelo retira;DELETElo borra (soloDRAFT);…/syncvuelve a leer el estado de Meta.
En el panel, Flows tiene la lista, el editor de JSON con vista previa y el enlace al constructor visual de Meta.
Enviar el Flow
Sección titulada «Enviar el Flow»{ "connection_id": "conn_...", "to": "5511999990001", "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Elige el mejor horario" }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_id": "flw_...", "flow_cta": "Reservar", "flow_action": "navigate", "flow_action_payload": { "screen": "INICIO" } } } }}flow_id acepta el flw_… de Messajo o el id de Meta. flow_cta tiene hasta 20 caracteres. Sin flow_token, Messajo genera uno (mjft_…) y lo guarda con el contacto, la conversación y el mensaje, para que el endpoint sepa de quién es el intercambio. Un Flow en una plantilla (botón FLOW) funciona igual.
Recibir las respuestas
Sección titulada «Recibir las respuestas»Cuando el contacto termina el Flow, llegan message.received (contenido reply con kind: "flow") y flow.response:
{ "type": "flow.response", "data": { "flow": { "id": "flw_...", "external_id": "1234567890", "name": "reservas" }, "flow_token": "mjft_...", "response": { "fecha": "2026-11-20", "hora": "09:00" }, "message": { "id": "msg_..." }, "contact": { "id": "ctc_..." }, "conversation": { "id": "cnv_..." } }}Otros eventos: flow.status_changed (Meta publicó, bloqueó o limitó el Flow), flow.endpoint_alert (alerta de salud del endpoint: tasa de error, latencia, disponibilidad) y flow.endpoint_error (la app del contacto avisó un error en el endpoint).
El endpoint de data exchange de Messajo
Sección titulada «El endpoint de data exchange de Messajo»Un Flow que busca datos (pantallas dinámicas, validación, reservas) necesita un endpoint. Dale al Flow un endpoint con la URL de tu handler:
{ "endpoint": { "url": "https://app.tuempresa.com/flows/reservas", "headers": [{ "name": "X-Tenant", "value": "tienda-1" }] } }Messajo registra en Meta la dirección https://api.messajo.com/meta/flows/<flw_id> y devuelve el handler_secret una vez (gíralo con POST /v1/flows/{id}/rotate-handler-secret). Sin handler, un Flow con endpoint devuelve 422 flow_handler_required. La URL del handler sigue las reglas de los destinos: https y dirección pública.
En cada intercambio, Meta llama a Messajo; Messajo verifica la firma de Meta, descifra, responde solo el ping y las notificaciones de error, y reenvía INIT, BACK y data_exchange a tu handler:
POST https://app.tuempresa.com/flows/reservasContent-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": "reservas" }, "action": "data_exchange", "screen": "INICIO", "data": { "fecha": "2026-11-20" }, "flow_token": "mjft_...", "context": { "connection_id": "conn_...", "contact_id": "ctc_...", "message_id": "msg_..." }, "version": "3.0"}Responde 200 con la próxima pantalla, en el formato de Meta:
{ "screen": "HORARIOS", "data": { "horarios": [{ "id": "09", "title": "09:00" }] } }contextvienenullcuando el Flow no salió por Messajo (sinflow_tokenconocido).- Un
flow_tokenque no reconoces → responde{ "error": "flow_token_invalid" }: Messajo devuelve427a Meta y la app muestra que el Flow expiró. - Tiempo máximo del handler: 7 s; respuesta de hasta 256 KiB. Error, demora o respuesta sin
screen→ Meta recibe500y el contacto ve un error genérico. Cada intercambio queda enGET /v1/flows/{id}/exchangespor 7 días (sin los datos), con el resultado y el tiempo.
Verificar la firma del handler
Sección titulada «Verificar la firma del handler»El Messajo-Signature es igual al de los webhooks, con el handler_secret como clave: HMAC-SHA256 de ${t}.${cuerpo crudo}, comparación en tiempo constante y tolerancia de 5 minutos. Detalles en Verificar la firma.
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 recibe Meta
Sección titulada «Códigos que recibe Meta»| HTTP | Cuándo | Qué hace la app del contacto |
|---|---|---|
200 |
respuesta cifrada | sigue el Flow |
421 |
Messajo no pudo descifrar con la clave actual ni con la anterior | descarga la clave pública de nuevo y repite |
427 |
el handler respondió flow_token_invalid |
muestra que el Flow ya no vale |
432 |
la firma de Meta (X-Hub-Signature-256) no coincide |
error |
429 |
más de 1.200 intercambios por minuto en el Flow | error |
500 |
el handler falló | error genérico |
Clave y rotación
Sección titulada «Clave y rotación»Meta cifra cada intercambio con la clave pública de la cuenta de mensajería. Messajo genera un par RSA 2048 la primera vez que un Flow de la cuenta usa el endpoint, sube la clave a todos los números activos y revisa a diario que Meta siga teniendo la clave correcta (la vuelve a subir si falta). Para cambiarla: POST /v1/connections/{id}/flow-key/rotate (clave admin); la clave anterior sigue descifrando por 24 horas. Publicar sin la clave subida a al menos un número → 409 flow_key_not_uploaded.
Por el espejo, whatsapp_business_encryption queda bloqueado (403 mirror_path_blocked) cuando la clave es de Messajo, para que nadie la cambie desde afuera.
Errores
Sección titulada «Errores»| Código | Cuándo |
|---|---|
flow_not_found |
el Flow no existe o es de otra organización |
flow_invalid_json |
JSON rechazado (Meta 139001) |
flow_error |
otro error 139xxx de Meta |