O SDK do widget permite enviar informações adicionais dos usuários diretamente para a plataforma, possibilitando identificação automática, histórico persistente, atributos personalizados e experiências mais inteligentes no atendimento.

Após instalar o script do widget no seu site, o objeto global abaixo ficará disponível:

window.$chatWidget

Aguardando o SDK carregar

Antes de utilizar qualquer método do SDK, aguarde o carregamento completo do widget:

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

Escutando novas mensagens

Você também pode ouvir eventos de novas mensagens recebidas no widget:

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

Configurações do widget

As configurações globais do widget podem ser definidas usando:

window.chatWidgetSettings = {
  hideMessageBubble: false,

  showUnreadMessagesDialog: false,

  position: "left",

  locale: "pt_BR",

  useBrowserLanguage: false,

  type: "standard",

  darkMode: "auto"
};

Configurações disponíveis

Usar idioma automático do navegador

Para exibir o widget automaticamente no idioma do navegador do visitante:

window.chatWidgetSettings = {
  useBrowserLanguage: true
};

Quando ativado:

• o idioma definido em locale será ignorado

• caso o idioma não seja suportado, o widget utilizará o idioma padrão da plataforma

Dark Mode

O widget suporta modo escuro automático:

window.chatWidgetSettings = {
  darkMode: "auto"
};

Opções disponíveis:

• light

• dark

• auto

Tipos de widget

Standard

Widget tradicional compacto.

type: "standard"

Expanded Bubble

Widget expandido com texto lateral.

window.chatWidgetSettings = {
  type: "expanded_bubble",
  launcherTitle: "Fale conosco"
};

Abrir chat em janela popout

Para habilitar o botão de popout:

window.chatWidgetSettings = {
  showPopoutButton: true
};

Abrir programaticamente:

window.$chatWidget.popoutChatWindow();

Personalizar mensagens do widget

Você pode alterar:

• título do widget

• descrição

• mensagens online/offline

window.chatWidgetSettings = {
  welcomeTitle: "Precisa de ajuda?",

  welcomeDescription: "Nossa equipe está pronta para atender você.",

  availableMessage: "Estamos online agora!",

  unavailableMessage: "No momento estamos offline."
};

Recursos opcionais do widget

window.chatWidgetSettings = {
  enableFileUpload: true,

  enableEmojiPicker: true,

  enableEndConversation: true
};

Abrir e fechar o widget programaticamente

Alternar estado:

window.$chatWidget.toggle();

Abrir:

window.$chatWidget.toggle("open");

Fechar:

window.$chatWidget.toggle("close");

Mostrar ou ocultar o botão do widget

window.$chatWidget.toggleBubbleVisibility("show");

window.$chatWidget.toggleBubbleVisibility("hide");

Identificar usuários no widget

Você pode identificar visitantes autenticados da sua aplicação:

window.$chatWidget.setUser("user-123", {
  email: "[email protected]",
  name: "João Silva",
  avatar_url: "https://site.com/avatar.jpg",
  phone_number: "+5511999999999"
});

Validação de identidade com HMAC

Para impedir impersonação e proteger o histórico do cliente, utilize validação HMAC:

window.$chatWidget.setUser("user-123", {
  name: "João Silva",

  email: "[email protected]",

  identifier_hash: "HASH_HMAC_GERADO"
});

Além disso, você pode enviar:

• telefone

• cidade

• empresa

• redes sociais

• descrição

• país

Definir atributos personalizados

Você pode enviar informações adicionais do cliente:

window.$chatWidget.setCustomAttributes({
  accountId: 1,
  pricingPlan: "pro"
});

Esses dados aparecem no painel lateral da conversa.

Remover atributo personalizado

window.$chatWidget.deleteCustomAttribute("pricingPlan");

Alterar idioma manualmente

window.$chatWidget.setLocale("pt_BR");

Definir labels automaticamente

window.$chatWidget.setLabel("cliente-vip");

Remover label:

window.$chatWidget.removeLabel("cliente-vip");

Resetar sessão do widget

Ideal para logout do usuário:

window.$chatWidget.reset();

Capturar erros do widget

window.addEventListener("widget:error", function () {
  console.log("Erro no widget");
});

Exemplo completo

window.chatWidgetSettings = {
  position: "right",

  locale: "pt_BR",

  darkMode: "auto",

  type: "expanded_bubble",

  launcherTitle: "Fale conosco",

  welcomeTitle: "Precisa de ajuda?",

  welcomeDescription: "Estamos prontos para atender você.",

  availableMessage: "Equipe online",

  unavailableMessage: "Equipe offline",

  enableFileUpload: true,

  enableEmojiPicker: true,

  enableEndConversation: true
};

window.addEventListener("widget:ready", function () {
  window.$chatWidget.setUser("user-123", {
    name: "João Silva",
    email: "[email protected]"
  });

  window.$chatWidget.setCustomAttributes({
    plan: "enterprise",
    company: "Acme"
  });
});