> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payable.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Ligações com IA

> Cobrança por voz — telefone ou WhatsApp — via API

# 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

```bash theme={null}
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](https://docs.payable.run/pt-BR/errors.md). 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

```bash theme={null}
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](https://docs.payable.run/pt-BR/webhooks.md)):

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.