Conversation flows · Documentation

GET /api/v1/flows

Lists all conversation flows available to your account.

Response

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

Deploys a flow to one or more recipients. Each recipient receives the flow independently. You can include custom variables used to replace placeholders in the messages.

Request body

{
  "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 identifies the number the flow is sent from. It accepts two formats: the internal UUID of the PhoneNumber, or the meta_phone_number_id (the numeric ID Meta assigns to the number, e.g. 748899301642932). You can get it from /admin/settings/integrations/whatsapp/numbers. If your account has only one WhatsApp number, you do not need to send it.

Response

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

Lists the runs of a flow with optional filters.

Query parameters

Parameter	Type	Description
status	string	Filter by status: pending, running, waiting, completed, failed, cancelled
batch_id	string	Filter by batch ID (returned by the deploy)
phone	string	Filter by the recipient's phone number
limit	integer	Results per page (default 20)

Response

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

Gets the details of a specific flow run.

Response

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

Updates the variables of a running execution. Useful to inject external information used in the next nodes of the flow.

Request body

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

Cancels a run that is pending or waiting. Completed or failed runs cannot be cancelled.

Response

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

Conversation webhooks

Set up webhooks to receive real-time notifications about conversation and flow events. Webhooks are configured from the panel of Alerts to your systems.

Available events

Event	Description
conversation.created	New conversation started
conversation.assigned	Conversation assigned to an agent
conversation.transferred	Conversation transferred to another agent or group
conversation.resolved	Conversation marked as resolved
conversation.closed	Conversation closed with a reason
conversation.message.received	Message received from the customer
conversation.message.sent	Message sent to the customer
flow_run.started	Flow run started
flow_run.completed	Flow run completed
flow_run.failed	Flow run failed
flow_run.waiting	Flow waiting for the customer to reply

Payload example (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"
    }
  }
}

Use cases

Bulk collections campaign

Deploy a payment reminder flow to thousands of customers with custom variables (name, amount, date). The flow can include several messages, waits for replies and branches based on the customer answers.

CRM integration

Use webhooks to sync the status of conversations with your CRM. When a customer replies, automatically update their record with the answer and schedule follow-ups.

Surveys and NPS

Deploy interactive flows with buttons to collect customer feedback. Use the run variables to store the answers and query the results via API.