--- title: "Faça chamadas de saída (API)" description: "Acione 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 agendamento - Retornos de pesquisas - Acompanhamentos de "segunda tentativa" após uma chamada perdida - Notificações de despacho Vai ligar para uma lista inteira? O recurso [**Campanhas**](/pt/guides/outbound-campaigns) do dashboard (`/dashboard/campaigns`) recebe um CSV de contatos e gerencia janelas de chamadas com reconhecimento de fuso horário, concorrência e política de tentativas para você. Este guia aborda chamadas programáticas individuais. ## Pré-requisitos Use um número de sua propriedade por meio de uma [conexão VoIP](/api-reference/voip-connections) ou solicite permissão para usar seus números do ThunderPhone em chamadas de saída na página Números de telefone. Os números do ThunderPhone começam apenas para chamadas recebidas. O ThunderPhone analisa cada solicitação manualmente; após a aprovação, esses números podem realizar chamadas até o limite diário aprovado (redefinido às 00:00 UTC) e executar campanhas, e você pode solicitar um limite maior. Os números VoIP do cliente não têm limite diário, por isso recomendamos usá-los para chamadas de saída. Consulte [Use seus próprios números](/pt/guides/bring-your-own-numbers). Um prompt voltado para chamadas de saída tende a começar com o agente se identificando e explicando seu propósito — "Olá, aqui é a Acme ligando para confirmar seu compromisso 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 crédito ou ative a recarga automática em **Organização → Configurações de faturamento** no painel. Sua chave `sk_live_` pode verificar o saldo com [`GET /v1/billing`](/api-reference/billing#get-billing-account), mas não pode adicionar crédito nem alterar a recarga automática. ## Faça uma chamada com um agente salvo O caminho mais simples — referencie um agente por ID: ```bash 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": "+14155552671", "agent_id": 12 }' ``` Resposta: ```json { "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 ver 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 [webhook `call.incoming`](/pt/webhooks/call-incoming): ```bash 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": "+14155552671", "config": { "prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…", "voice": "john", "product": "spark" } }' ``` ## Acompanhe a chamada Em paralelo, assine o [webhook `telephony.complete`](/pt/webhooks/events) — a forma mais rápida de saber que uma chamada terminou. Se você não puder aceitar 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. Se o seu agente estiver configurado para extrair dados estruturados após a chamada, esses dados serão entregues separadamente após a conclusão da finalização. ### Passe variáveis por chamada para um agente salvo Agentes salvos podem usar placeholders como `{{name}}` ou `{{name|there}}` no texto do prompt. Ao iniciar uma chamada de saída com `agent_id`, passe `variables` com os valores dessa chamada: ```json { "from_number": "+[REDACTED_PHONE]", "to_number": "+[REDACTED_PHONE]", "agent_id": 12, "variables": { "name": "Jordan" } } ``` Use valores de string indexados pelo nome do placeholder. Essas variáveis se aplicam a agentes salvos; o exemplo de `config` em linha deste guia não as utiliza. ## Modos de falha que vale a pena tratar | Erro | Correção | |-------|-----| | `402 Payment Required` | Adicione saldo ou ative a recarga automática | | `400` com `code: destination_not_allowed` | O ThunderPhone não liga para esse número: números inválidos, números de emergência, números com tarifa premium, códigos curtos ou países sancionados. De números do ThunderPhone, apenas números comuns dos EUA e do Canadá (sem tarifa premium). `reason` informa qual é o caso; consulte [destinos bloqueados](/api-reference/outbound-calls#blocked-destinations) | | `409` com `retryable: false` para um número do ThunderPhone | Siga o `code`: solicite chamadas de saída na página Números de telefone, aguarde uma análise pendente ou use outro número qualificado | | `429` com `code: platform_outbound_daily_limit_reached` | A organização usou as chamadas de saída de hoje feitas de números do ThunderPhone. Aguarde `resets_at` (00:00 UTC), solicite um limite maior na página Números de telefone ou ligue de um número na sua própria conexão VoIP | | `429` com `code: concurrent_call_limit_reached` | A organização tem tantas chamadas em andamento quanto seu [limite de chamadas simultâneas](/api-reference/introduction#call-limits) (20 por padrão, contando chamadas de entrada, saída, web e de teste). Tente novamente após os segundos do cabeçalho `Retry-After` ou quando uma chamada terminar; envie um e-mail para support@thunderphone.com para aumentar o limite | | `429` com `code: same_number_too_soon` | Você ligou para o mesmo `to_number` há menos de 10 segundos. Tente novamente após os segundos do cabeçalho `Retry-After` | | `409` com `retryable: false` para um número VoIP de cliente | Corrija o estado indicado por `code`; em caso de falhas de verificação, execute [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) | | conflito de idempotência `409` | Reutilize a chave apenas com a solicitação normalizada original ou envie uma nova chave | | `404 from_number is not registered to this organization` | Confirme que `from_number` corresponde a um número de telefone ativo na sua organização. Um número que já está sendo provisionado, falhou, está em liberação ou foi liberado também retorna essa resposta | | `500` apenas com um campo `detail` | Nenhum tronco de saída está configurado. Entre em contato com o suporte; este não é um problema de estado do número que você possa corrigir | | `502 Bad Gateway` | Falha transitória de SIP / LiveKit; é seguro tentar novamente | Consulte a [referência de chamadas de saída](/api-reference/outbound-calls#error-responses) para ver a lista completa e estável de códigos de elegibilidade e os dois formatos de resposta `409`. Se um número ativo se tornar inelegível após a solicitação ser aceita, mas antes de a chamada ser iniciada, a verificação final retornará o payload `409` não repetível. ## Como controlar o tempo de espera Chamadas de saída que demoram porque a pessoa chamada demora a responder (árvores de URA, filas) podem ser limitadas com `max_hold_seconds`: ```json { "from_number": "+15551234567", "to_number": "+14155552671", "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 segundos (15 minutos). --- ## Próximas etapas Todos os campos de solicitação e códigos de erro. Transmita chamadas de saída concluídas para o seu sistema. Use a recarga automática para que chamadas de saída nunca falhem por falta de saldo. Faça um teste do seu agente de saída antes da produção.