Nutzer-Verifizierung für eingeloggte Kunden

Wofür du sie brauchst

Am meisten braucht das ein Chat in einem Kunden-Dashboard, einem Mitgliederbereich oder deiner App. Dort sind deine Kunden schon eingeloggt. Sie noch einmal nach Name und E-Mail zu fragen, ergibt keinen Sinn, und dein Team will sicher wissen, wer schreibt. Mit der Nutzer-Verifizierung:

• Chattet der Kunde unter seinem echten Namen und seiner E-Mail. Das Formular vor dem Chat und die Frage nach der E-Mail entfallen.
• Landet jeder Besuch, auf jedem Gerät, beim selben Kontakt. Dein Team sieht also sofort frühere Konversationen, Notizen und Attribute.
• Zeigt ein Häkchen neben dem Namen, in der Konversation und auf der Kontaktseite, dass die Identität bestätigt ist. Fährst du mit der Maus darüber, steht dort Identität bestätigt.
• Kann sich niemand als einer deiner Kunden ausgeben. Das Widget akzeptiert eine Identität nur mit einer Signatur von deinem Server, und nur dein Server kennt den Schlüssel. Deskwoot prüft die Signatur ganz ohne Zugriff auf deine Systeme.

Schritt 1: Erstelle deinen geheimen Schlüssel

1. Geh zu Einstellungen > Posteingänge und öffne deinen Live-Chat-Posteingang.
2. Klicke unter Einbau und Datenschutz auf Eingeloggte Kunden erkennen.
3. Klicke unter Geheimer Schlüssel auf Schlüssel erstellen. Deskwoot erstellt den Schlüssel und zeigt ihn sofort an.
4. Klicke auf Kopieren und speichere den Schlüssel auf deinem Server, zum Beispiel als Umgebungsvariable mit dem Namen DESKWOOT_IDENTITY_SECRET.

Ab dann zeigt die Zeile Eingerichtet. Du kannst jederzeit zurückkommen: Anzeigen zeigt den Schlüssel wieder, und Kopieren kopiert ihn. Jeder Live-Chat-Posteingang hat seinen eigenen Schlüssel, und eine Signatur damit gilt nur für das Widget dieses Posteingangs.

Der Schlüssel gehört nur auf deinen Server. Leg ihn nie in Code, der im Browser läuft, und berechne die Signatur nie dort. Wer den Schlüssel hat, kann sich als jeder deiner Kunden ausgeben.

Schritt 2: Signiere die Nutzer-ID auf deinem Server

Für jeden eingeloggten Kunden berechnet dein Server einen HMAC SHA256 seiner Nutzer-ID mit dem geheimen Schlüssel und schreibt ihn als Hex. Dieser Wert ist der identifierHash. Nimm eine Nutzer-ID, die sich nie ändert, etwa die ID aus deiner Datenbank, und verwende den Schlüssel genau so, wie Deskwoot ihn zeigt, als Text.

Node.js:

import crypto from "crypto";

const identifierHash = crypto
  .createHmac("sha256", process.env.DESKWOOT_IDENTITY_SECRET)
  .update(userId)          // your stable user id, as a string
  .digest("hex");

Python:

import hashlib, hmac, os

identifier_hash = hmac.new(
    os.environ["DESKWOOT_IDENTITY_SECRET"].encode(),
    user_id.encode(),
    hashlib.sha256,
).hexdigest()

PHP:

$identifierHash = hash_hmac("sha256", $userId, getenv("DESKWOOT_IDENTITY_SECRET"));

Das Ergebnis ist immer 64 Zeichen lang. Das Panel in Deskwoot zeigt das Node.js-Beispiel ebenfalls, unter Schritt 1: auf deinem Server.

Schritt 3: Gib den Nutzer an das Widget weiter

Ergänze im Widget-Code auf deiner Seite ein user-Objekt in window.deskwootSettings. Dein Server trägt die Werte ein, wenn er die Seite für einen eingeloggten Kunden baut.

window.deskwootSettings = {
  widgetToken: "YOUR_WIDGET_TOKEN",
  user: {
    identifier: "user_4711",            // your stable user id
    identifierHash: "<HMAC-SHA256 of identifier, computed on your server>",
    email: "jane@example.com",          // optional
    name: "Jane Doe"                    // optional
  }
};

• identifier: deine stabile Nutzer-ID, als Text. Sie ist das einzige signierte Feld, sende also genau den Text, den du signiert hast. Auch eine Zahl steht in Anführungszeichen, etwa "4711". Höchstens 128 Zeichen.
• identifierHash: die Signatur aus Schritt 2.
• email und name: optional. Sie erscheinen am Kontakt in Deskwoot.
• attributes: optionale Angaben wie ein Tarif, siehe unten bei „Sende weitere Angaben mit Attributen“.

Für Besucher, die nicht eingeloggt sind, lässt du user weg: Sie chatten wie bisher als anonyme Besucher. Das Panel in Deskwoot zeigt diesen Code mit deinem eigenen Widget-Token, unter Schritt 2: auf deiner Seite. Ist das Widget noch nicht auf deiner Website, fang mit Das Widget einbinden an.

Wenn deine App Nutzer erst nach dem Laden einloggt

In einer App, die den Kunden einloggt, ohne eine neue Seite zu laden, rufst du window.deskwoot.identify(user) mit demselben Objekt auf, sobald dein Server es signiert hat. Das aktualisiert den aktuellen Besucher ohne Neuladen.

window.deskwoot.identify({
  identifier: "user_4711",
  identifierHash: "<HMAC-SHA256 of identifier, computed on your server>",
  email: "jane@example.com",
  name: "Jane Doe"
});

