> ## 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.
# Início rápido (API)
> Atenda sua primeira chamada telefônica com um agente de IA em quatro chamadas REST.
Este guia mostra as quatro chamadas REST necessárias para atender
sua primeira chamada telefônica com um agente de IA.
Você precisará de uma [conta ThunderPhone](https://app.thunderphone.com).
O cadastro é gratuito e leva menos de um minuto. Prefere clicar a usar curl?
O [início rápido do dashboard](/pt/quickstart-dashboard) chega à mesma
primeira chamada sem escrever nenhum código.
## Etapa 1: Obtenha uma chave de API
Abra [app.thunderphone.com](https://app.thunderphone.com).
Acesse **Organização → Chaves** no dashboard.
Clique em **Criar chave**, dê um nome a ela e copie o valor
`sk_live_...`. A chave em texto simples é exibida **apenas uma vez** — armazene-a
imediatamente no seu gerenciador de segredos.
Com dificuldades? [Criar uma chave de API do servidor](/pt/guides/api-keys) explica
este fluxo em detalhes passo a passo, e o copiloto no app pode
destacar cada controle para você em tempo real.
Ao longo deste guia, substitua `sk_live_YOUR_API_KEY` pelo valor que você
acabou de copiar. A chave identifica sua organização automaticamente, portanto
você nunca precisa incluir um ID da organização nas URLs.
## Etapa 2: Crie um agente
Um agente define como a IA lida com conversas — prompt, voz,
nível de produto, ferramentas e elegibilidade para widget.
```bash cURL 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": "Customer Support",
"prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
"voice": "john",
"product": "spark"
}'
```
```python Python theme={null}
import os, requests
agent = requests.post(
"https://api.thunderphone.com/v1/agents",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={
"name": "Customer Support",
"prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
"voice": "john",
"product": "spark",
},
).json()
print("Agent id:", agent["id"])
```
```javascript Node.js theme={null}
const agent = await fetch("https://api.thunderphone.com/v1/agents", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Customer Support",
prompt: "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
voice: "john",
product: "spark",
}),
}).then((r) => r.json());
console.log("Agent id:", agent.id);
```
Níveis de produto: `spark` é otimizado para custo, `bolt` para velocidade e
`storm-base` / `storm-extra` para inteligência em prompts complexos. Consulte
[Agentes](/api-reference/agents#product-tiers-at-a-glance) para a comparação
completa.
## Etapa 3: Provisione um número de telefone
Esta chamada solicita um número ao pool de demonstração do ThunderPhone e atribui seu
novo agente como manipulador de entrada. (Para trazer seu próprio número de um provedor
de VoIP, consulte [conexões VoIP](/api-reference/voip-connections)
em vez disso.)
```bash cURL theme={null}
# First provision
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"}'
# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/ \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
```python Python theme={null}
number = requests.post(
"https://api.thunderphone.com/v1/phone-numbers",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={"area_code": "415"},
).json()
requests.patch(
f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])
```
Seu novo número começa em `status="provisioning"` e passa para
`active` em poucos segundos; quando você fechar o navegador, o
número estará pronto para receber chamadas.
## Etapa 4 (opcional): Configure um webhook
Para eventos em tempo real (roteamento dinâmico de chamadas, processamento pós-chamada), adicione
um endpoint de webhook. Assine apenas os eventos de que você precisa.
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Prod webhook",
"url": "https://your-server.com/thunderphone-webhook",
"events": ["telephony.incoming", "telephony.complete"]
}'
```
A resposta contém um `secret` de uso único — copie-o para seu gerenciador
de segredos. Use esse segredo para verificar o cabeçalho
`X-ThunderPhone-Signature` nas solicitações recebidas (consulte a
[visão geral de webhooks](/pt/webhooks/overview)).
## Etapa 5: Teste seu agente
Ligue para o número que você acabou de provisionar. O agente atende, se apresenta
e segue seu prompt.
Inspecione a chamada após seu término:
```bash theme={null}
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Acesse uma chamada específica para buscar a transcrição e a URL da gravação:
```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
***
## Próximas etapas
Permita que seu agente chame suas APIs durante uma conversa.
Dispare chamadas usando seu próprio código.
Reaja a eventos de chamada em tempo real.
Todos os endpoints públicos, documentados.