Widget: identificar usuários logados

Quando o visitante já está autenticado no seu site, o widget pode abrir o atendimento sem pedir nome e telefone. Pessoa e empresa são criadas ou atualizadas no CRM no momento da identificação; a conversa só nasce quando a primeira mensagem é enviada.

1. Instale o widget

O identificador da conta está em Configurações > Widget.

<script src="https://SEU-DOMINIO/widget.js" data-account="ID_DA_CONTA" defer></script>

2. Informe quem está logado

// Depois do login, no seu app
await window.$hubzy.setUser("user_123", {
  name: "Maria Souza",
  email: "maria@empresa.com",
  phone: "+5511999999999", // opcional
  title: "Gerente de Operações",
  city: "São Paulo",
  company: {
    identifier: "org_42",
    name: "Empresa Exemplo",
    website: "https://empresa.com",
  },
  identityToken: "<token assinado no seu servidor>", // opcional, recomendado
});

// No logout
await window.$hubzy.reset();

O identifier é o identificador estável do usuário no seu sistema (nunca use e-mail que possa mudar). Identificadores diferentes nunca são mesclados automaticamente: cada um é um cadastro.

Alternativa declarativa

Quando o usuário já é conhecido no carregamento da página:

<script>
  window.hubzySettings = {
    user: { identifier: "user_123", name: "Maria Souza", email: "maria@empresa.com" },
  };
</script>
<script src="https://SEU-DOMINIO/widget.js" data-account="ID_DA_CONTA" defer></script>

3. Assine a identidade (recomendado)

Sem assinatura, a identidade vale apenas para o navegador atual — o histórico não é retomado em outro dispositivo, para evitar que alguém se passe por outro usuário. Com o token assinado, a conversa aberta é retomada em qualquer navegador e os dados do perfil são aceitos como verificados.

Gere o segredo em Configurações > Widget. Ele aparece uma única vez; guarde-o apenas no servidor. Rotacionar o segredo encerra as sessões verificadas em andamento.

// Node.js — no SEU servidor, nunca no navegador
import { createHmac } from "crypto";

const claims = {
  aud: ACCOUNT_ID,            // id da conta
  sub: "user_123",            // mesmo identificador passado ao setUser
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + 300, // no máximo 5 minutos
  profile: {
    name: "Maria Souza",
    email: "maria@empresa.com",
    company: { identifier: "org_42", name: "Empresa Exemplo" },
  },
};

const payload = Buffer.from(JSON.stringify(claims)).toString("base64url");
const signature = createHmac("sha256", HUBZY_WIDGET_SECRET).update(payload).digest("base64url");
const identityToken = payload + "." + signature;

Quando o token é usado, os dados de perfil considerados são os que estão dentro dele — o que vem do navegador é ignorado.

4. Eventos

window.addEventListener("hubzy:ready", () => {});
window.addEventListener("hubzy:user-set", (e) => console.log(e.detail.verified));
window.addEventListener("hubzy:reset", () => {});
window.addEventListener("hubzy:error", (e) => console.warn(e.detail.error));

Erros possíveis

• identity_invalid — token expirado, assinatura errada, ou aud/sub diferentes da conta e do identificador.
• identity_conflict — o telefone informado já pertence a outro cadastro; resolva no CRM.
• rate_limited — muitas identificações sem assinatura em pouco tempo.
• invalid_account — conta inexistente ou inativa.

Boas práticas

• Chame reset() no logout: a sessão do navegador é revogada.
• Gere o token no servidor a cada carregamento de página, com validade curta.
• Nunca exponha o segredo em código do navegador nem em repositórios.
• Telefone é opcional para usuários identificados; o identificador externo é a chave.