Como enviar informações adicionais do usuário usando o SDK do widget
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
Configuração
Descrição
hideMessageBubble
Oculta o botão flutuante do widget
showUnreadMessagesDialog
Mostra aviso de mensagens não lidas
position
Posição do widget (left ou right)
locale
Idioma do widget
useBrowserLanguage
Usa idioma do navegador do visitante
type
Tipo do widget (standard ou expanded_bubble)
darkMode
Tema do widget (light, dark ou auto)
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"
});
});