Ist der Kunde beim Laden der Seite schon eingeloggt, setz stattdessen user in window.deskwootSettings vor dem Widget-Code. Dann bleibt der Chat über jedes Neuladen hinweg offen. Mit identify() nach dem Laden startet jedes Neuladen mit einem leeren Chat, der zurückkommt, sobald der Kunde verifiziert ist.

Sende weitere Angaben mit Attributen

Mit attributes kannst du eine flache Liste von Angaben senden, etwa { plan: "Pro" } oder eine Firmen-ID. Sie erscheinen für dein Team am Kontakt.

Die Signatur deckt nur die Nutzer-ID ab, ein Besucher könnte diese Attribute im Browser also ändern. Deshalb liest der KI-Bot nie Attribute, die nicht signiert sind. Damit die KI daraus antworten darf, signiere sie ebenfalls auf deinem Server und sende attributesHash und attributesIssuedAt (die Unix-Zeit in Sekunden, zu der du sie signiert hast) mit. Außerdem liest die KI sie nur, wenn sie Kontakte nachsehen darf. Signiere bei jedem Seitenaufruf neu: Deskwoot verwendet eine signierte Menge bis zu 24 Stunden lang. Signiere nur, was der Kunde sehen darf, denn die KI kann ihm sagen, was in einem signierten Attribut steht.

Das genaue Format, mit Code für Node.js und Python und einem Testvektor, mit dem du deinen Code prüfen kannst, steht in der Widget-Dokumentation.

Ohne Nutzer-Verifizierung oder mit falscher Signatur

• Kein user in den Einstellungen: Der Besucher chattet anonym, und das Formular vor dem Chat und die Frage nach der E-Mail erscheinen so, wie du sie unter Vor dem Chat eingerichtet hast.
• Falsche Signatur: Deskwoot lehnt die Identität ab. Der Chat funktioniert weiter, aber der Kunde chattet als anonymer Besucher und sieht das Formular vor dem Chat, falls du eins nutzt. Eine Fehlermeldung sieht der Kunde nicht. Genauso läuft es, wenn der Posteingang noch keinen Schlüssel hat, wenn die Nutzer-ID nicht genau der Text ist, den du signiert hast, wenn sie länger als 128 Zeichen ist oder wenn die E-Mail-Adresse nicht gültig ist.
• Neuer Schlüssel: Klickst du auf Neuen Schlüssel erstellen und bestätigst mit Ja, neuen Schlüssel erstellen, funktioniert der alte Schlüssel sofort nicht mehr. Bis du den neuen auf deinem Server einträgst, werden eingeloggte Kunden nicht erkannt.
• Signierte Attribute: Ein falscher attributesHash lässt die ganze Identität scheitern, wie eine falsche Signatur, und ebenso eine signierte Menge über den Grenzen (30 Schlüssel, Schlüssel bis 64 Zeichen, Werte bis 1024 Zeichen). Eine signierte Menge, die älter als 24 Stunden ist, dagegen nicht: Der Kunde ist trotzdem verifiziert, nur diese Attribute werden ignoriert.

Um die Ursache zu finden, öffne die Entwicklertools deines Browsers, geh in den Tab Netzwerk und sieh dir die Antwort auf die Anfrage an /api/widget/identity/verify an. invalid_identifier_hash heißt, dass die Signatur nicht zur Nutzer-ID passt, und identity_verification_not_configured, dass der Posteingang noch keinen Schlüssel hat.

Häufige Fragen

Brauche ich die Nutzer-Verifizierung, damit der Chat funktioniert?

Nein. Sie ist optional. Ohne sie chatten alle als anonyme Besucher und füllen das Formular vor dem Chat aus, falls du eins nutzt. Die Nutzer-Verifizierung sorgt nur zusätzlich dafür, dass eingeloggte Kunden erkannt werden.

Kann ich den geheimen Schlüssel ins JavaScript meiner Seite schreiben?

Nein. Alles im Browser kann jeder lesen, und wer den Schlüssel hat, kann sich als jeder deiner Kunden ausgeben. Behalte den Schlüssel auf deinem Server und schick nur die fertige Signatur an die Seite.

Was nehme ich als Nutzer-ID?

Eine ID, die sich für diesen Kunden nie ändert, etwa die ID des Nutzers in deiner Datenbank. Deskwoot findet den Kontakt bei jedem Besuch über diese ID, eine neue ID bedeutet also einen neuen Kontakt. Eine E-Mail-Adresse eignet sich weniger, weil Leute sie ändern.

Ordnet Deskwoot einen verifizierten Kunden über die E-Mail zu?

Nein. Deskwoot ordnet einen verifizierten Kunden nur über die Nutzer-ID zu, die du signiert hast. E-Mail und Name sind nicht signiert, deshalb hängt Deskwoot einen Besucher nie wegen ihnen an einen bestehenden Kontakt. Hat schon ein anderer Kontakt diese E-Mail-Adresse, wird der verifizierte Kontakt ohne sie gespeichert.

Gilt ein Schlüssel für alle meine Posteingänge?

Nein. Jeder Live-Chat-Posteingang hat seinen eigenen Schlüssel, und eine Signatur damit funktioniert nur für das Widget dieses Posteingangs. Hast du das Widget von 2 Posteingängen auf deinen Websites, erstelle in jedem einen Schlüssel und signiere mit dem Schlüssel des Posteingangs, dessen Widget auf der Seite ist.

Wo sieht mein Team, dass ein Kunde verifiziert ist?

An einem Häkchen neben dem Namen des Kunden, in der Konversation und auf der Kontaktseite. Fährst du mit der Maus darüber, steht dort Identität bestätigt.