Comment envoyer des informations utilisateur supplémentaires à Chatwoot en utilisant le SDK ?

Le SDK du site web Chatwoot vous permet d'envoyer des informations utilisateur supplémentaires à Chatwoot.

Si vous avez installé notre code sur votre site web, le SDK exposera l'objet window.$chatwoot. Pour vous assurer que le SDK a été complètement chargé, veillez à écouter l'événement chatwoot:ready comme suit :

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

Si vous souhaitez écouter les messages dans le widget, vous pouvez utiliser l'événement suivant.

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

Paramètres du SDK​

Pour masquer la bulle, vous pouvez utiliser le paramètre mentionné ci-dessous.

Remarque : Si vous utilisez ceci, vous devez également déclencher l'ouverture du widget.

window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Désactive la boîte de dialogue des messages non lus
  position: "left", // Peut être left ou right
  locale: "en", // Langue à définir
  useBrowserLanguage: false, // Définir la langue du widget d'après celle du navigateur de l'utilisateur
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "yourdomain.com" // à configurer si vous souhaitez suivre les utilisateurs sur plusieurs sous-domaines
};

Utiliser automatiquement la langue du navigateur dans votre widget de chat en direct

Pour afficher le widget de chat en direct dans la langue du navigateur de l'utilisateur, définissez useBrowserLanguage sur true dans le window.chatwootSettings ci-dessus.

Remarque : Si useBrowserLanguage est activé (true), la valeur de locale spécifiée sera ignorée. Si la langue du navigateur n'est pas supportée par Chatwoot, la locale indiquée sous locale sera utilisée. Si celle-ci est également manquante, le widget utilisera la locale du tableau de bord agent par défaut.

Mode sombre​

Le widget de chat en direct Chatwoot prend en charge le mode sombre à partir de la version v2.4.0. Pour activer le mode sombre, suivez les étapes indiquées ici.

Designs du widget​

Chatwoot prend en charge deux designs pour le widget.

1. Standard (par défaut)

   

2. Bulle élargie

Si vous utilisez la bulle élargie, vous pouvez personnaliser le texte affiché dans la bulle en définissant le paramètre launcherTitle dans chatwootSettings comme indiqué ci-dessous.

window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "Discutez avec nous",
};

Activer la fenêtre popout​

Pour activer la fenêtre popout, ajoutez la configuration suivante dans chatwootSettings. Cette option est désactivée par défaut.

window.chatwootSettings = {
  // ...Autres configurations
  showPopoutButton: true,
}

Vous pouvez également ouvrir la fenêtre popout du chat par programmation avec la méthode `popoutChatWindow()`.

Messages personnalisés​

Personnalisez le message de bienvenue et les messages de disponibilité affichés dans l'en-tête du widget et les indicateurs de statut de l'équipe.

window.chatwootSettings = {
  // ...Autres configurations

  welcomeTitle: "Besoin d'aide ?", // En-tête personnalisé du widget
  welcomeDescription: "Nous sommes là pour vous aider.", // Sous-titre de l'en-tête
  availableMessage: "Nous sommes en ligne et prêts à discuter !", // Lorsque l'équipe est en ligne
  unavailableMessage: "Nous sommes actuellement hors ligne." // Lorsque l'équipe n'est pas disponible
};

Bascule des fonctionnalités

Activez ou désactivez des fonctionnalités UI optionnelles dans le widget :

window.chatwootSettings = {
  // ...Autres configurations

  enableFileUpload: true, // Afficher le bouton de pièce jointe
  enableEmojiPicker: true, // Activer le sélecteur d'emojis dans l'entrée de chat
  enableEndConversation: true // Permettre aux utilisateurs de terminer la conversation
};

Ouvrir la fenêtre popout par programmation​

Vous pouvez ouvrir la fenêtre popout par programmation avec la méthode popoutChatWindow().

Pour cela, appelez la méthode ainsi :

window.$chatwoot.popoutChatWindow();

Afficher ou masquer la bulle du widget​

Si vous souhaitez masquer/afficher la bulle du widget Chatwoot, vous pouvez utiliser toggleBubbleVisibility('show/hide')

Exemple

window.$chatwoot.toggleBubbleVisibility("show"); // pour afficher la bulle
window.$chatwoot.toggleBubbleVisibility("hide"); // pour masquer la bulle

Déclencher le widget par programmation

Si vous souhaitez ouvrir la fenêtre de chat en cliquant sur un lien de votre site web, suivez la méthode ci-dessous. Dans votre action, appelez le SDK Chatwoot comme décrit ci-dessous.

