> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  Criando seu primeiro agente manualmente? O dashboard orienta este fluxo exato
  — criar o agente, adicionar um número, simular, revisar — com um
  assistente guiado. Comece pelo
  [início rápido do dashboard](/pt/quickstart-dashboard).
</Note>

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](/api-reference/agents) para ver todos os campos
de configuração; o mínimo é:

```bash theme={null}
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.

<Tip>
  Escolha `spark` para perguntas e respostas simples com o menor custo, ou `bolt` quando a velocidade
  for mais importante. Atualize 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).
</Tip>

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

```bash theme={null}
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
para acompanhar a transição, se necessário.

<Note>
  Para produção, ignore os números de demonstração e
  [traga seus próprios números via VoIP](/pt/guides/bring-your-own-numbers).
  Os números de demonstração aceitam apenas chamadas recebidas e têm volume limitado.
</Note>

## 3. Atribua o agente

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

```bash theme={null}
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`](/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 de gravação e uma avaliação de IA.

## 5. Inspecione os resultados

Busque a lista de chamadas recentes:

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Obtenha a transcrição:

```bash theme={null}
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 theme={null}
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`](/pt/webhooks/events),
receberá os mesmos dados como um POST para o seu servidor — consulte
[call.complete](/pt/webhooks/call-complete).

***

## Próximas etapas

<CardGroup cols={2}>
  <Card title="Configuração dinâmica por chamada" icon="bolt" href="/pt/guides/dynamic-call-config">
    Escolha um agente diferente para cada pessoa que liga com base no número de telefone ou
    em uma lógica personalizada em um webhook.
  </Card>

  <Card title="Adicionar integrações de ferramentas" icon="screwdriver-wrench" href="/pt/guides/build-tool-integration">
    Permita que o agente chame suas APIs durante a conversa.
  </Card>

  <Card title="Receber webhooks de call.complete" icon="bolt" href="/pt/webhooks/call-complete">
    Envie cada chamada concluída para seu pipeline de CRM / análise.
  </Card>

  <Card title="Avaliação por IA e relatórios de problemas" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Avalie automaticamente todas as chamadas e encaminhe as sinalizadas para revisão.
  </Card>
</CardGroup>