Widgets do Site: central de atendimento multi-canal

O Widget do Site é um botão flutuante que o seu cliente final cola no site dele e que junta vários canais de contato (WhatsApp, Telegram, Instagram, Facebook, Email) num único lugar. O visitante clica na bolha, escolhe por onde quer falar, e a origem (UTMs + cookies de ads + landing page) é capturada automaticamente pro relatório de atribuição.

O que é

O Widget do Site é uma central de atendimento embedável: um botão flutuante que aparece no canto do site do cliente final. Ao clicar, abre um painel listando os canais que você cadastrou (WhatsApp, Instagram, Telegram, Facebook, Email). O visitante escolhe, e é redirecionado pro canal escolhido com o código de rastreio embutido na mensagem.

É diferente dos outros 2 jeitos de embedar atendimento no site:

	Widget do Site	WebChat	Link Rastreável
Forma	Botão flutuante multi-canal	Chat ao vivo dentro do widget	Link standalone
Onde colar	`<script>` no HTML do site	`<script>` no HTML do site	Anúncio Meta/Google, bio Instagram, email mkt, QR code
Quem atende	Você no Inbox, depois que cliente cair no WhatsApp/Instagram/etc	Você no Inbox em tempo real, dentro do widget	Você no Inbox, depois que cliente mandar msg pelo canal
Caso típico	Site quer dar várias opções de contato sem se comprometer com chat ao vivo	Site quer suporte em tempo real direto no chat	Anúncio do Meta/Google ou QR físico

Os três coexistem — você pode usar todos, ou só um. O Widget do Site faz mais sentido quando o cliente quer dar escolha ao visitante (WhatsApp pra quem prefere, Instagram pra quem usa mais, etc.) sem o compromisso operacional de manter alguém respondendo o chat ao vivo 24/7.

Como funciona pro visitante final

