Wie kann man zusätzliche Benutzerinformationen mit dem SDK an Chatwoot senden?

Das Chatwoot Website-SDK ermöglicht es Ihnen, zusätzliche Benutzerinformationen an Chatwoot zu übermitteln.

Wenn Sie unseren Code auf Ihrer Website installiert haben, stellt das SDK das Objekt window.$chatwoot bereit. Um sicherzustellen, dass das SDK vollständig geladen ist, achten Sie darauf, auf das Ereignis chatwoot:ready wie folgt zu hören:

window.addEventListener("chatwoot:ready", function () {
  // Verwenden Sie window.$chatwoot hier
  // ...
});

Wenn Sie Nachrichten im Widget mitverfolgen möchten, können Sie folgendes Ereignis nutzen.

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

SDK-Einstellungen​

Um die Sprechblase auszublenden, können Sie die unten stehende Einstellung verwenden.

Hinweis: Wenn Sie dies verwenden, müssen Sie das Widget ebenfalls auslösen.

window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Dialog für ungelesene Nachrichten deaktivieren
  position: "left", // Dies kann 'left' oder 'right' sein
  locale: "en", // Sprache, die festgelegt werden soll
  useBrowserLanguage: false, // Sprache des Widgets aus dem Browser des Nutzers festlegen
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "yourdomain.com" // konfigurieren, falls Sie Nutzer über Subdomains verfolgen möchten
};

Die Browser-Sprache im Live-Chat-Widget automatisch verwenden

Um das Live-Chat-Widget in der Sprache des Browsers des Nutzers anzuzeigen, setzen Sie useBrowserLanguage in den oben erwähnten window.chatwootSettings auf true.

Hinweis: Wenn useBrowserLanguage auf true gesetzt ist, wird die angegebene locale ignoriert. Wenn die vom Browser genutzte Sprache von Chatwoot nicht unterstützt wird, wird die unter locale angegebene Sprache genutzt. Fehlt auch diese, verwendet das Widget die Sprache des Agenten-Dashboards.

Dark Mode​

Das Chatwoot Live-Chat-Widget unterstützt Dark Mode ab Version 2.4.0. Um den Dark Mode zu aktivieren, folgen Sie den Schritten hier.

Widget-Designs​

Chatwoot unterstützt zwei Designs für das Widget.

1. Standard (Voreinstellung)

   

2. Erweiterte Sprechblase

Wenn Sie die erweiterte Sprechblase verwenden, können Sie den Text innerhalb der Sprechblase anpassen, indem Sie den Parameter launcherTitle in chatwootSettings wie unten beschrieben setzen.

window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "Chatten Sie mit uns",
};

Popout-Fenster aktivieren​

Um das Popout-Fenster zu aktivieren, fügen Sie folgende Konfiguration zu chatwootSettings hinzu. Diese Option ist standardmäßig deaktiviert.

window.chatwootSettings = {
  // ...Weitere Einstellungen
  showPopoutButton: true,
}

Sie können das Chatfenster auch programmatisch mit der Methode `popoutChatWindow()` aufpoppen lassen.

Eigene Nachrichten​

Passen Sie die Begrüßungs- und Verfügbarkeitsnachrichten im Widget-Kopfbereich und bei Teamstatus-Anzeige an.

window.chatwootSettings = {
  // ...Weitere Einstellungen

  welcomeTitle: "Brauchen Sie Hilfe?", // Eigener Widget-Kopfbereich
  welcomeDescription: "Wir sind für Sie da.", // Untertitel im Kopfbereich
  availableMessage: "Wir sind online und bereit zum Chatten!", // Wenn das Team online ist
  unavailableMessage: "Wir sind momentan offline." // Wenn das Team nicht verfügbar ist
};

Funktionsschalter

Aktivieren oder deaktivieren Sie optionale UI-Funktionen im Widget:

window.chatwootSettings = {
  // ...Weitere Einstellungen

  enableFileUpload: true, // Dateianhangs-Schaltfläche anzeigen
  enableEmojiPicker: true, // Emoji-Auswahl im Chat-Eingabefeld aktivieren
  enableEndConversation: true // Nutzern erlauben, das Gespräch zu beenden
};

Popout-Fenster programmatisch öffnen​

Sie können das Popout-Fenster programmatisch mit der popoutChatWindow() Methode öffnen.

Um dies zu starten, rufen Sie die Methode wie unten gezeigt auf.

window.$chatwoot.popoutChatWindow();

Sichtbarkeit der Widget-Sprechblase umschalten​

Wenn Sie die Chatwoot Widget-Sprechblase ein- oder ausblenden möchten, können Sie toggleBubbleVisibility('show/hide') verwenden.

Beispiel

