---
title: "Gerenciar chamadas recebidas (API)"
description: "De ponta a ponta: configure um agente, atribua-o a um número de telefone, atenda uma chamada e inspecione a transcrição."
---
Vai criar seu primeiro agente manualmente? O painel orienta você por este fluxo
exato — criar o agente, adicionar um número, simular, revisar — com um
assistente guiado. Comece pelo
[início rápido do painel](/pt/quickstart-dashboard).
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](/api-reference/agents) para ver todos os campos de configuração; o
mínimo é:
```bash
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.
Escolha `spark` para perguntas e respostas simples com o menor custo, ou `bolt` quando
a velocidade for o mais importante. Mude para `storm-base-with-ack` quando seu prompt
precisar de raciocínio mais profundo e puder tolerar um preenchimento de meio segundo enquanto
o modelo pensa. Consulte os
[níveis de produto](/api-reference/agents#product-tiers-at-a-glance).
## 2. Obtenha um número de telefone
Se você só precisa de algo para ligar, obtenha um número ThunderPhone
do pool do ThunderPhone:
```bash
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
para acompanhar a transição, se necessário.
Os números do ThunderPhone começam apenas para chamadas recebidas. Um administrador da organização pode solicitar
chamadas de saída na página Números de telefone. O ThunderPhone analisa cada
solicitação manualmente; após a aprovação, os números podem fazer chamadas e executar
campanhas. Os números VoIP dos clientes não mudam.
## 3. Atribua o agente
Associe o agente da etapa 1 à direção de entrada do número:
```bash
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`](/api-reference/calls#list-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](/api-reference/introduction#call-limits) 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:
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Obtenha a transcrição:
```bash
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):
```bash
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`](/pt/webhooks/events),
receberá os mesmos dados como um POST no seu servidor — consulte
[call.complete](/pt/webhooks/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
Escolha um agente diferente para cada pessoa que liga com base no número de telefone ou
em lógica personalizada em um webhook.
Permita que o agente chame suas APIs durante a conversa.
Encaminhe quem liga diretamente ou faça a triagem do destino antes de conectá-lo.
Envie cada chamada concluída para seu pipeline de CRM/análises.
Avalie cada chamada automaticamente e encaminhe as sinalizadas para revisão.