Developer cookbook

Gerenciar chamadas recebidas (API)

De ponta a ponta: configure um agente, atribua-o a um número de telefone, atenda uma chamada e analise a transcrição.

O fluxo canônico de "atender um telefone com uma IA", pelo seu terminal. Você vai:

1. Criar um agente com um prompt e uma voz.
2. Provisionar (ou trazer) um número de telefone e atribuir o agente como seu atendente de chamadas recebidas.
3. Ligar para o número. Observe o registro da chamada, a transcrição e a gravação.

Total de chamadas à API: quatro. Tempo total: menos de cinco minutos.

1. Crie um agente#

Um agente reúne o prompt, a voz e o nível de produto que conduzirão a chamada. Consulte Agentes para ver todos os campos de configuração; o mínimo é:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Salve o id retornado — você precisará dele na etapa 2.

2. Obtenha um número de telefone#

Se você só precisa de algo para testar ligando, provisione um número de demonstração do pool do ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

A resposta inclui um id e um number no formato E.164. Os números de demonstração começam com status="provisioning" e se tornam active em poucos segundos — consulte GET /v1/phone-numbers/{id} para acompanhar a transição, se necessário.

3. Atribua o agente#

Associe o agente da etapa 1 à direção de chamadas recebidas do número:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Pronto — o número está ativo. Você também pode definir outbound_agent_id no mesmo PATCH para que o número também esteja pronto para realizar chamadas.

4. Atenda uma chamada#

Ligue para o número pelo seu telefone. O agente atende, se apresenta conforme o seu prompt e a conversa começa.

Enquanto a chamada está em andamento, ela aparece em GET /v1/calls com status="in_progress". Quando termina, o registro é atualizado com end_reason, duration_seconds, billable_minutes e, posteriormente, uma URL de gravação e uma avaliação de IA.

5. Inspecione os resultados#

Busque a lista de chamadas recentes:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Obtenha a transcrição:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

E a URL da gravação (temporária e assinada):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Se você tiver assinado o webhook telephony.complete, receberá os mesmos dados como um POST para o seu servidor — consulte call.complete.

Próximas etapas#