Conceitos fundamentais

Um mapa de tudo na plataforma — o que cada objeto faz, onde ele fica no painel e qual API o utiliza.

ThunderPhone é uma plataforma completa para criar, executar e aprimorar agentes de voz com IA. Esta página é o mapa: todos os conceitos que você encontrará, cada um em uma seção curta, com a interface do dashboard e a API que a sustenta. Leia rapidamente uma vez e volte sempre que algum termo precisar de explicação.

A barra lateral do dashboard reflete esta estrutura:

Organizações#

Uma organização é a unidade de tenancy. 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 API sk_live_ criada em Organização → Chaves fica vinculada a uma organização. Esse vínculo torna a API REST tão direta: você nunca coloca um ID da organização nos caminhos de URL, porque 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 Minha conta, Geral, Chaves, Alertas, Configurações de faturamento e Histórico de faturamento. Consulte a referência de configurações da organização.

Na API: /v1/orgs, /v1/developer/api-keys.

Agentes#

Um agente é a configuração de IA que conduz uma chamada. Ele reúne:

• Um prompt que orienta o que o agente diz e como ele se comporta — incluindo ações de chamada, como transferências, pressionamento de teclas e encerramentos, que são linhas simples do prompt, e não uma configuração separada.
• Um nível de mecanismo (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 anexados: 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.

As edições no construtor são salvas automaticamente em um rascunho; nada entra em produção até você clicar em Implantar. Cada implantação é registrada em um snapshot na aba Histórico do construtor, para que você possa inspecionar e restaurar qualquer versão anterior.

No dashboard: Agentes de voz → o construtor de agentes (/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.

Vozes#

A biblioteca de vozes contém as vozes que um agente pode usar, suas amostras reproduzíveis, idiomas compatíveis, agrupamentos por gênero e sotaque e qualquer sobretaxa de voz ou idioma premium. Um recurso pago de teste pode sintetizar sua própria frase de 1 a 500 caracteres antes de você escolher.

Organizações elegíveis também podem criar vozes personalizadas a partir de uma pequena amostra em WAV ou MP3. As vozes personalizadas têm uma cota e um status de criação assíncrono; quando estiverem prontas, aparecerão no mesmo seletor de agentes das vozes da biblioteca.

No painel: Vozes (/dashboard/voices). Consulte Biblioteca de vozes e vozes personalizadas.

Na API: /v1/voices, amostras de voz e vozes personalizadas.

Números de telefone#

Um número de telefone pertence a uma organização e encaminha chamadas recebidas para um agente (além de poder realizar chamadas de saída). Há duas fontes:

• Números ThunderPhone — números reais dos EUA provisionados do pool do ThunderPhone, ativos em segundos, $1/mês mais uma sobretaxa de 1¢/minuto. Eles 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, e os números aprovados podem fazer chamadas e executar campanhas. Por padrão, uma organização pode ter 25 números.
• Números VoIP — trazidos do seu próprio provedor por meio de uma conexão VoIP. Twilio e Telnyx se conectam diretamente com uma chave de API (a Telnyx também oferece uma configuração guiada para novas contas); SignalWire, Vonage, Plivo e qualquer outro tronco SIP se conectam por meio da configuração SIP, uma configuração manual de SIP. Depois de importados e verificados, os números VoIP oferecem suporte a chamadas recebidas e de saída.

Cada linha de número permite definir um modo de roteamento, escolher o agente de chamadas recebidas e rotular o número.

No painel: Números de telefone (/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 se torna um registro de chamada. Uma chamada contém a transcrição completa com identificação de função, o histórico estruturado de turnos (incluindo chamadas de ferramentas), uma gravação, o total de cobrança e relatórios opcionais de avaliação por IA e de problemas.

Enquanto uma chamada está ao vivo, você pode abri-la e ouvir em tempo real — você entra silenciosamente, e ninguém na chamada escuta você. Depois de começar a ouvir, você pode sussurrar: digite uma instrução que vai diretamente para seu agente durante a chamada; quem liga nunca a escuta, e o agente a segue em tempo real.

No painel: Histórico de chamadas (/dashboard/call-history) para o arquivo e os detalhes por chamada; Ao vivo para chamadas em andamento. Consulte Revisar, ouvir e orientar suas chamadas.

Na API: /v1/calls — lista, transcrição, histórico, áudio, avaliação, exportação; /v1/issue-reports.

Portais de clientes#

Um portal de clientes é uma visualização de histórico de chamadas de somente leitura e com marca para um cliente externo. Os administradores da organização escolhem os agentes cujas chamadas aparecem, adicionam e-mails de visualizadores aprovados, enviam um logotipo e uma cor de destaque e, opcionalmente, verificam um domínio personalizado. Os visualizadores do portal podem inspecionar detalhes de chamadas, transcrições e gravações disponíveis sem receber acesso ao painel.

No painel: Portais de clientes (/dashboard/client-portals). Consulte Portais de clientes.

Na API: /v1/client-portals para a interface de gerenciamento de administradores.

Widgets da web#

O widget web oferece aos visitantes do seu site uma conversa com um agente por microfone — sem necessidade de número de telefone. Ele é autenticado com uma chave publicável (pk_live_...) que os navegadores só podem usar nos domínios permitidos por você, portanto é seguro em código do lado do cliente. A lista de domínios não é autenticação, e as configurações de sessão que uma página pode enviar ficam desativadas até que você as permita na chave.

As chaves operam em um de dois modos: agent (vinculada 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 do widget fluem pela mesma infraestrutura de chamadas usada nas 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 de widgets.

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, cole texto ou importe páginas da web por URL e, depois, vincule a base de conhecimento a um agente no builder. O agente a consulta com uma ferramenta de busca integrada sempre que a conversa exigir.

No dashboard: Conhecimento (/dashboard/knowledge) para a biblioteca de documentos; a seção Conhecimento do builder para vincular uma a um agente. Consulte Dar uma base de conhecimento ao seu agente.

Conexões#

As conexões permitem que os agentes alcancem 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, depois, ative ferramentas por operação (enviar uma mensagem no Slack, atualizar ou inserir um contato no HubSpot, agendar um horário no Cal.com…) para 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 faz 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 provedor para usar seus próprios números de telefone. Consulte Conectar um provedor VoIP.

O ThunderPhone também expõe seu próprio endpoint MCP para que um cliente MCP externo possa listar agentes, inspecionar chamadas e transcrições e realizar chamadas. Consulte Usar o ThunderPhone como servidor MCP.

Na API: /v1/integrations, /v1/mcp-servers 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, com reconhecimento de fuso horário), concorrência e política de tentativa (número máximo de tentativas e quais resultados — sem resposta, caixa postal, falha — serão tentados novamente). A campanha percorre a lista e registra cada chamada 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 área de supervisão: acompanhe um novo prompt recebendo seu primeiro tráfego real ou monitore uma campanha em andamento.

No painel: Ao vivo (/dashboard/live). Consulte Acompanhar e supervisionar chamadas ao vivo.

Simulações#

Uma simulação é uma pessoa que liga com 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) de publicar. Direcione-a para um agente ou 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ê solicitar) 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 informadas por cenário.

No painel: Simulações (/dashboard/simulations), além do botão Simulação no 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.

Conjuntos de validação#

Um conjunto de validação transforma momentos reais de chamadas em verificações de regressão repetíveis de turno único. Cada exemplo preserva o contexto da conversa, o áudio relevante de quem liga, a resposta original e o comportamento esperado. As reproduções são executadas no rascunho atual do agente sem realizar outra chamada, e a caixa de diálogo de publicação pode mostrar se a execução mais recente ainda corresponde a esse rascunho.

No painel: Conjuntos de validação (/dashboard/validation) para o conjunto de dados da organização e a aba Validação do criador de agentes para execuções. Consulte Conjuntos de validação.

Na API: /v1/validation-sets e os endpoints de reprodução de agente/exemplo na mesma página de referência.

Experimentos#

Um experimento realiza testes A/B de configurações de agentes em tráfego ao vivo: defina variantes (prompts, mecanismos ou configurações diferentes), distribua o tráfego entre elas e compare os resultados por variante. Use-o em vez de criar manualmente a lógica de segmentação em um webhook.

No painel: 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 uma pessoa revisora ou detectada pela avaliação de IA. Os problemas incluem gravidade, origem e status, e a página Problemas é a fila de triagem: filtre, inspecione a chamada com 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 ligou pediu para falar com uma pessoa na semana passada?") com uma análise elaborada por IA, limitada aos agentes e ao intervalo de datas que você escolher.

No painel: Relatórios (/dashboard/reports). Consulte Relatórios.

Observabilidade#

Observabilidade é a área de métricas: volume de chamadas, resultados e qualidade ao longo do tempo, filtráveis por agente e intervalo de tempo, 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ítes) em um intervalo de tempo e é acionada quando ela ultrapassa seu limite. As notificações são enviadas por e-mail e Slack e disparam um evento alert.triggered para seus endpoints de webhook.

