Guías

WhatsApp Flows

Un Flow es un formulario que se abre dentro del chat de WhatsApp: agendar una hora, registrarse, responder una encuesta o armar un pedido. El cliente lo completa sin salir de WhatsApp y la respuesta te llega por webhook. Solo existe en WhatsApp Cloud.

Cómo funciona#

• Los Flows viven en la cuenta de WhatsApp (WABA) de tu número, en Meta. heysteff guarda una copia para listarlos sin ir a Meta y para su configuración propia (save_to_contact).
• Cada Flow pasa por DRAFT (borrador: se edita y se prueba), PUBLISHED (se manda a cualquier cliente y ya no cambia) y DEPRECATED (ya no se manda ni se abre). Meta puede dejarlo en BLOCKED o THROTTLED si su salud baja.
• Las pantallas se definen en el Flow JSON, el formato de Meta (referencia del Flow JSON↗). heysteff lo sube tal cual y te devuelve los errores que encuentre Meta.
• Necesitas un número de WhatsApp Cloud conectado (no sirve WhatsApp por QR) y una key sk_live_ con flows:read y flows:write. Una key de prueba responde 403 test_key_not_allowed: el número compartido del sandbox no tiene Flows tuyos.

Crear y publicar un Flow#

1. POST /v1/whatsapp-flows crea un borrador con name, categories (SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY u OTHER) y, si quieres, el flow_json (objeto o texto, hasta 1 MB). Sin channel_connection_id se crea en la cuenta del número de WhatsApp Cloud conectado más reciente.
2. Revisa validation_errors en la respuesta: vacío quiere decir que el Flow JSON está listo. Si hay errores, corrígelos y sube el JSON de nuevo con PUT /v1/whatsapp-flows/{id}/json.
3. Pruébalo: GET /v1/whatsapp-flows/{id}/preview da un link que abre el formulario en el navegador, y también puedes mandártelo con mode: "draft".
4. POST /v1/whatsapp-flows/{id}/publish lo publica. Desde ahí ya no cambia: para otra versión, crea otro Flow.

curl https://app.heysteff.com/api/v1/whatsapp-flows \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agendar visita",
    "categories": ["APPOINTMENT_BOOKING"],
    "save_to_contact": true,
    "flow_json": {
      "version": "6.3",
      "screens": [
        {
          "id": "AGENDAR",
          "title": "Agenda tu visita",
          "terminal": true,
          "layout": {
            "type": "SingleColumnLayout",
            "children": [
              { "type": "TextInput", "name": "nombre", "label": "Nombre", "required": true },
              { "type": "DatePicker", "name": "fecha", "label": "Fecha", "required": true },
              {
                "type": "Footer",
                "label": "Enviar",
                "on-click-action": {
                  "name": "complete",
                  "payload": { "nombre": "${form.nombre}", "fecha": "${form.fecha}" }
                }
              }
            ]
          }
        }
      ]
    }
  }'

{
  "data": {
    "id": "0b6f4c1e-2d3a-4b5c-8d9e-1f2a3b4c5d6e",
    "flow_id": "1234567890123456",
    "channel_connection_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "name": "Agendar visita",
    "status": "DRAFT",
    "categories": ["APPOINTMENT_BOOKING"],
    "validation_errors": [],
    "save_to_contact": true,
    "responses_count": 0
  }
}

Guarda los dos ids: id es el de heysteff (el de las rutas /v1/whatsapp-flows/{id}) y flow_id es el de Meta, el que va en el mensaje y en el botón de una plantilla.

import { Heysteff } from '@heysteff/sdk';

const heysteff = new Heysteff({ apiKey: process.env.HEYSTEFF_API_KEY });

const flow = await heysteff.whatsappFlows.create({
  name: 'Agendar visita',
  categories: ['APPOINTMENT_BOOKING'],
  flow_json: flowJson,
});
if (flow.validation_errors.length === 0) await heysteff.whatsappFlows.publish(flow.id);
const { preview_url } = await heysteff.whatsappFlows.preview(flow.id);

