> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Conceitos principais
> 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, operar 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 precisar entender melhor um termo.
A barra lateral do dashboard reflete esta estrutura:
[Agentes](#agents), [números de telefone](#phone-numbers),
[widgets web](#web-widgets), [chamadas](#calls),
[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), [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 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
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`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/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](/pt/guides/supported-languages).
* Recursos conectados: [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 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.
***
## 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](#connections). 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.
Cada linha de número permite definir um modo de roteamento, escolher o agente de chamadas recebidas
e rotular o número.
**No dashboard:** **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
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](/pt/guides/review-calls).
**Na API:** [`/v1/calls`](/api-reference/calls) — lista, transcrição,
histórico, áudio, classificação, exportação;
[`/v1/issue-reports`](/api-reference/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](/pt/guides/dynamic-call-config)). 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](/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 do Widget](/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 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](/pt/guides/knowledge-base).
***
## 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](/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** envia 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 provedores para
[usar seus próprios números de telefone](#phone-numbers). Consulte
[Conectar um provedor de VoIP](/pt/guides/voip-providers).
**Na API:** [`/v1/integrations`](/api-reference/integrations) 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, 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](/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 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](/pt/guides/monitor-live-calls).
***
## 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](/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).
***
## 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)](/pt/guides/experiments-ab-testing).
***
## 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](/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 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](/pt/guides/reports).
***
## 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](/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í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 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 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-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 retroativa.
Os eventos são divididos em duas classes:
* **Eventos bloqueantes** esperam que seu servidor responda com uma configuração
que define a chamada em andamento — os
[eventos de chamada recebida](/pt/webhooks/call-incoming)
(`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](/pt/webhooks/overview).
Cada solicitação inclui uma assinatura HMAC-SHA256 em
`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 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](#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 ⋯ 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](/pt/guides/sso).
**No painel:** **Organização → Geral**. Consulte
[Convide sua equipe](/pt/guides/invite-your-team).
**Na API:** [`/v1/members`](/api-reference/members),
[`/v1/invites`](/api-reference/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](/pt/guides/supported-languages) adicionam 2¢/min). Quando o
saldo chega a zero, chamadas recebidas são rejeitadas e 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 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](/pt/guides/billing-and-topups).
**Na API:** [`/v1/billing`](/api-reference/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](/pt/guides/ask-the-copilot).
***
## Juntando tudo
O assistente de cinco etapas: agente → cobrança → 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: chamadas recebidas, chamadas feitas, configuração dinâmica, ferramentas e testes.
Faça a verificação de HMAC corretamente uma vez e reutilize-a em todos os lugares.