Início rápido (API)

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. O cadastro é gratuito e leva menos de um minuto. Prefere clicar a usar curl? O início rápido do dashboard chega à mesma primeira chamada sem escrever nenhum código.

Etapa 1: Obtenha uma chave de API

Entrar

Abra app.thunderphone.com.

Navegue até Chaves

Acesse Organização → Chaves no dashboard.

Crie uma chave

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

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"
  }'

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"])

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 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 em vez disso.)

# 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/<id-from-previous> \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

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.

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

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:

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:

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

Adicionar ferramentas de função

Permita que seu agente chame suas APIs durante uma conversa.

Fazer chamadas de saída

Dispare chamadas usando seu próprio código.

Processar webhooks

Reaja a eventos de chamada em tempo real.

Referência completa da API

Todos os endpoints públicos, documentados.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Etapa 1: Obtenha uma chave de API

Etapa 2: Crie um agente

Etapa 3: Provisione um número de telefone

Etapa 4 (opcional): Configure um webhook

Etapa 5: Teste seu agente

Próximas etapas

Adicionar ferramentas de função

Fazer chamadas de saída

Processar webhooks

Referência completa da API

​Etapa 1: Obtenha uma chave de API

​Etapa 2: Crie um agente

​Etapa 3: Provisione um número de telefone

​Etapa 4 (opcional): Configure um webhook

​Etapa 5: Teste seu agente

​Próximas etapas

Adicionar ferramentas de função

Fazer chamadas de saída

Processar webhooks

Referência completa da API

Etapa 1: Obtenha uma chave de API

Etapa 2: Crie um agente

Etapa 3: Provisione um número de telefone

Etapa 4 (opcional): Configure um webhook

Etapa 5: Teste seu agente

Próximas etapas