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

# Incorpore o widget da web

> Adicione um agente de voz ao seu site de marketing ou suporte — sem precisar de número de telefone.

O widget da web oferece aos visitantes do seu site uma conversa por clique para falar
com um agente de IA, usando o microfone do navegador. É um SDK separado de
JavaScript / React com sua própria [referência do SDK](/pt/widget/overview)
— este guia se concentra na configuração do lado do ThunderPhone necessária para o widget.

<Note>
  Você pode fazer tudo isso sem cURL: a página **Widgets da web** do painel
  (`/dashboard/web-widgets`) cria o widget, define seu modo
  e agente, gerencia os domínios permitidos e fornece o snippet de incorporação.
</Note>

## Pré-requisitos

<Steps>
  <Step title="Criar um agente">
    O agente cujo prompt e voz executarão a sessão do widget. Defina
    `widget_enabled: true` (o padrão).
  </Step>

  <Step title="Definir o modo de roteamento">
    * `mode="agent"` — um agente estático por chave. Mais simples.
    * `mode="webhook"` — seu servidor escolhe o agente para cada visitante por meio de um
      [webhook `web.incoming`](/pt/webhooks/call-incoming). Use isso para
      usuários autenticados, testes A/B ou roteamento por página.
  </Step>

  <Step title="Listar os domínios permitidos">
    As chaves publicáveis são bloqueadas por origem. Você deve informar cada nome de host
    que incorporará o widget. `localhost` / `127.0.0.1` são sempre
    permitidos durante o desenvolvimento local.
  </Step>
</Steps>

## Criar uma chave publicável

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

A resposta inclui uma `key` que começa com `pk_live_...`. **As chaves
publicáveis são públicas por design** — é seguro incluí-las no bundle do seu
front-end. Consulte a [referência de chaves publicáveis](/api-reference/publishable-keys) para
ver todos os campos.

<Warning>
  `allowed_domains` deve conter pelo menos uma entrada. `*.example.com`
  corresponde a subdomínios (por exemplo, `api.example.com`), mas **não** ao
  domínio raiz. Curingas simples como `*` ou `*.*` são rejeitados.
</Warning>

## Adicione o widget ao seu site

Três opções de integração são abordadas na
[documentação do SDK do widget](/pt/widget/overview):

<CardGroup cols={3}>
  <Card title="Componente React" icon="react" href="/pt/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Hook headless" icon="circle-nodes" href="/pt/widget/headless-hook">
    `useThunderPhone()` para UIs personalizadas.
  </Card>

  <Card title="Tag de script CDN" icon="code" href="/pt/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` para sites sem bundler.
  </Card>
</CardGroup>

Os três aceitam a mesma `publishableKey` e renderizam o botão de microfone
e o elemento de áudio durante a chamada.

O `context` do widget é truncado em 12.000 caracteres (aproximadamente 3.400
tokens de texto típico em inglês) e conta para a
[taxa adicional pelo tamanho do prompt](/pt/guides/billing-and-topups).

## Webhooks no modo widget

Quando `mode="webhook"`, o ThunderPhone chama seu `webhook_url` a cada
início de sessão com uma carga `web.incoming`. Retorne a configuração do agente
que deseja executar para esse visitante — ela segue o mesmo
[esquema de resposta](/pt/webhooks/call-incoming) das
chamadas telefônicas:

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

Você pode combinar o contexto da sua própria sessão (qual cliente está navegando,
em qual página ele está) no prompt e trocar agentes a cada lançamento.

## Observe as sessões

As sessões do widget aparecem em
[`GET /v1/calls`](/api-reference/calls#list-calls) com
`direction="widget"` — a mesma transcrição, gravação, avaliação e
cobrança das chamadas telefônicas. Filtre por `direction` para criar um
painel exclusivo para widgets.

***

## Próximas etapas

<CardGroup cols={2}>
  <Card title="Referência do SDK do widget" icon="window-maximize" href="/pt/widget/overview">
    Detalhes de integração com React / hook / CDN.
  </Card>

  <Card title="Configuração dinâmica por chamada" icon="bolt" href="/pt/guides/dynamic-call-config">
    Implemente o fluxo `mode="webhook"` de ponta a ponta.
  </Card>

  <Card title="Referência de chaves publicáveis" icon="key" href="/api-reference/publishable-keys">
    Todos os campos do recurso de chave.
  </Card>

  <Card title="API de sessões de microfone" icon="microphone" href="/api-reference/mic-sessions">
    Ignore o widget; use o LiveKit diretamente para interfaces personalizadas.
  </Card>
</CardGroup>