# 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](https://developers.facebook.com/docs/whatsapp/flows) 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

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

## Crear y editar el JSON

```bash
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`](/es/errors#flow_invalid_json), con `details[].path` en el formato `flow_json:<línea>:<columna>`.
- Solo cambia un `DRAFT`. Publicado → `409` [`flow_not_editable`](/es/errors#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.

## Enviar el Flow

```json
{
  "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

Cuando el contacto termina el Flow, llegan `message.received` (contenido `reply` con `kind: "flow"`) y `flow.response`:

```json
{
  "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

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:

```json
{ "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`](/es/errors#flow_handler_required). La URL del handler sigue las reglas de los [destinos](/es/webhooks/destinations/): `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:

```http
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:

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

### 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](/es/webhooks/verify-signature/).

<Code code={nodeSnippet} lang="ts" title="verify.ts" />

<Code code={pythonSnippet} lang="python" title="verify.py" />

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

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`](/es/errors#flow_key_not_uploaded).

Por el [espejo](/es/operate/migrate/), `whatsapp_business_encryption` queda bloqueado (`403 mirror_path_blocked`) cuando la clave es de Messajo, para que nadie la cambie desde afuera.

## Errores

| Código | Cuándo |
|---|---|
| [`flow_not_found`](/es/errors#flow_not_found) | el Flow no existe o es de otra organización |
| [`flow_invalid_json`](/es/errors#flow_invalid_json) | JSON rechazado (Meta `139001`) |
| [`flow_error`](/es/errors#flow_error) | otro error `139xxx` de Meta |
