Flujos de conversación · Documentación

GET /api/v1/flows

Lista todos los flujos de conversación disponibles en tu cuenta.

Respuesta

{
  "object": "list",
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Flujo de Cobranza",
      "description": "Recordatorio de pago con opciones",
      "type": "collection",
      "purpose": "Recordatorio",
      "channel": "whatsapp",
      "status": "published",
      "version": 1,
      "total_runs": 150,
      "total_responses": 89,
      "response_rate": 59.3,
      "published_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "url": "/v1/flows"
}

POST /api/v1/flows/{flow_id}/deploy

Despliega un flujo a uno o más destinatarios. Cada destinatario recibirá el flujo de forma independiente. Puedes incluir variables personalizadas que se usarán para reemplazar placeholders en los mensajes.

Cuerpo de la petición

{
  "recipients": [
    {
      "phone": "+5215512345678",
      "variables": {
        "nombre": "Juan Pérez",
        "monto": "$1,500.00",
        "fecha_limite": "15 de febrero"
      }
    },
    {
      "phone": "+5215587654321",
      "variables": {
        "nombre": "María García",
        "monto": "$2,300.00",
        "fecha_limite": "20 de febrero"
      }
    }
  ],
  "phone_number_id": "uuid-de-tu-numero-whatsapp", // Opcional: número desde el cual sale el flow. Si se omite, usa el default del tenant.
  "scheduled_at": null                              // Opcional: programar para después
}

phone_number_id identifica el número desde el cual sale el flow. Acepta dos formatos: el UUID interno del PhoneNumber, o el meta_phone_number_id (el ID numérico que Meta asigna al número, ej. 748899301642932). Lo puedes obtener desde /admin/settings/integrations/whatsapp/numbers. Si tu cuenta solo tiene un número de WhatsApp, no hace falta enviarlo.

Respuesta

{
  "success": true,
  "message": "Flow deployed to 2 recipients",
  "data": {
    "flow_id": "01234567-89ab-cdef-0123-456789abcdef",
    "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_recipients": 2,
    "runs_created": 2,
    "scheduled_at": null,
    "run_ids": [
      "f1a2b3c4-d5e6-7890-abcd-111111111111",
      "f1a2b3c4-d5e6-7890-abcd-222222222222"
    ]
  }
}

GET /api/v1/flows/{flow_id}/runs

Lista las ejecuciones de un flujo con filtros opcionales.

Parámetros de consulta

Parámetro	Tipo	Descripción
status	string	Filtrar por estado: pending, running, waiting, completed, failed, cancelled
batch_id	string	Filtrar por ID de lote (el que regresa el envío)
phone	string	Filtrar por número de teléfono del destinatario
limit	integer	Resultados por página (20 por defecto)

Respuesta

{
  "object": "list",
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-111111111111",
      "flow_id": "01234567-89ab-cdef-0123-456789abcdef",
      "flow_name": "Flujo de Cobranza",
      "phone_number": "+5215512345678",
      "country_code": "MX",
      "customer_id": "cust-uuid-123",
      "customer_name": "Juan Pérez",
      "conversation_id": "conv-uuid-789",
      "status": "completed",
      "source": "api",
      "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "context": {
        "nombre": "Juan Pérez",
        "monto": "$1,500.00"
      },
      "current_node_id": null,
      "error_message": null,
      "scheduled_at": null,
      "started_at": "2024-01-20T10:00:00Z",
      "finished_at": "2024-01-20T10:05:30Z",
      "created_at": "2024-01-20T09:59:58Z"
    }
  ],
  "has_more": false,
  "url": "/v1/flows/01234567-89ab-cdef-0123-456789abcdef/runs"
}

GET /api/v1/flows/{flow_id}/runs/{run_id}

Obtiene el detalle de una ejecución específica del flujo.

Respuesta

