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)

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

Se o seu caso é o Cenário 3 (área logada), você precisa configurar o HMAC. Sem ele a conversa não será criada.

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.

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:

É 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

⚠️ 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.

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.

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.

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.

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:

Como ativar:

No painel do Cloud Chat, vá em Caixas de Entrada → (sua inbox Website) → Configuração
Ative a flag Múltiplas conversas por usuário
Copie o novo script exibido após a ativação — ele já vem com user_id e identifier_hash no formato correto
Substitua o script atual da página pelo novo

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

Abra a página com o widget instalado
Verifique se o widget aparece no canto da tela
Cenário 2 e 3: confirme que nome, e-mail, telefone e atributos já aparecem preenchidos sem o cliente digitar
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
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
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?

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.

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

Como instalar o Web Widget do Cloud Chat: público, com dados ou em área logada (HMAC)

Quando usar

Pré-requisitos

Sobre este tutorial

Qual cenário é o seu?

Etapa comum a todos os cenários — Criar a caixa de entrada do tipo Web Widget

1. Acessar a tela de Caixas de Entrada

2. Escolher o canal Website

3. Configurar o canal do website

4. Adicionar agentes

5. Configuração do script

Cenário 1 — Web Widget público (sem passar dados do cliente)

Como instalar

Cenário 2 — Web Widget passando dados do cliente, fora de área logada

Como instalar

Cenário 3 — Web Widget em área logada (com HMAC + opcionalmente múltiplas conversas)

3.1 — Como funciona o HMAC

3.2 — Copiar o token da caixa de entrada

3.3 — Calcular o identifier_hash no backend

3.4 — Enviar o hash no widget via setUser

3.5 — Forçar a validação na caixa de entrada

3.6 — (Opcional) Habilitar múltiplas conversas e histórico

Validação de Domínio (opcional, todos os cenários)

Como testar

Perguntas frequentes

O que acontece se já existir uma informação anterior do contato?

E se eu errar o nome de algum campo personalizado?

Posso passar atributos da conversa também?

Que tipos de formatação o widget aceita?

Posso usar HMAC sem ativar múltiplas conversas?

Posso usar tudo isso em apps mobile?

Observações

3.3 — Calcular o `identifier_hash` no backend

3.4 — Enviar o hash no widget via `setUser`