WhatsApp Flows

Los eventos whatsapp.flows.* son especiales: Platica no sólo te notifica que algo ocurrió, también espera tu respuesta para continuar el flow de WhatsApp.

Úsalos cuando quieras que tu backend controle pantallas dinámicas, validaciones, opciones de dropdown, precios, confirmaciones o cualquier dato que deba calcularse en tiempo real.

Advertencia

Tu endpoint debe responder con un JSON válido en menos de 700 ms. Si no responde a tiempo, Platica devuelve un fallback { "data": { "acknowledged": true } } hacia Meta.

Eventos

Evento	Cuándo ocurre
`whatsapp.flows.init`	El usuario abre el flow (`action: "INIT"`)
`whatsapp.flows.screen_advance`	El usuario avanza de pantalla (`action: "data_exchange"`)
`whatsapp.flows.back`	El usuario regresa a la pantalla anterior (`action: "BACK"`)
`whatsapp.flows.exchanges`	Suscripción paraguas para recibir los tres eventos anteriores

Ciclo de entrega

Payload recibido

{
  "event": "whatsapp.flows.screen_advance",
  "eventId": "8f2c4d6a-1b3e-4f5d-8a9c-2e7b6d1a3f4e",
  "occurredAt": "2026-05-06T19:00:30.000Z",
  "workspace": "ws_456",
  "wabaId": "1234567890",
  "flowId": "flow_doc_abc",
  "screen": "WELCOME",
  "flowToken": "ZmxvdyQwMQ==",
  "version": "3.0",
  "data": {
    "selected_product": "p2",
    "email": "juan@empresa.com"
  }
}

Campo	Tipo	Descripción
`event`	`string`	Evento recibido
`eventId`	`string`	UUID del envío
`occurredAt`	`string`	Fecha ISO-8601
`workspace`	`string`	Workspace propietario
`wabaId`	`string`	WhatsApp Business Account ID
`flowId`	`string`	Identificador interno del flow
`screen`	`string \\| null`	Pantalla actual
`flowToken`	`string \\| null`	Token de sesión enviado por Meta
`version`	`string \\| null`	Versión del protocolo de Flows
`data`	`object`	Datos capturados o enviados por Meta

Nota

Las claves del payload usan camelCase (flowToken, wabaId), aunque Meta use snake_case internamente (flow_token).

Respuesta esperada

Tu endpoint debe responder 2xx con JSON. Platica acepta la respuesta si cumple al menos una de estas condiciones:

Tiene data y data es un objeto.
Tiene screen y screen es un string no vacío.

Ejemplo para poblar datos dinámicos:

{
  "data": {
    "products": [
      { "id": "p1", "title": "Plan Básico" },
      { "id": "p2", "title": "Plan Premium" }
    ]
  }
}

Ejemplo para avanzar a una pantalla:

{
  "screen": "PAYMENT",
  "data": {
    "amount_mxn": 499
  }
}

Ejemplo para mostrar un error:

{
  "data": {
    "error_message": "El código postal no es válido"
  }
}

Headers y firma

Header	Descripción
`Content-Type`	`application/json`
`User-Agent`	`Platica-Webhooks/1.0`
`X-Platica-Event`	Igual a `payload.event`
`X-Platica-Event-Id`	Igual a `payload.eventId`
`X-Platica-Workspace`	Igual a `payload.workspace`
`X-Platica-Signature-Timestamp`	Unix epoch en segundos
`X-Platica-Signature`	`sha256=<hex>` si configuraste `secret`

La firma se calcula con HMAC-SHA256 usando el timestamp y el cuerpo crudo:

sha256=<hmac_sha256(secret, `${timestamp}.${rawBody}`)>

Ejemplo en Node.js:

const crypto = require('crypto');

function verifyFlowsWebhook(secret, rawBody, timestampHeader, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

`whatsapp.flows.init`

Ocurre cuando el usuario abre el flow. Normalmente se usa para precargar datos iniciales.

{
  "event": "whatsapp.flows.init",
  "eventId": "5e3a1b9c-7d12-4a8e-9c5f-1e6b8d0a2c4f",
  "occurredAt": "2026-05-06T19:00:00.000Z",
  "workspace": "ws_456",
  "wabaId": "1234567890",
  "flowId": "flow_doc_abc",
  "screen": null,
  "flowToken": "ZmxvdyQwMQ==",
  "version": "3.0",
  "data": {}
}

`whatsapp.flows.screen_advance`

Ocurre cuando el usuario llena una pantalla y pulsa continuar. data trae los valores capturados.

{
  "event": "whatsapp.flows.screen_advance",
  "eventId": "8f2c4d6a-1b3e-4f5d-8a9c-2e7b6d1a3f4e",
  "occurredAt": "2026-05-06T19:00:30.000Z",
  "workspace": "ws_456",
  "wabaId": "1234567890",
  "flowId": "flow_doc_abc",
  "screen": "WELCOME",
  "flowToken": "ZmxvdyQwMQ==",
  "version": "3.0",
  "data": {
    "selected_product": "p2",
    "email": "juan@empresa.com"
  }
}

`whatsapp.flows.back`

Ocurre cuando el usuario pulsa regresar. Úsalo para restaurar datos de una pantalla anterior.

{
  "event": "whatsapp.flows.back",
  "eventId": "3a5b7c9d-2e4f-4a6b-8c1d-5e7f9a2b4c6d",
  "occurredAt": "2026-05-06T19:01:00.000Z",
  "workspace": "ws_456",
  "wabaId": "1234567890",
  "flowId": "flow_doc_abc",
  "screen": "PAYMENT",
  "flowToken": "ZmxvdyQwMQ==",
  "version": "3.0",
  "data": {}
}

`whatsapp.flows.exchanges`

Es una suscripción paraguas para recibir init, screen_advance y back en un solo webhook.

Usa whatsapp.flows.exchanges si tu backend quiere manejar todos los pasos del flow con el mismo endpoint y la misma lógica.

Si necesitas separar lógica por paso, suscríbete a los eventos granulares:

whatsapp.flows.init
whatsapp.flows.screen_advance
whatsapp.flows.back

Anterior Payloads Siguiente Listar Webhooks