Desde la consola: en la consola de developers, la sección Flows de WhatsApp lista tus Flows, los crea, sube el JSON, los publica o depreca, los sincroniza con Meta y muestra las respuestas. Desde tu IA: las tools MCP list_whatsapp_flows, get_whatsapp_flow, create_whatsapp_flow, update_whatsapp_flow, upload_whatsapp_flow_json, publish_whatsapp_flow, deprecate_whatsapp_flow, delete_whatsapp_flow, get_whatsapp_flow_preview, sync_whatsapp_flows y list_whatsapp_flow_responses.

Mandar un Flow#

Con la conversación abierta (dentro de las 24 horas desde el último mensaje del cliente), manda content_type: "flow" por POST /v1/messages. Sale como un mensaje con un botón que abre el formulario.

curl https://app.heysteff.com/api/v1/messages \
  -H "Authorization: Bearer $HEYSTEFF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_cloud",
    "to": "+56912345678",
    "content_type": "flow",
    "flow": {
      "flow_id": "1234567890123456",
      "cta": "Agendar",
      "body": "Elige el día de tu visita y te confirmamos enseguida.",
      "flow_token": "pedido-1042"
    }
  }'

Fuera de las 24 horas responde 409 wa_window_closed: usa una plantilla con botón FLOW. Se crea con POST /v1/templates y un botón {"type": "FLOW", "text": "Agendar", "flow_id": "1234567890123456", "flow_action": "navigate", "navigate_screen": "AGENDAR"} (el Flow tiene que estar publicado), y se manda así:

{
  "channel": "whatsapp_cloud",
  "to": "+56912345678",
  "content_type": "template",
  "template": {
    "name": "agendar_visita",
    "language": "es",
    "components": [
      {
        "type": "button",
        "sub_type": "flow",
        "index": "0",
        "parameters": [
          { "type": "action", "action": { "flow_token": "pedido-1042", "flow_action_data": { "sucursal": "centro" } } }
        ]
      }
    ]
  }
}

Si Meta rechaza el Flow al enviarlo (por ejemplo, porque está deprecado), el mensaje queda failed y llega el webhook message.failed. No se reemplaza por texto: un formulario convertido en texto no le sirve al cliente.

Endpoint de datos (data_exchange): heysteff todavía no aloja el endpoint cifrado que usa un Flow para pedir datos en vivo entre pantallas. Si tu Flow lo necesita, configúralo en Meta con tu propio servidor; heysteff igual manda el Flow con action: "data_exchange" y te entrega la respuesta final.

Recibir las respuestas#

Cuando el cliente envía el formulario llega el webhook message:received con flow_response: el flow_token con que mandaste el Flow y los campos en data, con las claves de tu Flow JSON. El content del mensaje es la misma respuesta en texto (una línea campo: valor por campo), que es lo que ve tu equipo en la bandeja.

{
  "event": "message:received",
  "data": {
    "conversation_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "message_id": "4e3d2c1b-0a9f-4e8d-7c6b-5a4f3e2d1c0b",
    "channel": "whatsapp_cloud",
    "content": "nombre: Ana\nfecha: 2026-11-20",
    "content_type": "interactive",
    "interactive_reply": null,
    "flow_response": {
      "flow_token": "pedido-1042",
      "data": { "nombre": "Ana", "fecha": "2026-11-20" }
    }
  }
}

En cualquier otro mensaje, flow_response es null. Lo mismo trae GET /v1/messages/{id}. Para leerlas después, GET /v1/whatsapp-flows/responses las lista de la más nueva a la más vieja (flow_id filtra por el id heysteff del Flow; para la página siguiente, manda before con el next_before de la respuesta).

Guardar las respuestas en el contacto#

Con save_to_contact: true (al crear el Flow o con PATCH /v1/whatsapp-flows/{id}), cada campo simple de la respuesta (texto, número, sí/no o una lista de textos) se guarda en el campo del contacto con la misma clave. Las claves tienen que ir en minúsculas, con números y guiones bajos, empezando por una letra (nombre, fecha_visita). Si el campo existe en Contactos, el valor se valida con su tipo; si no existe, se guarda tal cual. La respuesta trae saved_to_contact en GET /v1/whatsapp-flows/responses.

Errores#