O SDK do Chatwoot para sites permite que você envie informações adicionais do usuário para o Chatwoot.
Se você instalou nosso código no seu site, o SDK expõe o objeto window.$chatwoot. Para garantir que o SDK tenha sido carregado completamente, certifique-se de escutar o evento chatwoot:ready da seguinte forma:
window.addEventListener("chatwoot:ready", function () {
// Use window.$chatwoot aqui
// ...
});
Se você deseja escutar as mensagens no widget, pode usar o seguinte evento.
window.addEventListener('chatwoot:on-message', function(e) {
console.log('chatwoot:on-message', e.detail)
})
Configurações do SDK
Para ocultar o balão, você pode usar a configuração mencionada abaixo.
Observação: Se você usar isto, também deve acionar o widget.
window.chatwootSettings = {
hideMessageBubble: false,
showUnreadMessagesDialog: false, // Desabilita o diálogo de mensagens não lidas
position: "left", // Pode ser left ou right
locale: "en", // Idioma a ser definido
useBrowserLanguage: false, // Definir o idioma do widget pelo navegador do usuário
type: "standard", // [standard, expanded_bubble]
darkMode: "auto", // [light, auto]
// baseDomain: "yourdomain.com" // configure se quiser rastrear usuários entre subdomínios
};
Usar idioma do navegador no widget de chat ao vivo automaticamente
Para exibir o widget de chat ao vivo no idioma do navegador do usuário, defina useBrowserLanguage como true em window.chatwootSettings mencionado acima.
Observação: Se useBrowserLanguage for definido como true, o locale mencionado será ignorado. Se o idioma do navegador não for suportado pelo Chatwoot, será usado o locale informado em locale. Caso também não haja essa configuração, o widget usará o locale do painel do agente.
Modo Escuro
O widget de chat ao vivo do Chatwoot suporta modo escuro a partir da versão v2.4.0. Para ativar o modo escuro, siga os passos mencionados aqui.
Designs do widget
O Chatwoot suporta dois designs para o widget.
-
Padrão (default)
-
Balão expandido
Se você estiver usando o balão expandido, pode personalizar o texto utilizado no balão definindo o parâmetro launcherTitle nas chatwootSettings conforme mostrado abaixo.
window.chatwootSettings = {
type: "expanded_bubble",
launcherTitle: "Fale conosco",
};
Habilitar janela popout
Para habilitar a janela popout, adicione a seguinte configuração em chatwootSettings. Esta opção fica desabilitada por padrão.
window.chatwootSettings = {
// ...Outras configurações
showPopoutButton: true,
}
Você também pode abrir a janela de chat como popout programaticamente com o método `popoutChatWindow()`.
Mensagens personalizadas
Personalize as mensagens de boas-vindas e disponibilidade exibidas no cabeçalho do widget e indicadores de status da equipe.
window.chatwootSettings = {
// ...Outras configurações
welcomeTitle: "Precisa de ajuda?", // Cabeçalho personalizado do widget
welcomeDescription: "Estamos aqui para te ajudar.", // Subtítulo do cabeçalho
availableMessage: "Estamos online e prontos para conversar!", // Quando a equipe está online
unavailableMessage: "No momento estamos offline." // Quando a equipe está indisponível
};
Botões de ativação de recursos
Ative ou desative funcionalidades opcionais da interface dentro do widget:
window.chatwootSettings = {
// ...Outras configurações
enableFileUpload: true, // Exibir botão de anexar arquivo
enableEmojiPicker: true, // Ativar seleção de emoji na entrada do chat
enableEndConversation: true // Permite que usuários encerrem a conversa
};
Abrir a janela popout programaticamente
Você pode abrir a janela popout programaticamente com o método popoutChatWindow().
Para iniciar este processo, chame o método conforme abaixo.
window.$chatwoot.popoutChatWindow();
Alternar a visibilidade do balão do widget
Se quiser ocultar/exibir o balão do widget Chatwoot, utilize toggleBubbleVisibility('show/hide')
Exemplo
window.$chatwoot.toggleBubbleVisibility("show"); // para exibir o balão
window.$chatwoot.toggleBubbleVisibility("hide"); // para ocultar o balão
Acionar o widget programaticamente
Se quiser abrir a janela de chat ao clicar em um link no site, siga o método abaixo. Na sua ação, chame o SDK do Chatwoot conforme descrito abaixo.
window.$chatwoot.toggle();
// Alternar widget especificando estado
window.$chatwoot.toggle("open"); // Para abrir o widget
window.$chatwoot.toggle("close"); // Para fechar o widget
Definir o usuário no widget
window.$chatwoot.setUser("<unique-identifier-key-of-the-user>", {
email: "<[email protected]>",
name: "<name-of-the-user>",
avatar_url: "<avatar-url-of-the-user>",
phone_number: "<phone-number-of-the-user>",
});
setUser aceita um identificador, que pode ser o user_id em sua base de dados ou qualquer parâmetro único que represente um usuário. Você pode passar email, nome, avatar_url, phone_number como parâmetros. O suporte para parâmetros adicionais está em desenvolvimento.
Garanta que você reinicie a sessão quando o usuário fizer logout do seu app.
Validação de identidade usando HMAC
Para evitar personificação e manter a conversa com seus clientes privada, recomendamos configurar a validação de identidade no Chatwoot. A validação de identidade é feita gerando um HMAC (código de autenticação de mensagem baseado em hash) baseado no atributo identifier, usando SHA256. Junto com o identifier, você pode passar também o identifier_hash, como demonstrado abaixo, para garantir que o usuário está correto.
window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, {
name: "", // Nome do usuário
avatar_url: "", // URL do avatar
email: "", // Email do usuário
identifier_hash: "", // Hash do identificador gerado com base no webwidget hmac_token
phone_number: "", // Número de telefone do usuário
description: "", // descrição sobre o usuário
country_code: "", // Código de país com duas letras
city: "", // Cidade do usuário
company_name: "", // nome da empresa
social_profiles: {
twitter: "", // Nome do usuário no Twitter
linkedin: "", // Nome do usuário no LinkedIn
facebook: "", // Nome do usuário no Facebook
github: "", // Nome do usuário no Github
},
});
Para gerar o HMAC, leia sobre validação de identidade. Observação: implementar autenticação HMAC permite a persistência do histórico de chat entre sessões.
Definir atributos personalizados
Para definir informações extras sobre o cliente, você pode usar o campo de atributos personalizados do cliente. Saiba mais sobre atributos personalizados aqui.
Para definir um atributo personalizado, chame setCustomAttributes conforme abaixo
window.$chatwoot.setCustomAttributes({
accountId: 1,
pricingPlan: "paid",
// Aqui a chave precisa já estar definida como atributo personalizado
// O valor deve ser baseado no tipo (Atualmente suporta Number, Date, String e Number)
});
Você pode visualizar essas informações no painel lateral de uma conversa.
Para deletar um atributo personalizado, use deleteCustomAttribute conforme segue
window.$chatwoot.deleteCustomAttribute("attribute-key");
Definir idioma manualmente
window.$chatwoot.setLocale("en");
Para definir o idioma manualmente, use a função setLocale.
Definir labels na conversa
Note que as labels serão definidas somente se o usuário ainda não iniciou uma conversa. Neste caso, os itens a seguir não terão efeito:
window.$chatwoot.setLabel("support-ticket");
window.$chatwoot.removeLabel("support-ticket");
Atualizar a sessão (use ao deslogar o usuário do seu app)
window.$chatwoot.reset();
Erros do widget
Para identificar erros no widget, certifique-se de escutar o evento chatwoot:event conforme abaixo:
window.addEventListener("chatwoot:error", function () {
// ...
});
Observação: Este recurso está disponível a partir da versão v2.3.0.
Personalizar o cabeçalho de boas-vindas e descrição
Você pode alterar:
-
O título e a descrição de boas-vindas
-
Mensagens exibidas quando sua equipe estiver online ou offline
-
Ativar ou desativar recursos da interface, como envio de arquivos, seleção de emoji e botão de encerrar conversa
window.chatwootSettings = {
welcomeTitle: 'Precisa de ajuda?',
welcomeDescription: 'Estamos aqui para te ajudar.',
availableMessage: 'Estamos online e prontos para conversar!',
unavailableMessage: 'No momento estamos offline.',
enableFileUpload: true,
enableEmojiPicker: true,
enableEndConversation: true
};