Ir al contenido

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.

  • Una conexión de WhatsApp activa. El Flow pertenece a su cuenta de mensajería (WABA).
  • Clave con el permiso templates (crear, editar, publicar) y read (leer y ver los intercambios).
  • En el webhook de la app de Meta, el campo flows suscrito.
Ventana de terminal
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}/json reemplaza el JSON (cuerpo crudo, hasta 10 MiB). Messajo revisa lo básico (JSON válido, version y screens) y Meta valida el resto: sus errores vuelven en 422 flow_invalid_json, con details[].path en el formato flow_json:<línea>:<columna>.
  • Solo cambia un DRAFT. Publicado → 409 flow_not_editable; haz POST /v1/flows/{id}/clone y edita la copia.
  • POST /v1/flows/{id}/preview devuelve preview_url y expires_at para abrir el Flow en el navegador.
  • POST /v1/flows/{id}/publish publica; …/deprecate lo retira; DELETE lo borra (solo DRAFT); …/sync vuelve 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.

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

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

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/reservas
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": "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" }] } }
  • context viene null cuando el Flow no salió por Messajo (sin flow_token conocido).
  • Un flow_token que no reconoces → responde { "error": "flow_token_invalid" }: Messajo devuelve 427 a 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 recibe 500 y el contacto ve un error genérico. Cada intercambio queda en GET /v1/flows/{id}/exchanges por 7 días (sin los datos), con el resultado y el tiempo.

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.

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

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.

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