{
  "object": "flow_run",
  "id": "f1a2b3c4-d5e6-7890-abcd-111111111111",
  "flow_id": "01234567-89ab-cdef-0123-456789abcdef",
  "flow_name": "Flujo de Cobranza",
  "phone_number": "+5215512345678",
  "country_code": "MX",
  "customer_id": "cust-uuid-123",
  "customer_name": "Juan Pérez",
  "conversation_id": "conv-uuid-789",
  "status": "waiting",
  "source": "api",
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "context": {
    "nombre": "Juan Pérez",
    "monto": "$1,500.00",
    "respuesta_cliente": "Sí, pagaré mañana"
  },
  "current_node_id": "node_1768811907821_4wexo4g3h",
  "error_message": null,
  "scheduled_at": null,
  "started_at": "2024-01-20T10:00:00Z",
  "finished_at": null,
  "created_at": "2024-01-20T09:59:58Z"
}

POST /api/v1/flows/{flow_id}/runs/{run_id}/variables

Actualiza las variables de una ejecución en curso. Útil para inyectar información externa que será usada en los siguientes nodos del flujo.

Cuerpo de la petición

{
  "variables": {
    "crm_status": "contacted",
    "agent_notes": "Cliente confirmó pago para mañana",
    "follow_up_date": "2024-01-21"
  }
}

POST /api/v1/flows/{flow_id}/runs/{run_id}/cancel

Cancela una ejecución que está pendiente o en espera. Las ejecuciones completadas o fallidas no pueden cancelarse.

Respuesta

{
  "success": true,
  "message": "Flow run cancelled successfully",
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-111111111111",
    "flow_id": "01234567-89ab-cdef-0123-456789abcdef",
    "flow_name": "Flujo de Cobranza",
    "phone_number": "+5215512345678",
    "country_code": "MX",
    "customer_id": "cust-uuid-123",
    "customer_name": "Juan Pérez",
    "conversation_id": null,
    "status": "cancelled",
    "source": "api",
    "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "context": {
      "nombre": "Juan Pérez"
    },
    "current_node_id": null,
    "error_message": null,
    "scheduled_at": null,
    "started_at": null,
    "finished_at": "2024-01-20T11:00:00Z",
    "created_at": "2024-01-20T09:59:58Z"
  }
}

Webhooks de conversación

Configura webhooks para recibir avisos en tiempo real de conversaciones y flujos. Se configuran desde el panel de Avisos a tus sistemas.

Eventos disponibles

Evento	Descripción
conversation.created	Nueva conversación iniciada
conversation.assigned	Conversación asignada a un agente
conversation.transferred	Conversación transferida a otro agente o grupo
conversation.resolved	Conversación marcada como resuelta
conversation.closed	Conversación cerrada con motivo
conversation.message.received	Mensaje recibido del cliente
conversation.message.sent	Mensaje enviado al cliente
flow_run.started	Ejecución de flujo iniciada
flow_run.completed	Ejecución de flujo completada
flow_run.failed	Ejecución de flujo fallida
flow_run.waiting	Flujo esperando respuesta del cliente

Ejemplo de datos (conversation.message.received)

{
  "id": "evt_123456",
  "type": "conversation.message.received",
  "created_at": "2024-01-20T10:05:30Z",
  "data": {
    "id": "msg_abc123",
    "conversation_id": "conv_xyz789",
    "direction": "inbound",
    "type": "text",
    "body": "Sí, haré el pago mañana",
    "sender_identifier": "+5215512345678",
    "created_at": "2024-01-20T10:05:30Z",
    "conversation": {
      "id": "conv_xyz789",
      "channel": "whatsapp",
      "channel_identifier": "+5215512345678",
      "status": "open",
      "customer_id": "cust_abc",
      "customer_name": "Juan Pérez",
      "assigned_user_id": "user_123",
      "assigned_user_name": "Ana López"
    }
  }
}

Casos de uso

Campaña de cobranza masiva

Despliega un flujo de recordatorio de pago a miles de clientes con variables personalizadas (nombre, monto, fecha). El flujo puede incluir múltiples mensajes, esperas por respuesta, y ramificaciones basadas en las respuestas del cliente.

Integración con CRM

Usa los webhooks para sincronizar el estado de las conversaciones con tu CRM. Cuando un cliente responde, actualiza automáticamente su registro con la respuesta y programa seguimientos.

Encuestas y NPS

Manda flujos interactivos con botones para recopilar la opinión de tus clientes. Usa las variables de la ejecución para guardar las respuestas y consultarlas por API.