> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget para Site

> Widget de chat ao vivo first-party para o seu site — as conversas dos visitantes chegam na caixa de entrada do Switchbord, com respostas opcionais de IA do GBCA em modo rascunho ou envio automático.

O widget para site coloca uma bolha de chat nativa do Switchbord em qualquer site que você controle. As mensagens dos visitantes chegam na mesma caixa de entrada de operadores que as conversas do WhatsApp, os operadores respondem pelo mesmo compositor e — diferentemente de fornecedores de chat hospedado que prendem você ao chatbot deles — o widget pode encaminhar as conversas diretamente para o seu agente GBCA conectado.

Se você usa hoje o tawk.to ou um widget hospedado semelhante apenas para chat ao vivo, este é o caminho de substituição direta: uma tag de script, sua própria IA, seus próprios dados.

## O que você recebe

<CardGroup cols={2}>
  <Card title="Instalação em uma linha" icon="code">
    Uma única tag de script assíncrona por widget. Mudanças de aparência e comportamento são publicadas a partir de Settings sem precisar tocar no snippet novamente.
  </Card>

  <Card title="Caixa de entrada unificada" icon="inbox">
    As conversas do widget aparecem em `/inbox` ao lado do WhatsApp, em tempo real, com recursos adaptados ao canal (nenhuma regra de templates ou janela de atendimento se aplica aos chats do widget).
  </Card>

  <Card title="Sua IA, não a deles" icon="robot">
    O modo de IA por widget conecta o agente GBCA: rascunhos de resposta para revisão do operador, ou envio totalmente automático até que um humano assuma.
  </Card>

  <Card title="Lista de origens permitidas" icon="shield-check">
    Cada widget atende apenas os domínios que você listar. Requisições de qualquer outro lugar falham de forma segura.
  </Card>
</CardGroup>

## Criando um widget

Vá em **Settings → Integrations → Channels → Website widget**:

1. Clique em **Create widget** e dê a ele um nome de exibição.
2. Escolha um **slug** — ele passa a fazer parte da URL pública do script e do link direto de chat, então escolha algo que você não se importe de expor (letras minúsculas, números, hífens).
3. Adicione suas **origens permitidas** — as origens exatas (esquema + host, p. ex. `https://www.example.com`) de cada site que vai incorporar o widget. Subdomínios são origens separadas.
4. Escolha a cor de destaque do tema e a posição do botão de abertura, defina o título do widget e a mensagem de boas-vindas.
5. Copie o **snippet de instalação** na seção Install e entregue-o a quem mantém o site — ou use o [guia de instalação](/pt-BR/guides/website-widget-install), que inclui instruções específicas por framework e um prompt pronto para agentes de programação com IA.

O card de **diagnósticos de instalação** na mesma página executa verificações passivas — endpoint público habilitado, origens configuradas, slug válido — para que você possa confirmar a configuração antes mesmo de o snippet ir para produção.

<Tip>
  Todo widget também recebe um **link direto de chat** hospedado (`/chat/{slug}` no seu domínio de API). Útil para assinaturas de e-mail, QR codes, ou para testar o widget sem tocar em nenhum site.
</Tip>

## Modo de agente de IA (GBCA)

Cada widget tem seu próprio modo de IA, independente das suas configurações de resposta automática do WhatsApp:

| Modo             | Comportamento                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Off** (padrão) | Os operadores tratam todas as mensagens. Nenhum envolvimento de IA.                                                                                                                         |
| **Draft**        | Cada mensagem de visitante gera um rascunho do GBCA no compositor da caixa de entrada para revisão do operador — o mesmo fluxo de estado âmbar dos rascunhos proativos do WhatsApp.         |
| **Auto-send**    | O agente GBCA responde aos visitantes automaticamente. No instante em que um operador humano envia uma resposta na conversa, os envios autônomos param e o agente volta a apenas rascunhar. |

A autoridade de envio automático é reverificada contra as configurações do widget no momento do envio, então mudar o modo de volta para Draft ou Off tem efeito imediato — inclusive para respostas já enfileiradas. A chave mestra do GB-Agent no nível do workspace precisa estar habilitada para que qualquer modo de IA faça alguma coisa.

<Note>
  As conversas do widget nunca passam pelo pipeline de despacho do WhatsApp/Meta. As respostas de IA são entregues ao visitante pelo próprio widget.
</Note>

## Identidade do visitante

Por padrão, os visitantes são anônimos — o widget cria uma sessão e um contato sintético automaticamente. Dois upgrades estão disponíveis:

* **Atributos não verificados**: o JavaScript da sua página pode chamar `SwitchbordWidget.setVisitor({...})` para anexar um nome ou e-mail que o visitante digitou em algum lugar. Eles são armazenados como não verificados e nunca podem sobrescrever dados verificados.
* **Identidade assinada (Secure Mode)**: se o seu site tem usuários autenticados, o seu backend pode emitir um token HS256 de curta duração para que o Switchbord saiba *de forma verificável* quem é o visitante. Visitantes verificados retomam a conversa anterior entre sessões e dispositivos. Veja o [guia de instalação](/pt-BR/guides/website-widget-install#identidade-assinada-secure-mode) para exemplos do lado do servidor.

Você também pode ativar **Require identity** em um widget, o que bloqueia o envio de mensagens e o histórico até que o visitante da sessão seja verificado — o widget ainda inicializa anonimamente para poder realizar o handshake de login.

Quando uma identidade verificada corresponde a um contato existente (por e-mail ou telefone), o Switchbord cria uma **sugestão de mesclagem** não destrutiva em vez de mesclar automaticamente.

## O que os operadores veem

* As conversas do widget carregam o selo do canal de site; recursos exclusivos do WhatsApp (templates, contagem regressiva da janela de atendimento, upload de mídia) ficam ocultos.
* As respostas aparecem para o visitante com o rótulo de autor do operador; respostas de IA mostram o rótulo do agente.
* Os visitantes veem um selo de não lidas no botão de abertura quando respostas chegam com o chat fechado.

## Limites e comportamento

* Os endpoints públicos do widget têm limite de taxa por workspace (120 requisições/minuto), além da proteção no nível da plataforma.
* Execuções de IA disparadas por mensagens do widget passam por debounce — mensagens de visitantes em sequência rápida se consolidam em uma única execução do agente para a mensagem mais recente.
* O histórico da transcrição tem escopo de sessão: visitantes anônimos que limpam o armazenamento do navegador começam uma conversa nova. A identidade assinada é o fio condutor durável entre dispositivos.

## Próximos passos

* [Instale o widget no seu site](/pt-BR/guides/website-widget-install) — snippet, frameworks, referência do SDK, identidade assinada e um prompt de instalação para agentes de IA.
* [Conector GB-Agent](/pt-BR/platform/gb-agent-connector) — como o próprio agente GBCA é conectado ao seu workspace.