Visitante chega no site do seu cliente (ex: acme.com.br).
Vê uma bolha flutuante no canto inferior direito.
Clica. Abre um painel listando os canais disponíveis.
Escolhe (ex: WhatsApp).
Se houver 1 número/perfil só daquele canal → redireciona direto pro wa.me / t.me / ig.me / mailto: com o código de rastreio embutido.
Se houver 2+ instâncias do mesmo tipo (ex: WhatsApp Vendas + WhatsApp Suporte) → abre um drill-down "Qual WhatsApp você quer falar?" antes de redirecionar.
Visitante manda a mensagem (que já vem com [#CW-XXXX] pré-preenchido). Codewo recebe, casa o código com as UTMs capturadas, e cria um touchpoint no contato.

Como configurar

Em Configurações → Widgets do Site, clique em Novo widget. O dialog tem 2 colunas: form à esquerda, preview ao vivo à direita (atualiza conforme você muda).

1. Nome e status

Nome — interno. Aparece só pra você. Ex: "Site institucional", "Landing Black Friday".
Ativo — desligado, o snippet continua no site do cliente mas nada renderiza. Bom pra pausar sem precisar tirar o código de produção.

2. Posição

Cards de "Inferior Direita" / "Inferior Esquerda" — onde a bolha aparece na tela do visitante. Default = direita (padrão da maioria dos sites). Esquerda é útil quando o site já tem botão flutuante à direita (carrinho, scroll-to-top, etc.) e você quer evitar sobreposição.

3. Texto CTA no balão (toggle)

Ligado — bolha vira um pill expandido com o texto do CTA principal (ex: "Falar no WhatsApp →"). Chama mais atenção, melhor pra conversão.
Desligado — bolha vira só um círculo com o ícone do canal. Footprint menor, menos invasivo. Usar quando o site já é visualmente carregado.

4. Realçar canal #1 como CTA principal (toggle)

Ligado — o primeiro canal da sua ordem vira um botão grande no topo do painel (ex: "Iniciar conversa →"). Mostra hierarquia: o admin diz "prefiro que você fale por aqui".
Desligado — todos os canais aparecem como lista plana, em pé de igualdade. Bom quando você não tem preferência ou quer testar qual canal converte mais.

5. Canais e ordem

Arraste pra reordenar. O primeiro canal define:

A cor da bolha (verde se WhatsApp tá no topo, indigo se Chat ao vivo, azul se Telegram, etc.)
O ícone da bolha
O texto do CTA principal (quando "Realçar #1" tá ligado)

Pra cada canal adicionado:

Switch — liga/desliga. Desligado, o canal sai do widget sem precisar remover (útil pra pausar Instagram em férias da equipe que cuida disso).
Rótulo customizado (opcional) — sobrescreve o nome técnico do canal no widget. Ex: o canal WhatsApp chama-se "Pessoal" internamente, mas no widget público você quer mostrar "Vendas". Quando o canal é o #1 com "Realçar" ligado, esse rótulo também vira o texto do CTA — útil pra ter CTAs personalizados tipo "Falar com Vendas" ou "Tirar dúvida com a Maria".

Dica: se você cadastrar 2 WhatsApps (Vendas + Suporte), o widget mostra automaticamente "WhatsApp · 2 disponíveis" e ao clicar abre o drill-down. Você NÃO precisa configurar isso, é detectado pelo tipo do canal.

6. Mensagem de boas-vindas

Texto curto que aparece no header colorido do painel quando ele abre. Ex: "Olá! Como podemos ajudar?". Default existe — só altere se quiser personalizar o tom (ex: "Oi! Quer um cupom de desconto?").

7. Domínios permitidos

Restringe onde o snippet pode rodar. Deixe vazio = qualquer domínio. Útil quando:

Você quer impedir que outro site copie o snippet e use sua atribuição.
Você tem ambiente de testes (staging.acme.com) e produção (acme.com) e quer permitir os dois.
Cliente final tem subdomínios (*.acme.com aceita www.acme.com, blog.acme.com, app.acme.com).

Wildcard suportado: *.dominio.com libera todos os subdomínios; * libera todos os domínios (= deixar vazio).

Pegando o snippet e instalando

Depois de salvar, clique em Snippet no card do widget. Você verá um trecho HTML tipo:

```html

```

Cole antes do </body> em todas as páginas do site do cliente final. Em sites com CMS (WordPress, Shopify, Wix), procure por "código personalizado", "scripts no rodapé" ou "footer scripts".

A bolha aparece automaticamente assim que o script carrega. Não precisa de configuração no HTML do cliente — só colar.

Atribuição: o que é capturado

Quando o visitante clica num canal no widget, o launcher automaticamente captura e envia pro Codewo:

1. UTMs da URL atual
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `gclid`, `fbclid`, `gbraid`, `wbraid`.

2. UTMs persistidas (sobreviveram a navegação interna)
Storage local 30 dias — visitante chega em /promo?utm_source=google, navega pra /produtos, depois pra /contato, finalmente clica no widget → UTMs originais ainda estão lá.

3. Cookies de ads tags presentes no site
`_gcl_aw` (Google Ads), `_fbp` / `_fbc` (Meta Pixel), `_ga` (Google Analytics). Setados pelos scripts de tracking que o seu cliente já tem instalado. Sobrevivem 90+ dias e enriquecem o match-back server-to-server quando você implementar Meta CAPI ou Google Offline Conversions.

4. Landing URLs
URL atual + a URL onde a UTM foi capturada originalmente (`first_landing_url`).

Tudo isso vai pro AttributionCode.payload na hora do click. Quando o visitante manda a mensagem no WhatsApp/Telegram/Email com o [#CW-XXXX] pré-preenchido, o webhook do canal casa o código e cria um `contact_touchpoint` com todos os dados.

Mais detalhes em Atribuição multi-touch.

Preview ao vivo

Conforme você muda configs no form, o preview à direita atualiza em tempo real. Inclui:

Tab Aberto / Fechado — alterne pra ver os 2 estados.
Auto-switch inteligente — toggle de "Mostrar CTA no balão" muda → preview pula pra Fechado pra você ver. Toggle "Realçar canal #1" muda → pula pra Aberto.
Drill-down clicável — se você adicionou 2+ canais do mesmo tipo, clica no canal no preview e veja como vai abrir a sub-lista pro visitante.

Pegadinhas comuns

Snippet duplicado. Se você colar o snippet 2 vezes no mesmo HTML, o launcher protege com __codewoLauncherLoaded — só a primeira execução vale. Mas evita o lixo no HTML por higiene.
WebChat dentro do launcher. Por enquanto, o launcher não embeda o WebChat (chat ao vivo nativo). Se você quer chat ao vivo + outros canais, use o snippet do WebChat junto com o launcher (dois balões aparecem). Embed unificado vem em versão futura.
SMS / Phone fora. Esses canais não têm fluxo "click pra abrir conversa" no navegador — ficam fora da lista de canais elegíveis pro widget.
Editou e nada mudou no site? O config tem cache de 5 minutos no backend pra performance. Quando você salva, o cache é invalidado automaticamente — mas se a página do cliente final estava aberta há mais que 5min, peça um refresh.
Removeu/desativou canal e ele ainda aparece no widget? O cache também invalida quando você desativa/exclui canal. Refresh resolve.
Domínios permitidos vazio = qualquer um. Se você se preocupa com terceiros copiando o snippet, preencha pelo menos *.dominio-do-cliente.com.

Sempre que você muda algo no admin:

Salva o widget → cache backend é zerado imediatamente.
Canal desativado/excluído → cache dos widgets que usavam aquele canal é zerado.
Visitante novo do site do cliente → carrega a versão atualizada na próxima requisição.
Visitante com a página já aberta → ele só veria a mudança se recarregasse a página (launcher.js não faz polling — sem isso, gastaria banda à toa).

Isso significa: mudanças refletem em segundos pra visitantes novos, e na próxima sessão pra quem já tava no site. Aceitável pra 99% dos casos.

FAQ

Posso ter mais de um widget na mesma empresa?
Sim. Cada widget tem snippet próprio. Útil pra A/B testing (cor diferente, ordem diferente, copy diferente) ou pra sites diferentes do mesmo cliente.

O snippet expira?
Não. O token do snippet só é invalidado se você rotacionar manualmente (botão futuro — por enquanto edite o widget e ele mantém o mesmo token). Se vazar, fale com o suporte pra forçar rotação.

Funciona em mobile?
Sim. Em telas pequenas a bolha ocupa o canto, e o painel abre em popover responsivo. Em iPhone, o mailto: abre o Mail; o wa.me abre o WhatsApp app instalado.

Funciona em Single Page Apps (React/Vue/Next)?
Sim. O launcher é montado no DOM uma vez no DOMContentLoaded e fica lá. Trocar de rota internamente no SPA não afeta — a bolha continua visível.

O cliente final precisa pedir permissão de cookies?
Depende da legislação do país. No Brasil (LGPD), tracking analytics em geral é base legal de "legítimo interesse" — não precisa banner mandatório. Mas se o cliente do seu cliente já tem banner de cookies, vale incluir o launcher na descrição "ferramentas de atendimento".