Ligações com IA

A Payable pode ligar para o devedor com uma assistente de voz que confirma a identidade, apresenta a cobrança e negocia dentro dos limites da régua (desconto, parcelamento, reagendamento), envia o Pix/link durante a ligação, registra promessa de pagamento e transfere para um atendente quando pedido. Duas formas de alcançar o cliente (medium):

`medium`	O que acontece
`pstn`	Ligação telefônica comum para o celular do cliente. Padrão.
`whatsapp`	Chamada de voz no WhatsApp. A Meta exige que o cliente aceite uma permissão de chamada antes; a ligação fica em `awaiting_permission` até ele aceitar e, se recusar ou não responder, cai para `pstn` quando `fallbackToPstn` é `true` (padrão).

Os escopos necessários na chave de API são voice-calls:read e voice-calls:write.

Iniciar uma ligação

curl -X POST "https://api.payable.run/api/v1/voice-calls" \
  -H "Authorization: Bearer esk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_uuid",
    "debtId": "debt_uuid",
    "medium": "pstn"
  }'

clientId e debtId são obrigatórios: toda ligação é sobre uma cobrança em aberto do cliente. A resposta é a ligação com status: "queued" (ou "awaiting_permission" no WhatsApp) e um array warnings com avisos não bloqueantes — por exemplo, quando a ligação foi pedida fora da janela de horário da régua com allowOutsideWindow: true.

Erros

Todos seguem RFC 9457. Decida pelo code:

`code`	Significado	Repetir?
`VOICE_CALLS_DISABLED`	Ligações não habilitadas na plataforma ou na régua	Não
`CLIENT_HAS_NO_OPEN_DEBT`	A cobrança informada não está em aberto para este cliente	Não
`VOICE_MEDIUM_UNAVAILABLE`	O `medium` pedido não está configurado	Não (tente o outro `medium`)
`VOICE_INVALID_PHONE`	Cliente sem celular válido	Após corrigir o cadastro
`CHANNEL_OPTED_OUT`	O cliente pediu para não receber ligações (ou descadastrou o WhatsApp)	Não
`CALL_IN_PROGRESS`	Já existe ligação na fila ou em andamento para o cliente	Depois que ela terminar
`OUTSIDE_CALL_WINDOW`	Fora da janela de horário da régua	Com `allowOutsideWindow: true` ou mais tarde
`VOICE_DAILY_ATTEMPTS_REACHED`	Limite diário de tentativas para o cliente	No dia seguinte
`INSUFFICIENT_BALANCE`	Saldo insuficiente	Após recarregar

Acompanhar

curl "https://api.payable.run/api/v1/voice-calls/{id}" -H "Authorization: Bearer esk_live_..."
curl "https://api.payable.run/api/v1/voice-calls?debtId=debt_uuid&status=completed" -H "Authorization: Bearer esk_live_..."

Ciclo de status: queued → (awaiting_permission →) dialing → in_progress → completed | failed. cancelled só antes de discar (POST /voice-calls/{id}/cancel). Ao terminar, a ligação recebe um outcome:

`outcome`	Descrição
`negotiated`	Cliente aceitou parcelamento ou novo vencimento
`promise_to_pay`	Cliente prometeu pagar em uma data (`promiseToPayDate`)
`paid_during_call`	Pagamento confirmado durante a ligação
`callback_requested`	Cliente pediu retorno
`refused`	Atendeu, mas nada foi combinado
`no_answer` / `busy` / `voicemail`	Não atendeu (a régua tenta de novo dentro dos limites)
`wrong_number`	Quem atendeu não conhece o cliente
`transferred_to_human`	Transferida para o telefone de atendimento
`permission_denied`	WhatsApp: cliente não permitiu a chamada
`failed`	Falha técnica

summary e transcript vêm em português; analysis.source diz se o desfecho foi determinístico (ações registradas pelas ferramentas), do provedor ou inferido pela IA a partir da transcrição.

Gravação

GET /voice-calls/{id}/recording devolve { "url": "...", "expiresInSeconds": 86400 } com uma URL assinada. Use ?redirect=1 para um 302 direto ao arquivo. As gravações ficam disponíveis por até 180 dias.

Webhook

O evento voice_call.completed é emitido ao final de cada ligação (veja Webhooks):

{
  "type": "voice_call.completed",
  "data": {
    "id": "vc_uuid",
    "clientId": "client_uuid",
    "debtId": "debt_uuid",
    "medium": "pstn",
    "trigger": "flow",
    "status": "completed",
    "outcome": "promise_to_pay",
    "answered": true,
    "durationSeconds": 95,
    "billedAmountCents": 298,
    "promiseToPayDate": "2026-10-01",
    "recordingUrl": "https://...(24h)",
    "summary": "O cliente prometeu pagar em 01/10/2026."
  }
}

Cobrança

Por minuto iniciado de ligação atendida (voice_call_minute) mais uma taxa fixa por tentativa não atendida (voice_call_attempt). Os valores atuais aparecem em GET /voice-calls/config.

Na régua

Em Réguas → Ligações com IA você habilita o canal, define a janela de horário (padrão 8h–20h, segunda a sábado), as tentativas por dia/etapa, a voz e o telefone de transferência. Depois, ative “Ligação (IA)” nas etapas desejadas. Fora da janela a régua segura a etapa até a próxima abertura; sem resposta ela tenta de novo respeitando os limites.

Começar

Integração

Referência da API

Ligações com IA

Ligações com IA

Iniciar uma ligação

Erros

Acompanhar

Gravação

Webhook

Cobrança

Na régua

​Ligações com IA

​Iniciar uma ligação

​Erros

​Acompanhar

​Gravação

​Webhook

​Cobrança

​Na régua

Ligações com IA

Iniciar uma ligação

Erros

Acompanhar

Gravação

Webhook

Cobrança

Na régua