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

# Componente React

> Incorpore o widget de voz do ThunderPhone em uma aplicação React

O componente `ThunderPhoneWidget` renderiza uma barra de chamada glassmórfica com controles integrados para silenciar, encerrar a chamada e exibir o status da conexão. É a forma mais rápida de adicionar IA de voz a um app React.

## Instalação

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

## Uso básico

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  Você **deve** importar o arquivo CSS para que o widget seja renderizado corretamente. Sem ele, o widget ficará sem estilo.
</Warning>

***

## Propriedades

O componente aceita as seguintes propriedades por meio de `ThunderPhoneWidgetProps`:

| Propriedade      | Tipo                                                           | Obrigatória | Padrão                                     | Descrição                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------- | ----------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `publishableKey` | `string`                                                       | Sim         | --                                         | Chave de API publicável (`pk_live_...`) das configurações de Desenvolvedores. O agente é resolvido automaticamente pela configuração do widget da chave.                             |
| `theme`          | `'light' \| 'dark'`                                            | Não         | `'light'`                                  | Esquema de cores. Aplica a classe `tp--light` ou `tp--dark` à raiz do widget.                                                                                                        |
| `primaryColor`   | `string`                                                       | Não         | `'#000000'` (claro) / `'#ffffff'` (escuro) | String de cor CSS usada como cor de destaque (botão de chamada, forma de onda, indicadores ativos).                                                                                  |
| `title`          | `string`                                                       | Não         | `'Voice assistant'`                        | Texto exibido na barra do widget.                                                                                                                                                    |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Não         | `'bottom-right'`                           | Posição fixa do widget na viewport.                                                                                                                                                  |
| `apiBase`        | `string`                                                       | Não         | `'https://api.thunderphone.com/v1'`        | Substituição da URL base da API.                                                                                                                                                     |
| `language`       | `string`                                                       | Não         | --                                         | Substituição de idioma por sessão -- um código de idioma ou localidade, como `en`, `es` ou `fr-FR`. Quando não definido, o idioma configurado do agente é aplicado.                  |
| `voice`          | `string`                                                       | Não         | --                                         | Substituição de voz por sessão -- um nome de voz, como `maria`. Quando não definido, a voz configurada do agente é aplicada.                                                         |
| `context`        | `string`                                                       | Não         | --                                         | Contexto factual da página ou do site por sessão enviado ao agente (por exemplo, detalhes da página que o visitante está visualizando). Truncado no servidor para 12.000 caracteres. |
| `onConnect`      | `() => void`                                                   | Não         | --                                         | Chamado quando a sessão de voz é conectada com sucesso.                                                                                                                              |
| `onDisconnect`   | `() => void`                                                   | Não         | --                                         | Chamado quando a sessão termina.                                                                                                                                                     |
| `onError`        | `(error) => void`                                              | Não         | --                                         | Chamado em caso de erros. O objeto `error` tem os campos `error` (código) e `message`.                                                                                               |
| `className`      | `string`                                                       | Não         | --                                         | Nome adicional de classe CSS aplicado ao contêiner do widget.                                                                                                                        |
| `ringtone`       | `boolean \| string`                                            | Não         | `false`                                    | Reproduz um toque durante a conexão. `true` para o toque padrão ou uma string de URL para áudio personalizado.                                                                       |

***

## Exemplos

### Tema escuro com cor personalizada

```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"
      title="Talk to our AI"
    />
  )
}
```

### Posição personalizada

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### Idioma, voz e contexto por sessão

As props `language`, `voice` e `context` são encaminhadas para a solicitação de sessão (`POST /widget/session`) quando uma chamada é iniciada, substituindo os padrões configurados do agente para essa sessão:

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

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

Use `context` para fornecer ao agente conhecimento factual sobre a página em que o visitante está — detalhes do produto, preços ou perguntas frequentes específicas da página. O conteúdo é truncado no servidor para 12.000 caracteres.

### Com callbacks de eventos

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

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### Com estilização personalizada

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

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Consulte o [guia de estilização](/pt/widget/styling) para ver todas as classes CSS e propriedades personalizadas disponíveis.

### Com toque

Reproduza um som de telefone tocando enquanto a conexão é estabelecida:

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

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

Use um toque personalizado fornecendo a URL de um arquivo de áudio:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

O toque é reproduzido em loop enquanto o widget está no estado `connecting` e diminui suavemente quando o agente se conecta.

### Com base de API personalizada

<Tip>
  Você só precisa definir `apiBase` se estiver usando um endpoint de API auto-hospedado ou de proxy. O padrão aponta para `https://api.thunderphone.com/v1`.
</Tip>

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

***

## Tratamento de erros

Quando o callback `onError` é acionado, ele recebe um objeto de erro com dois campos:

| Campo     | Tipo     | Descrição                             |
| --------- | -------- | ------------------------------------- |
| `error`   | `string` | Código de erro legível por máquina    |
| `message` | `string` | Descrição de erro legível por humanos |

Os códigos de erro comuns incluem domínio não permitido, agente não encontrado e chave de API inválida.

***

## Próximas etapas

<CardGroup cols={2}>
  <Card title="Hook headless" icon="code" href="/pt/widget/headless-hook">
    Precisa de controle total sobre a interface? Use o hook `useThunderPhone`.
  </Card>

  <Card title="Estilização" icon="palette" href="/pt/widget/styling">
    Personalize cores, tamanhos e layout com propriedades personalizadas de CSS.
  </Card>
</CardGroup>