Recaudo Docs
Criar conta

Conversas

Fluxos de conversa

A API de fluxos de conversa permite disparar fluxos automáticos de WhatsApp para seus clientes. Você pode iniciar campanhas em massa, acompanhar o status das execuções e atualizar variáveis em tempo real.

GET /api/v1/flows

Lista todos os fluxos de conversa disponíveis na sua conta.

Resposta

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

Dispara um fluxo para um ou mais destinatários. Cada destinatário recebe o fluxo de forma independente. Você pode incluir variáveis personalizadas para substituir os marcadores nas mensagens.

Corpo da requisição

{
  "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 o número de onde o fluxo sai. Aceita dois formatos: o UUID interno do PhoneNumber, ou o meta_phone_number_id (o ID numérico que a Meta atribui ao número, ex. 748899301642932). Você pode obtê-lo em /admin/settings/integrations/whatsapp/numbers. Se sua conta tem só um número de WhatsApp, não é necessário enviá-lo.

Resposta

{
  "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 as execuções de um fluxo com filtros opcionais.

Parâmetros de consulta

Parâmetro Tipo Descrição
status string Filtrar por status: pending, running, waiting, completed, failed, cancelled
batch_id string Filtrar por ID do lote (retornado no disparo)
phone string Filtrar pelo número de telefone do destinatário
limit integer Resultados por página (padrão 20)

Resposta

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

Obtém o detalhe de uma execução específica do fluxo.

Resposta

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

Atualiza as variáveis de uma execução em andamento. Útil para injetar informações externas usadas nos próximos nós do fluxo.

Corpo da requisição

{
  "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 uma execução pendente ou em espera. Execuções concluídas ou com falha não podem ser canceladas.

Resposta

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

Configure webhooks para receber avisos em tempo real sobre conversas e fluxos. Eles são configurados no painel de Avisos para seus sistemas.

Eventos disponíveis

Evento Descrição
conversation.created Nova conversa iniciada
conversation.assigned Conversa atribuída a um agente
conversation.transferred Conversa transferida para outro agente ou grupo
conversation.resolved Conversa marcada como resolvida
conversation.closed Conversa encerrada com motivo
conversation.message.received Mensagem recebida do cliente
conversation.message.sent Mensagem enviada ao cliente
flow_run.started Execução de fluxo iniciada
flow_run.completed Execução de fluxo concluída
flow_run.failed Execução de fluxo com falha
flow_run.waiting Fluxo aguardando resposta do cliente

Exemplo de dados (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

Campanha de cobrança em massa

Dispare um fluxo de lembrete de pagamento para milhares de clientes com variáveis personalizadas (nome, valor, data). O fluxo pode incluir várias mensagens, esperas por resposta e ramificações conforme as respostas do cliente.

Integração com CRM

Use os webhooks para sincronizar o status das conversas com seu CRM. Quando um cliente responde, atualize automaticamente o registro dele com a resposta e agende acompanhamentos.

Pesquisas e NPS

Dispare fluxos interativos com botões para coletar a opinião dos clientes. Use as variáveis da execução para guardar as respostas e consultar os resultados pela API.

Esta página ajudou? Obrigado por avisar.
Esc