Developer cookbook

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

Pré-requisitos#

1. Tenha um número VoIP

   As chamadas de saída exigem que você seja proprietário do from_number por meio de uma conexão VoIP. Números de demonstração aceitam apenas chamadas recebidas. Consulte Use seus próprios números.

2. Crie um agente

   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).

3. Mantenha um saldo positivo

   Chamadas de saída retornam 402 Payment Required se o saldo for ≤ $0.00. Adicione saldo via POST /v1/billing/top-up ou ative a recarga automática.

Faça uma chamada com um agente salvo#

O caminho mais simples — referencie um agente pelo ID:

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:

{ "call_id": 987654321, "status": "initiated" }

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:

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 — 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#

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:

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