window.$chatwoot.toggleBubbleVisibility("show"); // um die Blase anzuzeigen
window.$chatwoot.toggleBubbleVisibility("hide"); // um die Blase auszublenden

Widget programmatisch auslösen

Wenn Sie das Chatfenster durch Klicken auf einen Link auf Ihrer Website öffnen möchten, nutzen Sie die folgende Methode. Rufen Sie bei Ihrer Aktion das Chatwoot SDK wie beschrieben auf.

window.$chatwoot.toggle();

// Widget umschalten durch Übergabe eines Zustands
window.$chatwoot.toggle("open"); // Widget öffnen
window.$chatwoot.toggle("close"); // Widget schließen

Benutzer im Widget festlegen​

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 akzeptiert eine Kennung, die eine user_id in Ihrer Datenbank oder ein beliebiger eindeutiger Parameter sein kann, der einen Benutzer darstellt. Sie können E-Mail, Name, avatar_url, phone_number als Parameter übergeben. Unterstützung für zusätzliche Parameter ist in Arbeit.

Stellen Sie sicher, dass Sie die Sitzung zurücksetzen, wenn sich der Nutzer aus Ihrer App ausloggt.

Identitätsvalidierung mit HMAC​

Um sich vor Identitätsdiebstahl zu schützen und die Unterhaltung mit Ihren Kunden privat zu halten, empfehlen wir, die Identitätsvalidierung in Chatwoot einzurichten. Die Identitätsvalidierung wird durch Erzeugen eines HMAC (hash-basierten Message Authentication Code) basierend auf dem identifier-Attribut mittels SHA256 realisiert. Zusammen mit dem identifier können Sie auch identifier_hash wie unten gezeigt übergeben, um sicherzugehen, dass der Nutzer der richtige ist.

window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, {
  name: "", // Name des Nutzers
  avatar_url: "", // Avatar-URL
  email: "", // E-Mail des Nutzers
  identifier_hash: "", // auf Grundlage des webwidget hmac_token generierter Identifizierungs-Hash
  phone_number: "", // Telefonnummer des Nutzers
  description: "", // Beschreibung zum Nutzer
  country_code: "", // Zweistelliger Ländercode
  city: "", // Stadt des Nutzers
  company_name: "", // Firmenname
  social_profiles: {
    twitter: "", // Twitter-Name
    linkedin: "", // LinkedIn-Nutzername
    facebook: "", // Facebook-Nutzername
    github: "", // Github-Nutzername
  },
});

Zur Generierung des HMAC lesen Sie Identitätsvalidierung. Die Implementierung von HMAC-Authentifizierung erlaubt, dass Chatverläufe über verschiedene Sitzungen hinweg bestehen bleiben.

Benutzerdefinierte Attribute setzen​

Um zusätzliche Informationen über den Kunden zu speichern, können Sie das Feld für benutzerdefinierte Attribute verwenden. Mehr zu benutzerdefinierten Attributen erfahren Sie hier.

Um ein benutzerdefiniertes Attribut zu setzen, rufen Sie setCustomAttributes wie folgt auf

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

  // Hier der Schlüssel, der bereits als benutzerdefiniertes Attribut definiert ist
  // Wert muss entsprechend dem Typ sein (aktuell unterstützt: Number, Date, String und Number)
});

Diese Informationen sind im Seitenpanel einer Konversation sichtbar.

Um ein benutzerdefiniertes Attribut zu löschen, verwenden Sie deleteCustomAttribute wie folgt

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

Sprache manuell festlegen​

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

Um die Sprache manuell zu setzen, nutzen Sie die setLocale-Funktion.

Labels auf der Konversation setzen​

Bitte beachten Sie, dass Labels nur auf eine Konversation gesetzt werden, falls der Nutzer noch keine Konversation begonnen hat. In diesem Fall haben folgende Aktionen keinen Effekt:

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

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

Sitzung aktualisieren (verwenden Sie dies beim Abmelden des Nutzers aus Ihrer App)​

window.$chatwoot.reset();

Widget-Fehler​

Um Fehler im Widget zu sehen, achten Sie darauf, auf das Ereignis chatwoot:event wie folgt zu hören:

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

Hinweis: Diese Funktion ist verfügbar ab v2.3.0.

Begrüßungskopf und -beschreibung anpassen

Sie können Folgendes ändern:

• Den Begrüßungstitel und die Beschreibung

• Nachrichten, wenn Ihr Team online oder offline ist

• UI-Funktionen wie Dateiupload, Emoji-Auswahl und Button zur Gesprächsbeendigung gezielt aktivieren

window.chatwootSettings = {
  welcomeTitle: 'Brauchen Sie Hilfe?',
  welcomeDescription: 'Wir sind für Sie da.',
  availableMessage: 'Wir sind online und bereit zum Chatten!',
  unavailableMessage: 'Wir sind momentan offline.',

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