Como enviar informações adicionais de usuário com o SDK

O SDK do Chatwoot permite enviar informações adicionais dos seus usuários para o Chatwoot, tornando o atendimento pelo chat no site mais personalizado e eficiente. Este guia mostra como identificar quem está conversando (setUser) e enviar atributos personalizados, além das demais configurações do widget.

Ao instalar o código do Chatwoot no seu site, o SDK expõe o objeto window.$chatwoot. Para garantir que o SDK foi carregado por completo, escute o evento chatwoot:ready antes de chamar qualquer método:

window.addEventListener("chatwoot:ready", function () {
  // Use window.$chatwoot aqui
  // ...
});

Para escutar as mensagens trocadas no widget, utilize o evento abaixo:

window.addEventListener("chatwoot:on-message", function (e) {
  console.log("chatwoot:on-message", e.detail);
});

Definir o usuário no widget (setUser)

Se você já conhece quem está navegando (por exemplo, um cliente logado no seu site), use setUser para identificá-lo no Chatwoot. O primeiro argumento é um identificador único do usuário; o segundo é um objeto com os dados dele:

window.$chatwoot.setUser("<identificador-único-do-usuário>", {
  email: "[email protected]",
  name: "Maria Silva",
  avatar_url: "https://exemplo.com/maria.png",
  phone_number: "+5511999999999"
});

Chame setUser sempre depois do evento chatwoot:ready. Informe pelo menos um valor válido em name, email ou avatar_url; se enviar phone_number, use o formato internacional E.164, começando por + e o código do país.

Validação de identidade com HMAC

Para evitar falsificação de identidade e garantir a privacidade das conversas, ative a validação de identidade gerando um identifier_hash a partir de um token HMAC. Com a validação ativa, você pode enviar o conjunto completo de campos de contato:

window.$chatwoot.setUser("<identificador-único>", {
  name: "Maria Silva",
  avatar_url: "https://exemplo.com/maria.png",
  email: "[email protected]",
  identifier_hash: "<hash-HMAC-gerado-no-servidor>",
  phone_number: "+5511999999999",
  description: "Cliente desde 2024",
  country_code: "BR",
  city: "São Paulo",
  company_name: "Empresa Exemplo",
  social_profiles: {
    linkedin: "https://www.linkedin.com/in/maria-exemplo",
    facebook: "https://www.facebook.com/maria.exemplo",
    github: "https://github.com/maria-exemplo"
  }
});

Para gerar o token HMAC e habilitar esse recurso, veja Como habilitar a validação de identidade no Chatwoot?.

Definir atributos personalizados

Use setCustomAttributes para adicionar informações extras sobre o cliente (por exemplo, plano contratado ou ID interno):

window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "pago"
});

Para remover um atributo, use deleteCustomAttribute:

window.$chatwoot.deleteCustomAttribute("nome-do-atributo");

Configurações do SDK

Defina as preferências do widget no objeto window.chatwootSettings. Para ocultar a bolha de mensagens, defina hideMessageBubble como true (nesse caso, lembre-se de acionar o widget manualmente):

window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Desativa o diálogo de mensagens não lidas
  position: "left",                // Pode ser "left" ou "right"
  locale: "pt",                    // Idioma do widget
  useBrowserLanguage: false,       // Usa o idioma do navegador do usuário
  type: "standard",                // [standard, expanded_bubble]
  darkMode: "auto"                 // [light, auto, dark]
  // baseDomain: "seudominio.com"  // Rastrear usuários entre subdomínios
};

Usar o idioma do navegador

Para exibir o widget no idioma do navegador do usuário, defina useBrowserLanguage como true. Observação: se useBrowserLanguage estiver como true, o valor de locale será ignorado. Se o idioma do navegador não for suportado pelo Chatwoot, o widget usará o idioma configurado em locale.

Modo escuro

Defina darkMode como auto para acompanhar o tema do dispositivo, dark para manter o modo escuro ou light para manter o modo claro.

Modelos de widget

O Chatwoot oferece dois modelos de widget: o padrão (standard) e a bolha expandida (expanded_bubble). Para personalizar o texto da bolha expandida, utilize o parâmetro launcherTitle:

window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "Converse conosco"
};

Ativar a janela pop-out

Para habilitar a janela pop-out, adicione a configuração abaixo ao chatwootSettings:

window.chatwootSettings = {
  showPopoutButton: true
};

Você também pode abrir a janela pop-out programaticamente:

window.$chatwoot.popoutChatWindow();

Controlar o widget programaticamente

Alternar a visibilidade da bolha

Para mostrar ou ocultar a bolha do Chatwoot, use toggleBubbleVisibility:

window.$chatwoot.toggleBubbleVisibility("show"); // mostrar a bolha
window.$chatwoot.toggleBubbleVisibility("hide"); // ocultar a bolha

Abrir o widget programaticamente

Para abrir o chat ao clicar em um link ou botão, use o método toggle:

window.$chatwoot.toggle();        // Alterna o estado
window.$chatwoot.toggle("open");  // Abre o widget
window.$chatwoot.toggle("close"); // Fecha o widget

Definir o idioma manualmente

Use setLocale para definir o idioma do widget:

window.$chatwoot.setLocale("pt");

Aplicar etiquetas na conversa

Para adicionar ou remover etiquetas de uma conversa, use setLabel e removeLabel:

window.$chatwoot.setLabel("suporte");
window.$chatwoot.removeLabel("suporte");

Reiniciar a sessão

Ao desconectar o usuário do seu site, reinicie a sessão do widget:

window.$chatwoot.reset();

Tratar erros do widget

Para detectar erros no widget, escute o evento chatwoot:error:

window.addEventListener("chatwoot:error", function () {
  // ...
});

Observação: este recurso está disponível a partir da versão 2.3.0.