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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#sdk-settings "Lien direct vers le titre")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#dark-mode "Lien direct vers le titre")

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](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/live-chat-dark-mode).

### Designs du widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#widget-designs "Lien direct vers le titre")

Chatwoot prend en charge deux designs pour le widget.

1. Standard (par défaut)

   ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeEpVVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cd7e6b995894f8afbcc4a48f8e159ae4e3a1a04b/standard-bubble-chatwoot-live-chatwoot.gif)

2. Bulle élargie

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeE5VVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2b40967d868bb213b2d4e541ca3ed0e82c7222d0/expanded-bubble-chatwoot-live-chatwoot.gif)

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Lien direct vers le titre")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Lien direct vers le titre")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#programatically-open-the-popout-window "Lien direct vers le titre")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#toggle-the-widget-bubble-visibility "Lien direct vers le titre")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-the-user-in-the-widget "Lien direct vers le titre")

```
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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#identity-validation-using-hmac "Lien direct vers le titre")

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é](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/identity-validation). 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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-custom-attributes "Lien direct vers le titre")

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](https://www.chatwoot.com/hc/user-guide/articles/1677502327-how-to-create-and-use-custom-attributes).

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-language-manually "Lien direct vers le titre")

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

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

### Définir des labels sur la conversation[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-labels-on-the-conversation "Lien direct vers le titre")

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)[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#refresh-the-session-use-this-while-you-logout-the-user-from-your-app "Lien direct vers le titre")

```
window.$chatwoot.reset();
```

### Erreurs du widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#widget-errors "Lien direct vers le titre")

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
 };
```