Faça chamadas de saída (API)

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

Pré-requisitos#

1. Escolha um número habilitado para chamadas de saída

   Use um número de sua propriedade por meio de uma conexão VoIP 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.

2. Crie um agente

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

3. Mantenha um saldo positivo

   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, 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:

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:

{ "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 webhook call.incoming:

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

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

Consulte a referência de chamadas de saída 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:

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