Getting Started

Conceitos fundamentais

Um mapa de tudo na plataforma — o que cada objeto faz, onde 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á, um breve tópico para cada um, com a interface do painel e a API que o sustenta. Leia rapidamente uma vez e volte sempre que precisar entender melhor um termo.

A barra lateral do painel reflete esta estrutura:

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 API sk_live_ criada em Organização → Chaves fica vinculada a uma organização. Esse vínculo torna a API REST tão simples: você nunca insere um ID de organização nos caminhos de URL, porque sua chave já a identifica.

No painel: 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 das configurações da organização.

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

Agentes#

Um agente é a configuração de IA que executa 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 teclas e desligamentos, que são linhas simples do prompt, e não configurações separadas.
• 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 em linha.
• Ajustes de comportamento: ordem de fala, modo de confirmação, trilha de fundo, tempo limite de espera.

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

No painel: 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, além de qualquer cobrança adicional por voz ou idioma premium. Um recurso de teste pago pode sintetizar sua própria frase de 1 a 500 caracteres antes da escolha.

Organizações qualificadas também podem criar vozes personalizadas a partir de uma curta amostra em WAV ou MP3. As vozes personalizadas têm uma cota e status de criação assíncrono; quando ficam prontas, aparecem no mesmo seletor de agentes que as 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 direciona chamadas de entrada para um agente (e pode realizar chamadas de saída). Há duas origens:

• Números de demonstração — números reais dos EUA provisionados do pool do ThunderPhone, ativos em segundos. Apenas para chamadas de entrada, eles atendem com um breve aviso falado, e o painel limita cada 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 se conectam diretamente (a Telnyx tem uma configuração guiada); SignalWire e Vonage estarão disponíveis em breve — atualmente, você pode acessá-los por meio da configuração manual de SIP, que aceita qualquer tronco SIP. Depois de importados e verificados, os números VoIP oferecem suporte a chamadas de entrada e de saída.

Cada linha de número permite definir um modo de roteamento, escolher o agente de entrada e adicionar um rótulo ao 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 de entrada, chamada de saída, simulação e sessão de widget se torna um registro de chamada. Uma chamada inclui a transcrição completa identificada por função, o histórico estruturado de turnos (incluindo chamadas de ferramenta), uma gravação, o total de cobrança e relatórios opcionais de avaliação e problemas por IA.

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

No painel: 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, avaliação, exportação; /v1/issue-reports.

Portais de clientes#

Um portal de cliente é uma visualização de histórico de chamadas de marca própria e somente leitura 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 das 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 administrativo.

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 é autenticado com uma chave publicável (pk_live_...) vinculada à origem dos seus domínios permitidos, portanto é seguro em código do lado do cliente.

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 passam pela mesma infraestrutura de chamadas das ligações telefônicas.

No painel: 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 Crie 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 a chamada para fundamentar suas respostas — envie arquivos, cole texto ou importe páginas da web por URL e associe a base de conhecimento a um agente no builder. O agente a consulta com uma ferramenta de pesquisa integrada sempre que a conversa exigir.

No painel: Conhecimento (/dashboard/knowledge) para a biblioteca de documentos; a seção Conhecimento do builder para associar uma a um agente. Consulte Forneça 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:

• Aplicativos (/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, criar ou atualizar um contato no HubSpot, agendar um horário no Cal.com…) para qualquer agente. Consulte Conecte aplicativos.
• APIs (/dashboard/api-connections) — transforme qualquer API HTTP em uma ação de 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 realiza uma chamada de sandbox antes da implantação. Consulte Conexões de API — a interface no painel 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 Adicione um servidor MCP.
• VoIP (/dashboard/voip-connections) — credenciais de provedor para usar seus próprios números de telefone. Consulte Conecte 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 Use o ThunderPhone como um servidor MCP.

Na API: /v1/integrations, /v1/mcp-servers e /v1/voip-connections; consulte também Crie 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 tentativas (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 painel: Campanhas (/dashboard/campaigns). Consulte Execute 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 — mesma rota de telefonia, transcrição real, avaliação real — para que você possa testar antes (e depois) de publicar. Direcione-a a um agente ou 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 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 na CI; regressões em relação à linha de base aceita são relatadas 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 na versão atual do agente sem fazer outra chamada, e a caixa de diálogo de publicação pode mostrar se a execução mais recente ainda corresponde a essa versão.

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 no tráfego ao vivo: 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 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 por 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 seus dados de 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 escrita 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 janela 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íte) em uma janela de tempo e é acionada quando ela ultrapassa seu limite. As notificações são enviadas por e-mail e Slack, e acionam 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). 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 sem confirmação, repetidas com recuo exponencial — consulte semântica de entrega.

Cada solicitação inclui uma assinatura HMAC-SHA256 em 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 e uma URL de endpoint; o agente decide quando chamá-la, 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 de chamada integrados — 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 ferramenta.

No painel: a seção Conexões de API do construtor (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 painel: 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 o debitam pela tarifa por minuto do agente (nível do mecanismo mais sobretaxas — o construtor mostra a tarifa total em tempo real à medida que você altera as configurações, e idiomas adicionais selecionados adicionam 3¢/min). Quando o saldo chega a zero, as chamadas recebidas são rejeitadas e as chamadas feitas retornam 402 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 caia no meio de uma frase.

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

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 maneira mais rápida de encontrar um controle mencionado nesta página. Consulte Pergunte ao copiloto no aplicativo.

Juntando tudo#