Como instalar o Web Widget do Cloud Chat: público, com dados ou em área logada (HMAC)
Quando usar
- Você quer adicionar o chat do Cloud Chat em qualquer página do seu site
- Você quer passar dados do contato automaticamente (nome, e-mail, telefone, atributos) sem o cliente digitar
- Você quer validar a identidade do usuário (HMAC) para impedir que alguém se passe por outra pessoa
- Você quer permitir múltiplas conversas simultâneas e dar acesso ao histórico dentro do widget
- Você quer restringir o widget a domínios específicos (ex: produção apenas)
- Você quer saber se o cliente final vê o histórico dos atendimentos, como impedir que ele encerre a conversa ou por
que mensagens de visitantes diferentes caem na mesma conversa
Pré-requisitos
- Estar logado como administrador no Cloud Chat
- Acesso ao código fonte do site onde o widget vai ser instalado
- Para Cenário 3 (área logada com HMAC): backend próprio para gerar o identifier_hash — não pode ser feito no frontend
(expõe a chave secreta)
Sobre este tutorial
Esse artigo cobre o ciclo completo de instalação do Web Widget do Cloud Chat. Antes de seguir o passo a passo de código,
você precisa decidir qual dos 3 cenários se encaixa no seu uso — eles têm requisitos e complexidade muito diferentes.
Qual cenário é o seu?
| Cenário | Quando usar | Passa dados do cliente? | Precisa de HMAC? | | --- | --- | --- | --- | | 1. Widget público
(sem dados) | Site público / landing page / blog. O cliente digita o próprio nome e e-mail ao iniciar a conversa. | ❌
Não | ❌ Não | | 2. Widget com dados, fora de área logada | Páginas que já conhecem o contato mas não exigem
autenticação forte (ex: link único enviado por e-mail/CRM, formulário pós-cadastro). | ✅ Sim | ❌ Não | | 3. Widget em
área logada (com HMAC) | Portal do cliente, dashboard interno, app autenticado. Qualquer cenário onde o usuário precisa
fazer login pra acessar. | ✅ Sim | ✅ Obrigatório |
:::warning Se o seu caso é o Cenário 3 (área logada), você precisa configurar o HMAC. Sem ele a conversa não será
criada.
:::
:::info O atributo personalizado do contato deve ser criado previamente — ver Como criar campos customizados de contatos
e conversas.
:::
Etapa comum a todos os cenários — Criar a caixa de entrada do tipo Web Widget
Antes de configurar qualquer cenário, você precisa criar uma caixa de entrada do tipo Website no Cloud Chat. O caminho é
o mesmo para os 3 cenários.
1. Acessar a tela de Caixas de Entrada
No painel do Cloud Chat, vá em Configurações → Caixas de Entrada e clique no botão Adicionar Caixa de Entrada (canto
superior direito).
2. Escolher o canal Website
Selecione o card Website na grade de canais disponíveis.
3. Configurar o canal do website
Preencha os campos:
- Nome do site — nome exibido pro cliente (ex: "Cloud Humans")
- Domínio do website — domínio onde o widget vai rodar (ex: cloudhumans.com)
- Cor do Widget — cor primária do botão e cabeçalho
- Seja bem-vindo — título inicial do widget (ex: "Olá!")
- Bem-vindo, saudação — mensagem de boas-vindas
- Ativar saudação do canal — se quer enviar mensagem automática ao iniciar conversa
Clique em Criar caixa de entrada.
4. Adicionar agentes
Selecione os agentes que terão acesso a essa caixa de entrada. Como administrador, adicione-se a si mesmo se quiser
visualizar todas as conversas.
Clique em Adicionar agentes.
5. Configuração do script
Na tela final (“Sua caixa de entrada está pronta!”), o Cloud Chat exibe o script básico de instalação do widget. Porém,
existem outras opções de configuração que podem ser utilizadas dependendo do seu cenário.
Clique em Mais configurações. Nessa seção, você verá as três opções de script disponíveis para instalação, que
explicaremos abaixo.
:::success Pronto. Agora vá pro cenário que se aplica ao seu caso (1, 2 ou 3 abaixo) e siga as instruções específicas de
cada um.
:::
Cenário 1 — Web Widget público (sem passar dados do cliente)
Use quando o widget fica numa página pública (landing, blog, site institucional). O cliente digita o próprio nome /
e-mail / telefone ao iniciar a conversa.
Como instalar
Cole o script copiado na Etapa Comum (Passo 5) logo antes do fechamento da tag </body> no HTML da página:
:::info É só isso. Esse cenário não exige nada além do script base. Não chame setUser(), não passe identifier_hash. O
cliente preenche os próprios dados no formulário inicial do widget.
:::
Cenário 2 — Web Widget passando dados do cliente, fora de área logada
Use quando você já conhece o contato mas a página não exige login. Exemplos:
- Link único enviado por e-mail ou WhatsApp com o identifier na URL
- Página pós-cadastro (o cliente acabou de preencher um formulário)
- Página acessada via deep link de campanha de CRM
Aqui você quer pré-preencher nome, e-mail, telefone e atributos personalizados sem o cliente digitar.
Como instalar
:::error ⚠️ O primeiro argumento de setUser(...) é o identifier — precisa ser único por usuário (ID interno, UUID do
banco, etc). Se você deixar o identifier chumbado (valor fixo, copiado do exemplo, ou um placeholder), o Cloud Chat
mescla todos os acessos como o mesmo contato — funde tickets de pessoas diferentes na mesma conversa e quebra o
histórico irreversivelmente.
Antes de subir pra produção, confirme com seu time de engenharia que o identifier está sendo populado dinamicamente com
o ID real do usuário.
:::
:::info Você precisa passar pelo menos o e-mail ou o telefone — são os identificadores que o Cloud Chat usa para fazer
match com o contato.
:::
Cenário 3 — Web Widget em área logada (com HMAC + opcionalmente múltiplas conversas)
Use quando o widget fica dentro de área logada (portal do cliente, dashboard, app autenticado). Aqui o HMAC é
obrigatório.
Esse cenário também é o único onde faz sentido habilitar múltiplas conversas + histórico.
3.1 — Como funciona o HMAC
A validação usa HMAC SHA-256: um código gerado a partir do identifier do usuário combinado com uma chave secreta (token)
da caixa de entrada.
:::warning A geração do identifier_hash é responsabilidade do cliente. O cálculo precisa acontecer no backend
(servidor), nunca no navegador, se a chave secreta vazar no front-end, a proteção deixa de existir. A Cloud Humans
fornece o token por caixa de entrada; implementar o cálculo e a entrega do hash ao widget é responsabilidade da equipe
técnica do cliente.
:::
3.2 — Copiar o token da caixa de entrada
Em Configurações → Caixas de Entrada → (sua inbox Website) → Configurações avançadas → Validação de Identidade do
Usuário → Copiar.
Esse token é secreto — guarde apenas no backend, nunca no frontend.
3.3 — Calcular o identifier_hash no backend
Quando o usuário se autentica no seu sistema, o backend calcula:
identifier_hash = HMAC_SHA256(token_da_inbox, identifier)
Onde identifier é o ID único do usuário (UUID interno, e-mail corporativo, etc).
Exemplos server-side:
// Node.js
const crypto = require('crypto');
const hash = crypto
.createHmac('sha256', '<token-da-inbox>')
.update('<identifier>')
.digest('hex');
# Python
import hashlib, hmac
hash = hmac.new(b'<token-da-inbox>', b'<identifier>', hashlib.sha256).hexdigest()
// PHP
$identifier_hash = hash_hmac('sha256', '<identifier>', '<token-da-inbox>');
3.4 — Enviar o hash no widget via setUser
<script>
(function(d,t) {
var BASE_URL="https://cloudchat2.cloudhumans.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.defer = true;
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.cloudchatSDK.run({
websiteToken: 'SEU_TOKEN_AQUI',
baseUrl: BASE_URL
});
window.addEventListener('cloudchat:ready', function() {
window.$cloudchat.setUser('<identifier-do-usuario>', {
identifier_hash: '<hash-gerado-no-backend>',
email: '[email protected]',
name: 'João da Silva',
phone_number: '+5511999999999'
});
});
}
})(document,"script");
</script>
3.5 — Forçar a validação na caixa de entrada
Ainda em Configurações avançadas, marque "Forçar validação de identidade do usuário" → Habilitado. A partir daí,
requisições sem um identifier_hash válido são rejeitadas.
:::error Ative o "Forçar validação" somente depois que o backend já estiver enviando o identifier_hash correto. Se
ativar antes, todas as conversas que não enviam o hash passam a ser rejeitadas e o chat para de funcionar. Teste
primeiro numa caixa de entrada de homologação.
:::
:::success Boas práticas:
- Use um identifier estável — nunca mude o identificador de um usuário existente
- Não exponha o token HMAC no frontend
- Gere o hash sempre no backend e envie ao cliente apenas no momento de inicializar o widget
- Regenere o identifier_hash toda vez que o widget for carregado para um usuário autenticado
:::
3.6 — (Opcional) Habilitar múltiplas conversas e histórico
Com o HMAC já funcionando, você pode habilitar a feature de múltiplas conversas + histórico: o mesmo usuário consegue
manter vários atendimentos abertos em paralelo e ver o histórico de conversas já encerradas dentro do próprio widget.
Útil para SaaS, B2B ou e-commerce com alta recompra/recontato.
Como o usuário vê: o widget passa a exibir duas abas — Conversas ativas (em aberto) e Histórico de conversas
(encerradas, com busca por data inicial, data final e ID do ticket; carrega 5 por vez).
Vídeos demonstrativos:
https://www.loom.com/share/5e1ffa9996814752b4e745191d5059f7
https://www.loom.com/share/184de48c78c440dfaf6169c14b244f94
Como ativar:
1. No painel do Cloud Chat, vá em Caixas de Entrada → (sua inbox Website) → Configuração
2. Ative a flag Múltiplas conversas por usuário
3. Copie o novo script exibido após a ativação — ele já vem com user_id e identifier_hash no formato correto
4. Substitua o script atual da página pelo novo
:::error A feature de múltiplas conversas e histórico depende do HMAC estar ativo e funcionando. Não habilite em widget
público (Cenário 1) nem em widget sem área logada (Cenário 2) — sem validação de identidade, qualquer um consegue
acessar o histórico de outro usuário.
:::
Validação de Domínio (opcional, todos os cenários)
Configure os domínios onde o widget pode funcionar — útil para evitar uso fora dos domínios autorizados (staging,
terceiros não autorizados).
Em Caixas de Entrada → (sua inbox) → Configuração, na seção Validação de Domínio:
| Configuração | Comportamento | | --- | --- | | Campo vazio | Sem restrições — funciona em qualquer domínio | |
example.com | Permite uso apenas nesse domínio | | *.example.com | Permite uso em todos os subdomínios (ex:
app.example.com, login.example.com) |
Como testar
1. Abra a página com o widget instalado
2. Verifique se o widget aparece no canto da tela
3. Cenário 2 e 3: confirme que nome, e-mail, telefone e atributos já aparecem preenchidos sem o cliente digitar
4. Cenário 2 e 3: teste com pelo menos 2 usuários diferentes — abra o widget com um, depois com outro, confira no
painel se aparecem como contatos separados (não mesclados num só). Se aparecerem mesclados, o identifier está fixo —
corrija antes de subir pra produção
5. Cenário 3: teste com um identifier_hash inválido e confirme que o widget rejeita a requisição quando "Forçar
validação" está habilitado
6. Cenário 3 com múltiplas conversas: abra dois tickets em paralelo e confirme que aparecem como conversas separadas
dentro do widget
Perguntas frequentes
O que acontece se já existir uma informação anterior do contato?
A nova informação enviada via script sobrescreve os dados antigos. O dado mais recente prevalece.
E se eu errar o nome de algum campo personalizado?
Nenhum erro é lançado. O campo incorreto é ignorado silenciosamente. Apenas os campos existentes são atualizados.
Posso passar atributos da conversa também?
:::warning Não por enquanto. A passagem de atributos personalizados da conversa não foi lançada na versão atual (v0) por
limitações técnicas. Use o formulário no início da conversa como alternativa.
:::
Que tipos de formatação o widget aceita?
O Widget aceita a maioria dos formatos do Markdown:
- Negrito / Tachado / Itálico
- Bloco de código
- Links
- Imagens
- Bullet points
Posso usar HMAC sem ativar múltiplas conversas?
Sim. HMAC é uma camada de segurança independente — você pode ativar só o HMAC (Cenário 3, passos 3.1 a 3.5) sem
habilitar múltiplas conversas (passo 3.6). O contrário não é recomendado.
O cliente final consegue ver o histórico dos próprios atendimentos?
Sim, dentro do próprio widget do site. Com Múltiplas conversas por usuário ativa (passo 3.6), o widget mostra duas abas:
Conversas ativas e Histórico de conversas, com busca por data e pelo número do ticket.
- Funciona só no Cenário 3 (área logada com HMAC), porque o histórico precisa ter certeza de quem é o usuário.
- Cada pessoa vê apenas os próprios atendimentos. Não existe visão por empresa: colegas da mesma empresa não veem os
chamados uns dos outros.
- Não existe um portal de tickets com URL própria. O único portal com link é a Central de Ajuda, com artigos.
Como impedir que o cliente encerre a conversa pelo widget?
1. Vá em Configurações → Caixas de entrada e abra a caixa do Web Widget.
2. Na aba Configurações, desmarque Permitir que usuários terminem a conversa a partir do widget.
3. Salve.
Com a opção desmarcada, o cliente deixa de poder encerrar a conversa pelo widget. Quem encerra passa a ser o time ou a
ClaudIA.
Mensagens de visitantes diferentes aparecem na mesma conversa. O que fazer?
Quase sempre o script do site está mandando o mesmo identificador para todo mundo. O Cloud Chat junta quem tem o mesmo
identificador num só contato, e essas pessoas passam a ver as mensagens umas das outras. Os casos mais comuns:
- o script foi publicado com o valor de exemplo da documentação, sem trocar pelo ID real do usuário;
- a variável do usuário chega vazia e o identificador vai como undefined ou null.
Como corrigir:
1. Se clientes reais estiverem sendo afetados, tire o widget do ar até corrigir.
2. Só chame setUser quando o usuário estiver logado e tiver um ID real (id do cliente ou e-mail). Para visitante não
logado, não chame setUser: o widget funciona como anônimo (Cenário 1).
3. Nunca passe como identificador um valor vazio, null, undefined ou fixo.
4. No logout, chame window.$cloudchat.reset().
5. Procure outras cópias do script no site (outros arquivos, templates e gerenciador de tags). Em lojas Shopify, por
exemplo, o script pode estar em sections, snippets ou templates, além do theme.liquid.
6. Para impedir que alguém se passe por outro cliente, ative a validação de identidade com HMAC (Cenário 3).
Posso usar tudo isso em apps mobile?
Sim, via WebView. Veja Como integrar o Web Widget em aplicativos mobile.
Observações
- Para compartilhar a sessão do widget entre abas do navegador: Como compartilhar a sessão do Web Widget entre abas do
navegador
- Para usar o widget em apps mobile via WebView: Como integrar o Web Widget em aplicativos mobile
- Para criar atributos personalizados antes de passar via script: Como criar campos customizados de contatos e
conversas
- Para ativar continuidade de conversa por e-mail: Como habilitar continuidade de conversas por e-mail
- Para ativar o widget no Portal de Ajuda: Como ativar o Web Widget no Portal de Ajuda
