Fundamentos
Engajamento
Monitoramento ao vivo e
campanhas de saída.
Conexões
Apps, APIs, servidores MCP e provedores de VoIP que seus
agentes podem usar.
Qualidade e testes
Organização
Eventos
Webhooks e ferramentas de função para
seu próprio código.
Organizações
Uma organização é a unidade de locação. Todos os outros recursos — agentes, números de telefone, chamadas, chaves — pertencem a exatamente uma organização. Sua conta pode pertencer a várias organizações; cada uma tem seu próprio saldo, suas próprias chaves e sua própria lista de membros. A chave de APIsk_live_ criada em Organização → Chaves fica
vinculada a uma organização. Esse vínculo torna a API REST tão
direta: você nunca inclui um ID de organização nos caminhos de URL, pois sua chave já
a identifica.
No dashboard: o seletor de organização (no rodapé da barra lateral) e
as configurações de Organização — abas para Geral, Chaves, Alertas, Configurações
de faturamento e Histórico de faturamento.
Na API: /v1/orgs,
/v1/developer/api-keys.
Agentes
Um agente é a configuração de IA que opera uma chamada. Ele reúne:- Um prompt que determina o que o agente diz e como ele se comporta — incluindo ações de chamada, como transferências, pressionamentos de teclado e encerramentos, que são linhas simples do prompt, não uma configuração separada.
- Um nível de engine (
spark,bolt,storm-*): Spark é otimizado para custo, Bolt para velocidade e Storm para inteligência em prompts complexos. - Uma voz, além de um idioma principal e idiomas adicionais opcionais — o agente alterna automaticamente quando quem liga muda de idioma. Consulte Idiomas compatíveis.
- Recursos conectados: apps conectados, conexões de API, bases de conhecimento, servidores MCP e ferramentas de função integradas.
- Ajustes de comportamento: ordem de fala, modo de confirmação, faixa de fundo, tempo limite de espera.
/dashboard/agents). Consulte
Crie seu primeiro agente de voz.
Na API: /v1/agents — CRUD,
duplicação, transferência, histórico de versões e auxiliares de prompt.
Números de telefone
Um número de telefone pertence a uma organização e direciona chamadas recebidas para um agente (e pode realizar chamadas de saída). Duas fontes:- Números de demonstração — números reais dos EUA provisionados do pool do ThunderPhone, ativos em segundos. Apenas para chamadas recebidas, eles atendem com um breve aviso falado, e o dashboard limita uma organização a 10 deles. Perfeitos para um primeiro teste; não para produção.
- Números VoIP — trazidos do seu próprio provedor por meio de uma conexão VoIP. Twilio e Telnyx conectam-se diretamente (a Telnyx tem uma configuração guiada); SignalWire e Vonage estarão disponíveis em breve — hoje você pode acessá-los por meio de configuração manual de SIP, que aceita qualquer tronco SIP. Depois de importados e verificados, os números VoIP oferecem suporte a chamadas recebidas e de saída.
/dashboard/phone-numbers).
Consulte Obter um número de telefone.
Na API: /v1/phone-numbers,
/v1/voip-connections,
/v1/phone-number-labels.
Chamadas
Cada chamada recebida, chamada de saída, simulação e sessão de widget torna-se um registro de chamada. Uma chamada contém a transcrição completa com funções identificadas, o histórico estruturado de turnos (incluindo chamadas de ferramentas), uma gravação, o total de cobrança e classificações de IA e relatórios de problemas opcionais. Enquanto uma chamada está ao vivo, você pode abri-la e Ouvir chamada — você entra silenciosamente, e ninguém na chamada ouve você. Depois de ouvir, você pode sussurrar: digite uma instrução que vai diretamente para seu agente durante a chamada; quem liga nunca a ouve, e o agente a segue ao vivo. No dashboard: Histórico de chamadas (/dashboard/call-history) para
o arquivo e os detalhes de cada chamada; Ao vivo para chamadas em andamento. Consulte
Revisar, ouvir e orientar suas chamadas.
Na API: /v1/calls — lista, transcrição,
histórico, áudio, classificação, exportação;
/v1/issue-reports.
Widgets da Web
O widget da Web oferece aos visitantes do seu site uma conversa baseada em microfone com um agente — sem necessidade de número de telefone. Ele autentica com uma chave publicável (pk_live_...) vinculada por origem aos seus
domínios permitidos, portanto é segura em código do lado do cliente.
As chaves operam em um de dois modos: agent (vinculado estaticamente a um agente)
ou webhook (seu servidor escolhe a configuração para cada visitante — consulte
Configuração dinâmica por chamada). As sessões de widget
usam a mesma infraestrutura de chamadas que as chamadas telefônicas.
No dashboard: Widgets da Web (/dashboard/web-widgets) —
crie widgets, defina o modo e o agente, gerencie domínios permitidos e
copie o snippet de incorporação. Consulte
Criar um widget da Web.
Na API: /v1/publishable-key,
/v1/mic-session e a
documentação do SDK do Widget.
Bases de conhecimento
Uma base de conhecimento é um conjunto de documentos que seu agente pode pesquisar durante uma chamada para fundamentar suas respostas — envie arquivos diretamente ou importe do Google Drive e, depois, anexe a base de conhecimento a um agente no builder. O agente a consulta com uma ferramenta de pesquisa integrada sempre que a conversa exige isso. No dashboard: Conhecimento (/dashboard/knowledge) para a
biblioteca de documentos; a seção Conhecimento do builder para anexar uma a
um agente. Consulte
Dar uma base de conhecimento ao seu agente.
Conexões
As conexões são como os agentes alcançam o mundo externo. Quatro tipos, um grupo na barra lateral:- Apps (
/dashboard/app-connections) — conexões OAuth com Slack, HubSpot, Salesforce, Google Calendar, Google Sheets e Cal.com. Conecte uma vez e ative ferramentas por operação (enviar uma mensagem no Slack, criar ou atualizar um contato no HubSpot, agendar um horário no Cal.com…) em qualquer agente. Consulte Conectar apps. - APIs (
/dashboard/api-connections) — transforme qualquer API HTTP em uma ação do agente. Cole um comando cURL e o assistente de IA cria um rascunho da definição da ferramenta, ou crie-a manualmente; um botão Testar solicitação envia uma chamada de sandbox antes da publicação. Consulte Conexões de API — a interface no dashboard de/v1/integrations. - MCP (
/dashboard/mcp-connections) — adicione um servidor Model Context Protocol por URL e permita que o agente use as ferramentas que ele expõe. Consulte Adicionar um servidor MCP. - VoIP (
/dashboard/voip-connections) — credenciais de provedores para usar seus próprios números de telefone. Consulte Conectar um provedor de VoIP.
/v1/integrations e
/v1/voip-connections; consulte também
Criar uma integração de ferramenta.
Campanhas
Uma campanha realiza chamadas de saída em escala: envie um CSV de contatos, escolha o agente e o número de origem e defina a janela de chamadas (dias e horários, considerando o fuso horário), a concorrência e a política de tentativas (máximo de tentativas e quais resultados — sem resposta, caixa postal, falha — recebem nova tentativa). A campanha percorre a lista e registra todas as chamadas no Histórico de chamadas. No dashboard: Campanhas (/dashboard/campaigns). Consulte
Executar uma campanha de chamadas de saída.
Para chamadas programáticas pontuais: a
API de chamadas de saída.
Monitoramento ao vivo
Ao vivo mostra todas as chamadas em andamento na organização e permite abrir qualquer uma delas para ouvir e sussurrar em tempo real. É a superfície de supervisão: acompanhe um novo prompt recebendo seu primeiro tráfego real ou monitore uma campanha em execução. No dashboard: Ao vivo (/dashboard/live). Consulte
Acompanhar e supervisionar chamadas ao vivo.
Simulações
Uma simulação é uma pessoa que liga gerada por IA tendo uma conversa real com seu agente — mesmo caminho de telefonia, transcrição real, avaliação real — para que você possa testar antes (e depois) da publicação. Direcione-a a um agente ou a um número de telefone, escreva você mesmo o cenário de quem liga ou gere cenários com IA a partir do prompt do agente (incluindo casos extremos, se você pedir) e acompanhe a chamada ao vivo. Os cenários são agrupados em suítes, que definem uma taxa mínima de aprovação e podem bloquear lançamentos no CI; regressões em relação à linha de base aceita são reportadas por cenário. No dashboard: Simulações (/dashboard/simulations), além do
botão Simulação dentro do criador de agentes. Consulte
Simular uma chamada.
Na API: /v1/test-calls e o
executor de suítes — consulte Testar um agente de ponta a ponta.
Experimentos
Um experimento testa A/B configurações de agentes em tráfego real: defina variantes (prompts, mecanismos ou configurações diferentes), divida o tráfego entre elas e compare os resultados por variante. Use-o em vez de implementar manualmente a lógica de agrupamento em um webhook. No dashboard: Experimentos (/dashboard/experiments) e a
aba A/B no criador de agentes. Consulte
Experimentos (testes A/B).
Problemas
Um problema é uma ocorrência sinalizada em uma chamada específica — registrada por um revisor humano ou detectada pela avaliação por IA. Os problemas incluem gravidade, origem e status, e a página Problemas é a fila de triagem: filtre, inspecione a chamada com o problema e acompanhe as correções. No painel: Problemas (/dashboard/issues), além da
sinalização por chamada no Histórico de chamadas. Consulte Triagem de problemas.
Na API: /v1/issue-reports.
Relatórios
Um relatório responde a uma pergunta em linguagem natural sobre os dados das suas chamadas (“Quais foram os três principais motivos pelos quais quem liga pediu para falar com uma pessoa na semana passada?”) com uma análise escrita por IA, limitada aos agentes e ao intervalo de datas que você escolher. No painel: Relatórios (/dashboard/reports). Consulte
Relatórios.
Observabilidade
A observabilidade é a área de métricas: volume de chamadas, resultados e qualidade ao longo do tempo, filtrável por agente e período, com exportação para análises posteriores. No painel: Observabilidade (/dashboard/observability).
Consulte Observabilidade.
Alertas
Uma regra de alerta monitora uma métrica (taxa de sucesso, taxa de falha, pontuação média, volume de chamadas, regressões de suíte) durante um período e é acionada quando ela ultrapassa seu limite. As notificações são enviadas por e-mail e Slack, e acionam um eventoalert.triggered para seus
endpoints de webhook.
No painel: Organização → Alertas. Consulte
Alertas.
Webhooks
O ThunderPhone envia webhooks HTTP POST ao seu servidor quando eventos ocorrem durante e após uma chamada. Há dois modelos de entrega:- Endpoints de webhook (recomendado): gerencie várias URLs em
/v1/developer/webhook-endpointscom segredos por endpoint e assinaturas de eventos por endpoint. - Webhook legado de URL única: uma URL por organização. Gerenciado em
/v1/webhookou em Organização → Geral. Mantido para compatibilidade retroativa.
- Eventos bloqueantes esperam que seu servidor responda com uma configuração
que define a chamada em andamento — os
eventos de chamada recebida
(
telephony.incoming/web.incoming). Você tem até 10 segundos para responder; em caso de tempo limite, o agente atribuído estaticamente atende a chamada. - Eventos não bloqueantes são notificações de disparo único, repetidas com recuo exponencial — consulte semântica de entrega.
X-ThunderPhone-Signature. Consulte
Verificação de assinatura.
Ferramentas de função
Uma ferramenta de função é um endpoint HTTP que seu agente pode chamar durante a conversa. Você fornece ao ThunderPhone um esquema de função no estilo OpenAI junto com uma URL de endpoint; o agente decide quando chamá-lo, e o ThunderPhone faz a solicitação HTTP assinada a partir dos seus servidores e entrega o resultado de volta ao agente. Os agentes também incluem recursos integrados de chamada — transferir a chamada, enviar entrada pelo teclado (DTMF), encerrar a chamada, aguardar em espera — que você ativa com linhas simples no prompt, em vez de definições de ferramentas. No painel: a seção Conexões de API do criador (consulte Conexões). Na API:/v1/integrations e
a especificação de Ferramentas de função.
Equipe e funções
Cada organização tem uma lista de membros com duas funções: Membros criam e operam agentes; Administradores também gerenciam a equipe e o faturamento. Convide por e-mail — os convites expiram após 7 dias e podem ser revogados; o menu ⋯ na linha de um membro altera funções ou remove alguém. O login único pode ser configurado para toda a organização — consulte SSO. No painel: Organização → Geral. Consulte Convide sua equipe. Na API:/v1/members,
/v1/invites.
Cobrança
O ThunderPhone é pré-pago. Cada organização mantém um saldo em USD; as chamadas o debitam pela tarifa por minuto do agente (nível do mecanismo mais sobretaxas — o criador mostra a tarifa total em tempo real conforme você altera as configurações, e idiomas premium adicionam 2¢/min). Quando o saldo chega a zero, chamadas recebidas são rejeitadas e chamadas feitas retornam402 Payment Required.
Adicione saldo manualmente ou ative a recarga automática com um limite de saldo, um
valor de recarga e um limite mensal de gastos opcional — para que uma chamada
nunca seja interrompida no meio de uma frase.
No painel: Organização → Configurações de cobrança e
Histórico de cobrança. Consulte
Adicionar saldo e ativar a recarga automática.
Na API: /v1/billing.
O copiloto no aplicativo
O painel inclui um copiloto integrado — pergunte a ele “como faço X” e ele responde com base nesta documentação, oferece tours passo a passo que destacam os controles reais e pode reproduzir qualquer um dos tours guiados. É a forma mais rápida de encontrar um controle mencionado nesta página. Consulte Perguntar ao copiloto no aplicativo.Juntando tudo
Início rápido pelo painel
O assistente de cinco etapas: agente → cobrança → número → simulação → revisão.
Início rápido pela API
A mesma primeira chamada em quatro chamadas REST.
Usando o painel
Crie um agente, adicione saldo, obtenha um número, simule e revise chamadas.
Conectar ferramentas e dados
Aplicativos OAuth, APIs personalizadas, servidores MCP e provedores de VoIP.
Analisar e melhorar
Relatórios, observabilidade, experimentos, problemas e alertas.
Equipe e conta
Convites e funções, chaves de API, segurança e SSO.
Livro de receitas para desenvolvedores
As receitas da API: chamadas recebidas, chamadas feitas, configuração dinâmica, ferramentas e testes.
Verificar assinaturas de webhook
Faça a verificação de HMAC corretamente uma vez e reutilize-a em todos os lugares.