> ## 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.

# Widget de voz incorporável

> 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.

<Frame>
  <img src="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="Widget do ThunderPhone em temas claros e escuros com várias cores de destaque" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## Pré-requisitos

Antes de incorporar o widget, conclua estas três etapas no [Painel do ThunderPhone](https://app.thunderphone.com):

<Steps>
  <Step title="Criar uma chave de API publicável">
    Acesse **Desenvolvedores** nas configurações do painel e crie uma chave publicável. As chaves publicáveis começam com `pk_live_` e podem ser incluídas com segurança no código do cliente.
  </Step>

  <Step title="Configurar domínios permitidos">
    Nas mesmas configurações de Desenvolvedores, adicione os domínios onde o widget será incorporado. `localhost` é sempre permitido para desenvolvimento. Caracteres curinga são compatíveis (por exemplo, `*.example.com`).
  </Step>

  <Step title="Criar um widget web">
    Acesse **Widgets Web** no painel e crie um widget. Selecione o agente que deseja disponibilizar e a chave publicável a ser usada. O agente é resolvido automaticamente a partir da configuração da sua chave publicável.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

***

## Início rápido

Instale o pacote:

```bash theme={null}
npm install @thunderphone/widget
```

Adicione o widget ao seu aplicativo:

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

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'` |

<CodeGroup>
  ```tsx Light theme (default) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

  ```tsx Dark theme with custom color theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
    theme="dark"
    primaryColor="#8b5cf6"
    title="Ask our AI"
  />
  ```
</CodeGroup>

Mais três props personalizam a sessão, e não a aparência -- todas são encaminhadas para a solicitação de sessão quando uma chamada é iniciada:

| 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.

***

## Opções de integração

Escolha o método de integração que melhor se adapta à sua stack:

<CardGroup cols={3}>
  <Card title="Componente React" icon="react" href="/pt/widget/react">
    Componente de UI pré-criado com controles de chamada e exibição de status integrados. Importe, passe as props e pronto.
  </Card>

  <Card title="Hook headless" icon="code" href="/pt/widget/headless-hook">
    Controle total sobre a UI. O hook `useThunderPhone` gerencia a sessão de voz enquanto você cria sua própria interface.
  </Card>

  <Card title="CDN / tag de script" icon="globe" href="/pt/widget/cdn-script-tag">
    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.
  </Card>
</CardGroup>

***

## 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.

<Note>
  Precisa de ajuda? Entre em contato pelo [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>