--- title: "Conceitos fundamentais" description: "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: [Agentes](#agents), [vozes](#voices), [números de telefone](#phone-numbers), [widgets da web](#web-widgets), [chamadas](#calls), [portais de clientes](#client-portals), [bases de conhecimento](#knowledge-bases). [Monitoramento ao vivo](#live-monitoring) e [campanhas](#campaigns) de saída. [Apps, APIs, servidores MCP e provedores de VoIP](#connections) que seus agentes podem usar. [Simulações](#simulations), [conjuntos de validação](#validation-sets), [experimentos](#experiments), [problemas](#issues), [relatórios](#reports), [observabilidade](#observability). [Equipe e funções](#team-and-roles), [chaves de API](#organizations), [alertas](#alerts), [faturamento](#billing). [Webhooks](#webhooks) e [ferramentas de função](#function-tools) para seu próprio código. --- ## 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](/pt/guides/organization-settings). **Na API:** [`/v1/orgs`](/api-reference/organizations), [`/v1/developer/api-keys`](/api-reference/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](/pt/guides/supported-languages). - Recursos anexados: [apps conectados](#connections), [conexões de API](#connections), [bases de conhecimento](#knowledge-bases), [servidores MCP](#connections) e [ferramentas de função](#function-tools) 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](/pt/guides/build-an-agent). **Na API:** [`/v1/agents`](/api-reference/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](/pt/guides/voice-library). **Na API:** [`/v1/voices`](/api-reference/voices), [amostras de voz](/api-reference/voice-samples) e [vozes personalizadas](/api-reference/custom-voices). --- ## 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, {/* rate:phone */}$1/mês mais uma sobretaxa de 1¢/minuto{/* /rate */}. 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](#connections). 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](/pt/guides/get-a-phone-number). **Na API:** [`/v1/phone-numbers`](/api-reference/phone-numbers), [`/v1/voip-connections`](/api-reference/voip-connections), [`/v1/phone-number-labels`](/api-reference/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](/pt/guides/review-calls). **Na API:** [`/v1/calls`](/api-reference/calls) — lista, transcrição, histórico, áudio, avaliação, exportação; [`/v1/issue-reports`](/api-reference/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](/pt/guides/client-portals). **Na API:** [`/v1/client-portals`](/api-reference/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](/pt/guides/dynamic-call-config)). 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](/pt/guides/embed-a-web-widget-dashboard). **Na API:** [`/v1/publishable-key`](/api-reference/publishable-keys), [`/v1/mic-session`](/api-reference/mic-sessions) e a [documentação do SDK de widgets](/pt/widget/overview). --- ## 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](/pt/guides/knowledge-base). --- ## 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](/pt/guides/connect-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](/pt/guides/api-connections) — a interface no dashboard de [`/v1/integrations`](/api-reference/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](/pt/guides/mcp-servers). - **VoIP** (`/dashboard/voip-connections`) — credenciais de provedor para [usar seus próprios números de telefone](#phone-numbers). Consulte [Conectar um provedor VoIP](/pt/guides/voip-providers). 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](/pt/guides/thunderphone-mcp-server). **Na API:** [`/v1/integrations`](/api-reference/integrations), [`/v1/mcp-servers`](/api-reference/mcp-servers) e [`/v1/voip-connections`](/api-reference/voip-connections); consulte também [Criar uma integração de ferramenta](/pt/guides/build-tool-integration). --- ## 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](/pt/guides/outbound-campaigns). **Para chamadas programáticas pontuais:** a [API de chamadas de saída](/pt/guides/place-outbound-calls). ## Monitoramento ao vivo **Ao vivo** mostra todas as chamadas em andamento na organização e permite abrir qualquer uma delas para [ouvir e sussurrar](#calls) 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](/pt/guides/monitor-live-calls). --- ## 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](/pt/guides/simulate-a-call). **Na API:** [`/v1/test-calls`](/api-reference/test-calls) e o executor de suítes — consulte [Testar um agente de ponta a ponta](/pt/guides/test-agents). --- ## 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](/pt/guides/validation-sets). **Na API:** [`/v1/validation-sets`](/api-reference/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)](/pt/guides/experiments-ab-testing). --- ## 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](/pt/guides/issues). **Na API:** [`/v1/issue-reports`](/api-reference/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](/pt/guides/reports). --- ## 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](/pt/guides/observability). --- ## 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](/pt/webhooks/endpoints). **No painel:** **Organização → Alertas**. Consulte [Alertas](/pt/guides/alerts). --- ## 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`](/pt/webhooks/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`](/api-reference/organizations#legacy-single-url-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](/pt/webhooks/call-incoming) (`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](/pt/webhooks/overview). 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](/pt/webhooks/overview). --- ## 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](#connections)). **Na API:** [`/v1/integrations`](/api-reference/integrations) e a [especificação de Ferramentas de Função](/pt/tools/overview). --- ## 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](/pt/guides/sso). **No dashboard:** **Organização → Geral**. Consulte [Convide sua equipe](/pt/guides/invite-your-team). **Na API:** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/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](/pt/guides/supported-languages) adicionam {/* rate:language */}3¢/min{/* /rate */}). 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](/pt/guides/billing-and-topups), além da [referência completa de preços](/pt/guides/pricing). **Na API:** [`/v1/billing`](/api-reference/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](/pt/guides/ask-the-copilot). --- ## Juntando tudo O assistente de cinco etapas: agente → faturamento → número → simulação → revisão. A mesma primeira chamada em quatro chamadas REST. Crie um agente, adicione saldo, obtenha um número, simule e revise chamadas. Aplicativos OAuth, APIs personalizadas, servidores MCP e provedores de VoIP. Relatórios, observabilidade, experimentos, problemas e alertas. Convites e funções, chaves de API, segurança e SSO. As receitas da API: recebimento, realização, configuração dinâmica, ferramentas e testes. Faça a verificação HMAC corretamente uma vez e reutilize-a em todos os lugares.