---
title: "Widget de voz incorporável"
description: "Adicione um agente de voz com IA a qualquer site com algumas linhas de código"
---
O widget de voz incorporável do ThunderPhone permite que os visitantes do seu site conversem com um agente de IA diretamente no navegador. Não é necessária nenhuma ligação -- os usuários clicam em um botão e iniciam uma conversa por voz em tempo real com a tecnologia do ThunderPhone.
O widget é exibido como uma barra com efeito glassmorphism que se adapta a temas claros e escuros, com cores de destaque e posicionamento personalizáveis. Ele é distribuído como o pacote npm `@thunderphone/widget` e também está disponível via CDN para ambientes sem bundler.
## Pré-requisitos
Antes de incorporar o widget, conclua estas três etapas no [Painel do ThunderPhone](https://app.thunderphone.com):
Acesse **Widgets web** no dashboard e crie um widget. Selecione o agente que deseja disponibilizar. Cada widget tem sua própria chave publicável (`pk_live_...`), que pode ser incluída com segurança no código do cliente; o agente é determinado pela chave.
No mesmo widget, adicione os domínios onde ele será incorporado. Caracteres curinga são compatíveis (por exemplo, `*.example.com`). A lista impede que o widget funcione quando alguém copia sua chave para outro site; ela não é uma forma de autenticação, pois um script fora de um navegador pode enviar qualquer cabeçalho `Origin`. `localhost` não é permitido automaticamente em produção: adicione-o à lista para testar localmente com a API de produção.
Se sua página definir `language`, `voice` ou `context`, ative cada opção em **Substituições do navegador**. Novos widgets não aceitam nenhuma, e uma solicitação de sessão que inclua uma configuração desativada falhará com `400 override_not_allowed`. Consulte [Substituições do navegador](/pt/guides/embed-web-widget).
As chaves publicáveis (`pk_live_...`) **não** são iguais aos seus tokens de API secretos. As chaves publicáveis foram projetadas para uso no cliente e são limitadas a sessões de widget nos seus domínios permitidos. Nunca use seu token de API secreto no código do cliente.
Por padrão, as sessões do widget terminam após 30 minutos ou antes, caso a duração máxima de chamada do próprio agente seja menor. Altere o limite por chave com `max_call_duration_seconds` na [chave publicável](/api-reference/publishable-keys) (até 6 horas) ou defina-o como `null` para usar o limite do próprio agente.
---
## Início rápido
Instale o pacote:
```bash
npm install @thunderphone/widget
```
Adicione o widget ao seu aplicativo:
```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
function App() {
return (
)
}
```
Pronto. Seus usuários verão uma barra de chamada com efeito glassmorphism que os conecta ao seu agente de IA com um único clique.
---
## Personalização
O widget tem quatro props de aparência:
| Prop | Padrão | Descrição |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` para vidro branco, `'dark'` para vidro escuro |
| `primaryColor` | `'#000000'` (claro) / `'#ffffff'` (escuro) | Cor de destaque para o botão de iniciar, a forma de onda e o indicador de conexão |
| `title` | `'Voice assistant'` | Texto exibido no widget |
| `position` | `'bottom-right'` | Canto da viewport: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |
```tsx Light theme (default)
```
```tsx Dark theme with custom color
```
Outras três propriedades personalizam a sessão, não a aparência — todas são encaminhadas para a solicitação de sessão quando uma chamada começa. Cada uma funciona somente quando a chave publicável do widget permite seu uso em **Substituições do navegador**; caso contrário, a solicitação de sessão falha com `400 override_not_allowed`:
| Prop | Descrição |
|------|-------------|
| `language` | Substituição de idioma por sessão -- um código ou localidade como `en`, `es` ou `fr-FR` |
| `voice` | Substituição de voz por sessão -- um nome de voz como `maria` |
| `context` | Contexto factual da página ou do site passado ao agente (truncado no servidor para 12.000 caracteres) |
Consulte a [referência do componente React](/pt/widget/react) para a tabela completa de props.
Para uma interface totalmente personalizada, use o [hook headless](/pt/widget/headless-hook) para gerenciar a sessão de voz enquanto cria sua própria interface. O hook expõe níveis de áudio em tempo real para criar visualizações que reagem ao áudio.
Cada conversa no widget é uma chamada. Ela conta para o [limite de chamadas simultâneas](/api-reference/introduction#call-limits) da sua organização (20 chamadas em andamento por padrão, compartilhadas com chamadas telefônicas e outras chamadas) e para um limite do widget de 25 sessões ativas (ou o seu limite de chamadas simultâneas, se for maior). Ao atingir qualquer um dos limites, uma nova conversa não poderá começar até que uma chamada termine.
---
## Opções de integração
Escolha o método de integração que melhor se adapta à sua stack:
Componente de UI pré-criado com controles de chamada e exibição de status integrados. Importe, passe as props e pronto.
Controle total sobre a UI. O hook `useThunderPhone` gerencia a sessão de voz enquanto você cria sua própria interface.
Não requer bundler. Carregue o widget por meio de uma tag de script para sites estáticos, WordPress e outros ambientes que não usam React.
---
## Estilização
O widget inclui temas claro e escuro integrados, controlados pela prop `theme`, e uma cor de destaque controlada pela prop `primaryColor`. Para uma personalização mais profunda, você pode substituir propriedades e classes personalizadas de CSS. Consulte o [guia de estilização](/pt/widget/styling) para ver os detalhes.
Precisa de ajuda? Entre em contato pelo [support@thunderphone.com](mailto:support@thunderphone.com)