> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Faça chamadas de saída (API)
> Dispare uma chamada de saída conduzida por IA a partir do seu próprio código — fluxos de pesquisa, acompanhamento ou confirmação.
As chamadas de saída permitem que você forneça um número de destino e uma
configuração de agente ao ThunderPhone para que a IA faça a chamada em seu
nome. Casos de uso típicos:
* Confirmações de agendamentos
* Retornos de pesquisas
* Acompanhamentos de "segunda tentativa" após uma chamada perdida
* Notificações no estilo de despacho
Vai ligar para uma lista inteira? O recurso
[**Campanhas**](/pt/guides/outbound-campaigns) do painel
(`/dashboard/campaigns`) recebe um CSV de contatos e gerencia
janelas de chamada com reconhecimento de fuso horário, simultaneidade e política de
tentativas para você. Este guia aborda chamadas programáticas individuais.
## Pré-requisitos
As chamadas de saída exigem que você seja proprietário do `from_number` por meio de uma
[conexão VoIP](/api-reference/voip-connections). Números de demonstração
aceitam apenas chamadas recebidas. Consulte
[Use seus próprios números](/pt/guides/bring-your-own-numbers).
Um prompt voltado para chamadas de saída normalmente começa com o agente
se identificando e explicando seu propósito — "Olá, aqui é da Acme, ligando para
confirmar seu agendamento de amanhã às 15h…" Defina
`outbound_speak_order` como `agent_first` (o padrão).
Chamadas de saída retornam `402 Payment Required` se o saldo for ≤
`$0.00`. Adicione saldo via
[`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
ou ative a [recarga automática](/api-reference/billing#update-auto-reload).
## Faça uma chamada com um agente salvo
O caminho mais simples — referencie um agente pelo ID:
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12
}'
```
Resposta:
```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` significa apenas que a solicitação foi aceita — a chamada
**ainda não está conectada**. Consulte
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
para obter o status em tempo real (`in_progress` → `completed` / `failed`).
## Faça uma chamada com configuração inline
Se você quiser um prompt pontual que não vale a pena salvar como agente,
passe `config` em vez disso. A estrutura corresponde ao esquema de resposta do
[`call.incoming` webhook](/pt/webhooks/call-incoming):
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155550199",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'
```
## Acompanhe a chamada
Em paralelo, assine o
[`telephony.complete` webhook](/pt/webhooks/events) —
a forma mais rápida de saber que uma chamada terminou. Se você não puder receber
webhooks de entrada, consulte `GET /v1/calls/{call_id}` a cada poucos segundos; o
registro inclui `end_reason`, `duration_seconds` e a URL da gravação
quando a chamada termina.
## Modos de falha que vale a pena tratar
| Erro | Correção |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required` | Adicione saldo ou ative a recarga automática |
| `403` saída bloqueada (número de demonstração) | Use um número VoIP |
| `403` saída bloqueada (VoIP não verificado) | Execute [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Confirme que o `from_number` corresponde a um número de telefone seu |
| `502 Bad Gateway` | Falha temporária de SIP / LiveKit; é seguro tentar novamente |
## Como controlar o tempo em espera
As chamadas realizadas que se prolongam porque quem atende demora para responder
(árvores de URA, filas) podem ser limitadas com `max_hold_seconds`:
```json theme={null}
{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12,
"max_hold_seconds": 120
}
```
O agente encerra a chamada se nenhum áudio humano for recebido nos últimos
N segundos. O padrão é 900 (15 minutos).
***
## Próximas etapas
Todos os campos de solicitação e códigos de erro.
Envie chamadas realizadas concluídas para o seu sistema.
Recarga automática para que chamadas realizadas nunca falhem por falta de saldo.
Faça um teste do seu agente de chamadas realizadas antes da produção.