window.$chatwoot.toggle();

// Ouvrir/fermer le widget en passant l'état
window.$chatwoot.toggle("open"); // Pour ouvrir le widget
window.$chatwoot.toggle("close"); // Pour fermer le widget

Définir l'utilisateur dans le widget​

window.$chatwoot.setUser("<unique-identifier-key-of-the-user>", {
  email: "<email-address-of-the-user@your-domain.com>",
  name: "<name-of-the-user>",
  avatar_url: "<avatar-url-of-the-user>",
  phone_number: "<phone-number-of-the-user>",
});

setUser accepte un identifiant qui peut être un user_id dans votre base de données ou tout autre paramètre unique représentant un utilisateur. Vous pouvez passer email, name, avatar_url, phone_number en paramètres. Le support d'autres paramètres supplémentaires est en cours de développement.

Veillez à réinitialiser la session lorsque l'utilisateur se déconnecte de votre application.

Validation d'identité via HMAC​

Pour éviter l'usurpation d'identité et garantir que la conversation avec vos clients reste privée, nous recommandons de configurer la validation d'identité dans Chatwoot. La validation d'identité est activée en générant un HMAC (hash basé sur SHA256) à partir de l'attribut identifier. En plus de l'attribut identifier, vous pouvez aussi transmettre identifier_hash comme ci-dessous pour vous assurer que l'utilisateur est bien le bon.

window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, {
  name: "", // Nom de l'utilisateur
  avatar_url: "", // URL de l'avatar
  email: "", // Email de l'utilisateur
  identifier_hash: "", // Hash de l'identifiant généré depuis le hmac_token du webwidget
  phone_number: "", // Numéro de téléphone
  description: "", // description sur l'utilisateur
  country_code: "", // Code pays à deux lettres
  city: "", // Ville de l'utilisateur
  company_name: "", // nom de l'entreprise
  social_profiles: {
    twitter: "", // Nom d'utilisateur Twitter
    linkedin: "", // Nom d'utilisateur LinkedIn
    facebook: "", // Nom d'utilisateur Facebook
    github: "", // Nom d'utilisateur Github
  },
});

Pour générer le HMAC, lisez validation d'identité. Notez que la mise en œuvre de l'authentification HMAC permettra de conserver l'historique des chats entre les sessions.

Définir des attributs personnalisés​

Pour renseigner des informations supplémentaires à propos du client, vous pouvez utiliser le champ d'attributs personnalisés client. En savoir plus sur les attributs personnalisés ici.

Pour définir un attribut personnalisé, appelez setCustomAttributes comme ceci

window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "paid",

  // Ici la clé existe déjà comme attribut personnalisé
  // La valeur doit correspondre au type (actuellement supporte Number, Date, String et Number)
});

Vous pourrez visualiser ces informations dans le panneau latéral d'une conversation.

Pour supprimer un attribut personnalisé, utilisez deleteCustomAttribute comme ci-dessous

window.$chatwoot.deleteCustomAttribute("attribute-key");

Définir la langue manuellement​

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

Pour définir la langue manuellement, utilisez la fonction setLocale.

Définir des labels sur la conversation​

Veuillez noter que les labels seront affectés à une conversation si l'utilisateur n'a pas encore démarré de conversation. Dans ce cas, les actions suivantes n'auront aucun effet :

window.$chatwoot.setLabel("support-ticket");

window.$chatwoot.removeLabel("support-ticket");

Rafraîchir la session (à utiliser lors de la déconnexion de l'utilisateur depuis votre application)​

window.$chatwoot.reset();

Erreurs du widget​

Pour visualiser les erreurs éventuelles dans le widget, veillez à écouter l'événement chatwoot:error comme ceci :

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

Remarque : Cette fonctionnalité est disponible à partir de la version v2.3.0.

Personnaliser l'en-tête et la description de bienvenue

Vous pouvez modifier :

• Le titre et la description de bienvenue

• Les messages affichés lorsque votre équipe est en ligne ou hors ligne

• Activer sélectivement des fonctions UI comme l'envoi de fichiers, le sélecteur d'emojis et le bouton de fin de conversation

window.chatwootSettings = {
  welcomeTitle: 'Besoin d’aide ?',
  welcomeDescription: 'Nous sommes là pour vous aider.',
  availableMessage: 'Nous sommes en ligne et prêts à discuter !',
  unavailableMessage: 'Nous sommes actuellement hors ligne.',

  enableFileUpload: true,
  enableEmojiPicker: true,
  enableEndConversation: true
 };