No painel: Organização → Alertas. Consulte Alertas.

Webhooks#

O ThunderPhone envia webhooks HTTP POST ao seu servidor quando algo acontece durante e após uma chamada. Dois modelos de entrega:

• Endpoints de webhook (recomendado): gerencie várias URLs em /v1/developer/webhook-endpoints com segredos por endpoint e assinaturas de eventos por endpoint.
• Webhook legado de URL única: uma URL por organização. Gerenciado em /v1/webhook ou em Organização → Geral. Mantido para compatibilidade com versões anteriores.

Os eventos são divididos em duas classes:

• Eventos bloqueantes esperam que seu servidor responda com uma configuração que molda a chamada em andamento — os eventos de chamada recebida (telephony.incoming / web.incoming). Uma chamada telefônica espera até 13 segundos, incluindo uma tentativa, e uma sessão de widget espera 10 segundos. Não há agente de fallback: sem uma configuração utilizável, a chamada telefônica é encerrada e a sessão de widget falha.
• Eventos não bloqueantes são notificações disparadas sem aguardar resposta, repetidas com recuo exponencial — consulte semântica de entrega.

Cada solicitação inclui uma assinatura HMAC-SHA256 com carimbo de data e hora em X-ThunderPhone-Signature-V2, além da assinatura legada somente do corpo 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 uma 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 de 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ê habilita com linhas simples no prompt, em vez de definições de ferramenta.

No dashboard: 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 ⋯ em uma linha de membro altera funções ou remove alguém. O login único pode ser configurado para toda a organização — consulte SSO.

No dashboard: Organização → Geral. Consulte Convide sua equipe.

Na API: /v1/members, /v1/invites.

Faturamento#

O ThunderPhone é pré-pago. Cada organização mantém um saldo em USD; as chamadas debitam esse saldo conforme a taxa por minuto do agente (nível do mecanismo mais sobretaxas — o criador mostra a taxa total em tempo real conforme você altera as configurações, e idiomas adicionais selecionados adicionam 3¢/min). Quando o saldo chega a zero, chamadas recebidas são rejeitadas e chamadas realizadas retornam 402 Payment Required.

Adicione saldo manualmente ou habilite 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 caia no meio de uma frase.

No dashboard: Organização → Configurações de faturamento e Histórico de faturamento. Consulte Adicione saldo e ative a recarga automática, além da referência completa de preços.

Na API: /v1/billing.

O copiloto no aplicativo#

O dashboard 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 Pergunte ao copiloto no aplicativo.

Juntando tudo#