Gerenciar chamadas recebidas (API)

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

O fluxo canônico de “atender um telefone com uma IA”, pelo 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 responsável pelas chamadas recebidas.
3. Ligar para o número. Observar o registro da chamada, a transcrição e a gravação.

Total de chamadas de 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. Você também pode definir limites de chamada, como max_call_duration_seconds e ring_duration_seconds, no agente. Os agentes também oferecem suporte a intro_clip e intro_ring_count para reproduzir uma introdução pré-gravada e até dois toques antes de o agente falar. Novos agentes também precisam de um fuso horário. Se o seu agente for multilíngue, você poderá definir language_switching para controlar se ele pergunta antes de alternar idiomas ou segue o idioma de quem liga. 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 ligar, obtenha um número ThunderPhone 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 do ThunderPhone começam com status="provisioning" e ficam active em alguns segundos — consulte periodicamente 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 entrada 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. Depois que as chamadas de saída forem aprovadas para sua organização, você também poderá definir outbound_agent_id no mesmo PATCH. Até lá, a API rejeita essa atribuição com 400.

Se você encaminhar chamadas recebidas por meio de um webhook de configuração em vez de um inbound_agent_id fixo, esse webhook agora poderá retornar um timezone por chamada junto com agent_id e variables.

4. Faça uma chamada#

Ligue para o número usando seu telefone. O agente atende, se apresenta conforme 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 da gravação e uma avaliação por IA.

As chamadas recebidas contam para o limite de chamadas simultâneas da sua organização (20 chamadas em andamento por padrão, compartilhadas com chamadas de saída, web e de teste). Uma chamada que chega quando o limite foi atingido é recusada antes que o agente atenda e é encerrada, não é cobrada e é registrada como uma chamada com falha com o motivo de encerramento concurrent_call_limit_reached. Envie um e-mail para support@thunderphone.com se você precisar de um limite maior.

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ê se inscreveu no webhook telephony.complete, receberá os mesmos dados como um POST no seu servidor — consulte call.complete.

Se o seu agente tiver campos de extração configurados, o payload da chamada concluída também poderá incluir dados extraídos estruturados.

Próximas etapas#