So greifen Sie auf Benutzerdaten in Zendesk Sunshine Conversations für KI-Agenten zu und verwenden diese

Personalisierte Kundenerlebnisse beginnen damit, zu wissen, mit wem Sie sprechen. Wenn sich ein Kunde an Ihren KI-Agenten wendet, erwartet er mehr als nur generische Antworten. Er möchte, dass Sie seinen Namen kennen, seine Historie verstehen und den Kontext seines Problems kennen. Benutzerdaten in Zendesk Sunshine Conversations machen dies möglich.

Sunshine Conversations dient als Messaging-Schicht unterhalb der KI-Agenten von Zendesk und wickelt alles von WhatsApp-Nachrichten bis hin zu Web-Chats ab. Der Zugriff auf die darin gespeicherten Benutzerdaten erfordert jedoch ein Verständnis der API-Architektur und die Kenntnis der aufzurufenden Endpunkte. Diese Anleitung führt Sie Schritt für Schritt durch das Abrufen und Verwenden von Kundendaten, um personalisiertere KI-Agentenerlebnisse zu schaffen.

Wenn Sie nach einem einfacheren Ansatz suchen, der keine benutzerdefinierten API-Integrationen erfordert, bieten wir eine Alternative. Unsere Plattform verbindet sich direkt mit Zendesk und übernimmt den Zugriff auf Benutzerdaten automatisch. Wenn Sie jedoch benutzerdefinierte Lösungen entwickeln oder die volle Kontrolle über den Datenfluss benötigen, zeigt Ihnen diese technische Anleitung genau, was Sie wissen müssen.

Die Datenarchitektur von Sunshine Conversations verstehen

Sunshine Conversations (ehemals Smooch.io) fungiert als die zugrunde liegende Datenschicht für alle Messaging-Interaktionen in Zendesk. Ursprünglich ein eigenständiges Produkt, ist es jetzt vollständig in die Zendesk Suite integriert und übernimmt die schwere Aufgabe des Routings von Nachrichten zwischen Kunden, KI-Agenten und menschlichen Agenten. Die Plattform bietet eine einheitliche Messaging-API, die mehrere Kanäle mit einer einzigen Konversationsschnittstelle verbindet.

So funktioniert der Datenfluss: Wenn ein Kunde eine Nachricht über WhatsApp, ein Web-Widget oder einen anderen Kanal sendet, empfängt Sunshine Conversations diese Nachricht, identifiziert den Benutzer und leitet sie an den entsprechenden Handler weiter. Ihr KI-Agent interagiert dann mit Sunshine Conversations, um auf Benutzerprofile, Konversationsverlauf und Metadaten zuzugreifen.

Die Plattform speichert Benutzerdaten an verschiedenen Stellen:

Benutzerobjekt (User object): Dieses enthält Kernprofilinformationen, einschließlich der Benutzer-ID, des Namens (profile.surname und profile.givenName), der E-Mail-Adresse, der Gebietsschemaeinstellungen, des Authentifizierungsstatus und des Zeitpunkts der ersten Anmeldung (signedUpAt). Der User API-Endpunkt ermöglicht Ihnen den Zugriff auf all dies.

Clientobjekt (Clients object): Jeder Benutzer kann mehrere "Clients" haben, die verschiedene von ihm verwendete Kanäle darstellen. Ein Kunde kann einen WhatsApp-Client, einen SMS-Client und einen Web-Chat-Client haben. Jeder Client speichert kanalspezifische Daten, einschließlich Telefonnummern für WhatsApp- und SMS-Benutzer.

Konversationsmetadaten (Conversation metadata): Dies sind Kontextdaten, die Sie von Ihrer Website oder Anwendung übergeben, z. B. Seiten-URLs, Bestell-IDs oder benutzerdefinierte Felder. Sie werden auf Konversationsebene gespeichert und können während des Chats abgerufen oder aktualisiert werden.

Teilnehmer (Participants): Jede Konversation hat Teilnehmer, und diese Verknüpfung stellt die Verbindung einer Konversations-ID zu einer bestimmten Benutzer-ID her.

Um mit diesen Daten zu arbeiten, benötigen Sie einige Voraussetzungen: eine Sunshine Conversations-Lizenz (im Lieferumfang von Zendesk Suite Professional und höher enthalten), API-Schlüssel, die im Admin Center erstellt wurden, und das AI Agents Advanced Add-on für die Integration Builder-Funktionen.

Einrichten des API-Zugriffs auf Benutzerdaten

Bevor Sie Benutzerinformationen abrufen können, müssen Sie die Authentifizierung konfigurieren. Sunshine Conversations verwendet ein Zwei-Faktor-System für den API-Zugriff, das Sie einmal einrichten und in allen Ihren API-Aufrufen referenzieren müssen.

Gehen Sie zum Admin Center, navigieren Sie zu Apps und Integrationen, wählen Sie APIs aus und klicken Sie auf Conversations API. Wenn diese Option nicht angezeigt wird, überprüfen Sie, ob Sie Suite Professional oder höher verwenden und ob Agent Workspace aktiviert ist. Detaillierte Einrichtungsanweisungen finden Sie in der Conversations API-Dokumentation.

Klicken Sie auf "API-Schlüssel erstellen" und geben Sie ihm einen beschreibenden Namen wie "KI-Agent-Benutzerdatenzugriff". Das System generiert drei Informationen:

• App-ID (App ID): Diese identifiziert Ihr Zendesk-Konto und erscheint in den meisten API-URLs
• Schlüssel-ID (Key ID): Diese dient als Benutzername für die Basic Authentication
• Geheimer Schlüssel (Secret Key): Dieser dient als Passwort. Kopieren Sie ihn sofort, er wird nur einmal angezeigt

Für API-Integrationen im Integration Builder verwenden Sie die Basic Auth mit der Schlüssel-ID als Benutzernamen und dem geheimen Schlüssel als Passwort. Die App-ID wird in die API-Endpunkt-URLs eingebettet. Sie benötigen alle drei Anmeldeinformationen für jeden API-Aufruf.

Hier ist ein kurzer Tipp: Erstellen Sie separate API-Schlüssel für Entwicklungs- und Produktionsumgebungen. Der Integration Builder unterstützt mehrere Umgebungen, sodass Sie verschiedene Anmeldeinformationen für Tests und Live-Nutzung konfigurieren können. Sie können bis zu 10 Schlüssel speichern, sodass genügend Platz ist, um sie nach Anwendungsfall zu organisieren. Es lohnt sich, dies frühzeitig einzurichten, damit Sie beim Testen nicht versehentlich Live-Daten ändern.

Abrufen von Benutzerprofildaten

Das Abrufen von Benutzerdaten erfordert einen zweistufigen API-Prozess, da Sunshine Conversations seine Datenmodellstruktur so aufgebaut hat. Zuerst müssen Sie die Benutzer-ID finden, die der aktuellen Konversation zugeordnet ist. Dann verwenden Sie diese Benutzer-ID, um das vollständige Profil abzurufen.

Schritt 1: Teilnehmer auflisten, um die Benutzer-ID zu erhalten

Jede Konversation hat eine eindeutige ID, die automatisch generiert wird, wenn der Chat beginnt. In KI-Agenten Advanced ist diese als Systemparameter namens platformConversationId verfügbar. Sie verwenden diese, um den Endpunkt Teilnehmer auflisten aufzurufen.

Erstellen Sie eine API-Integration im Integration Builder mit diesen Einstellungen:

• Methodentyp: GET
• URL: https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/conversations/{{platformConversationId}}/participants

Die Antwort enthält ein Array von Teilnehmern. Für eine typische Kundenkonversation erhalten Sie ein Teilnehmerobjekt, das die benötigte userId enthält. Verwenden Sie diese JSONata-Abfrage, um sie zu extrahieren: data.participants.userId

Schritt 2: Benutzerdetails von der User API abrufen

Nachdem Sie die userId haben, erstellen Sie eine zweite API-Integration, um das vollständige Benutzerprofil abzurufen:

• Methodentyp: GET
• URL: https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}

Die Antwort enthält ein umfassendes Benutzerobjekt. Hier sind die wichtigsten Felder, die Sie mit JSONata-Abfragen extrahieren können:

Schritt 3: Verwenden Sie die Daten in Ihren Bot-Abläufen

Speichern Sie diese Werte als Sitzungsparameter im Integration Builder und referenzieren Sie sie dann in Ihrem Dialog mit doppelten geschweiften Klammern wie {{givenName}}. Sie können sie auch in bedingter Logik verwenden, z. B. {{authenticated}} überprüfen, um verschiedene Abläufe für authentifizierte Benutzer im Vergleich zu Gastbenutzern anzuzeigen.

Ein Muster, das gut funktioniert: Erstellen Sie eine "Chat gestartet"-Ereignisaktion, die beide API-Aufrufe automatisch ausführt, wenn eine Konversation beginnt. Dadurch wird sichergestellt, dass Benutzerdaten verfügbar sind, bevor der Kunde seine erste Nachricht sendet, wodurch personalisierte Begrüßungen von Anfang an möglich sind.

Zugriff auf kanalspezifische Daten (WhatsApp, SMS und mehr)

Das Benutzerobjekt liefert Ihnen Profilinformationen, aber was ist mit kanalspezifischen Details wie Telefonnummern? Hier kommt die Clients API ins Spiel. Dieser Endpunkt zeigt, über welche Kanäle ein Benutzer verbunden ist, und liefert kanalspezifische Kennungen.

Warum die Clients API wichtig ist

Wenn ein Kunde Sie über WhatsApp kontaktiert, wird seine Telefonnummer nicht im Hauptbenutzerobjekt gespeichert. Stattdessen befindet sie sich im Clients-Array als Teil seines WhatsApp-Clientdatensatzes. Dies ist entscheidend für Anwendungsfälle wie:

• Nachschlagen von Kundenbestellungen anhand der Telefonnummer in Ihrem CRM
• Senden von Follow-up-SMS-Nachrichten
• Identifizieren wiederkehrender Kunden über verschiedene Telefonnummern hinweg
• Überprüfen der Benutzeridentität durch Telefonabgleich

Abrufen von Clientdaten

Erstellen Sie eine API-Integration, die Folgendes aufruft:

• Methodentyp: GET
• URL: https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}/clients

Die Antwort enthält ein Array von Clientobjekten, die jeweils eine andere Kanalverbindung darstellen. Für WhatsApp-Benutzer sehen Sie etwa Folgendes:

{
  "type": "whatsapp",
  "externalId": "1234567890",
  "displayName": "Sarah Johnson",
  "raw": {
    "from": "+15551234567"
  },
  "linkedAt": "2024-01-15T10:30:00.000Z"
}

Extrahieren der WhatsApp-Telefonnummer

Verwenden Sie diese JSONata-Abfrage, um die Telefonnummer zu erhalten: data.clients[type="whatsapp"].raw.from

Sie können dieses Muster für andere Kanäle anpassen. Ändern Sie für SMS-Benutzer den Typfilter: data.clients[type="sms"].raw.from

Eine praktische Anwendung: Speichern Sie diese Telefonnummer als Sitzungsparameter und verwenden Sie sie dann in einem nachfolgenden API-Aufruf an Ihr CRM, um den Bestellverlauf des Kunden nachzuschlagen. Wenn der KI-Agent sie mit Namen begrüßt und sagt: "Ich sehe, Sie haben eine Bestellung von letzter Woche", fühlt sich das Erlebnis wirklich persönlich an.

Übergeben benutzerdefinierter Daten über Konversationsmetadaten

Manchmal müssen Sie Informationen von Ihrer Website oder Anwendung in die Konversation übergeben. Vielleicht ist es die Seiten-URL, auf der der Kunde auf Hilfe geklickt hat, seine Bestell-ID aus dem Checkout-Ablauf oder seine Abonnementstufe. Sunshine Conversations verarbeitet dies über Metadaten.

Übergeben von Daten aus dem Web Widget

Wenn Sie das Web Widget von Zendesk verwenden, können Sie beim Start der Konversation benutzerdefinierte Daten anhängen:

zE("messenger:set", "conversationFields", [
  { id: "7662882404114", value: "Premium Plan" }
])

Diese Daten erscheinen in den Konversationsmetadaten mit einem Schlüssel im Format zen:ticket_field:7662882404114, wobei die Zahl Ihre benutzerdefinierte Feld-ID ist. Die wichtigste Voraussetzung: Das benutzerdefinierte Feld muss in Zendesk vom Endbenutzer bearbeitbar sein.

Abrufen von Metadaten in KI-Agenten

Erstellen Sie im Integration Builder eine Aktion mit den CRM-Aktionen mit:

• Ziel: Sunshine Conversations
• Aufgabe: Konversationsmetadaten abrufen
• Rufen Sie das Metadatenobjekt ab und extrahieren Sie bestimmte Schlüssel

Referenzieren Sie den vollständigen Schlüsselnamen einschließlich des Präfixes zen:ticket_field:, wenn Sie Ihre Parameterzuordnung einrichten. Der Wert, den Sie vom Widget übergeben haben, ist jetzt als Sitzungsparameter in Ihrem Dialog verfügbar.

Festlegen von Metadaten von KI-Agenten

Sie können Metadaten auch während der Konversation aktualisieren. Dies ist nützlich, wenn der KI-Agent Informationen sammelt, die im Zendesk-Ticket erscheinen sollen, wenn es an einen menschlichen Agenten eskaliert wird.

Erstellen Sie eine Aktion, bei der die Aufgabe auf "Konversationsmetadaten aktualisieren" gesetzt ist. Verwenden Sie dasselbe Schlüsselformat (zen:ticket_field:FIELD_ID) und übergeben Sie Ihren Parameter als Wert. Wenn die Konversation an Agent Workspace eskaliert wird, wird dieses benutzerdefinierte Feld vorausgefüllt.

Ein paar Dinge, die Sie beachten sollten: Übergeben Sie für Dropdown-Felder den Tag-Wert anstelle des Anzeigenamens. Übergeben Sie für Nachschlagefelder die ID des zugehörigen Datensatzes. Systemfelder wie Betreff oder Status können mit dieser Methode nicht aktualisiert werden, sondern nur benutzerdefinierte Felder.

Praktische Implementierungsbeispiele

Lassen Sie uns dies anhand einiger realer Szenarien in die Praxis umsetzen.

Personalisierte Begrüßung mit Fallback

Richten Sie Ihr "Chat gestartet"-Ereignis so ein, dass es eine API-Integration auslöst, die den Vornamen des Benutzers abruft. Speichern Sie ihn als {{givenName}}. Schreiben Sie in Ihre Willkommensnachricht: "Hallo {{givenName}}, wie kann ich Ihnen heute helfen?"

Aber was, wenn der Name fehlt? Fügen Sie eine bedingte Prüfung hinzu. Wenn {{givenName}} leer ist, verzweigen Sie zu einer Nachricht, die besagt: "Hallo, wie kann ich Ihnen heute helfen?" Dies verhindert unangenehme Leerstellen in Ihren Begrüßungen.

CRM-Nachschlagen für Bestellhistorie

Kombinieren Sie die Clients API mit Ihrer eigenen CRM API. Rufen Sie zuerst die WhatsApp-Nummer mit data.clients[type="whatsapp"].raw.from ab. Erstellen Sie dann eine zweite API-Integration, die den Nachschlageendpunkt Ihres CRM aufruft und diese Telefonnummer als Parameter übergibt.

Wenn das CRM Bestelldaten zurückgibt, extrahieren Sie wichtige Details wie die aktuelle Bestellnummer und den Status. Jetzt kann Ihr KI-Agent sagen: "Ich sehe, Sie haben Bestellung #12345 von gestern. Rufen Sie deswegen an?"

Authentifizierte Benutzerabläufe

Verwenden Sie das Feld authenticated aus der User API, um verschiedene Erlebnisse anzuzeigen. Authentifizierte Benutzer erhalten möglicherweise Zugriff auf kontospezifische Aktionen wie "Meinen Bestellstatus überprüfen" oder "Mein Abonnement aktualisieren". Gastbenutzer sehen ein eingeschränkteres Menü, das sich auf allgemeine Hilfethemen konzentriert.

Der Authentifizierungsstatus ist besonders nützlich für sicherheitssensible Aktionen. Bevor Sie eine Rückerstattung oder Kontoänderung bearbeiten, überprüfen Sie, ob {{authenticated}} gleich true ist und ob die E-Mail-Identitätsüberprüfung Ihren Anforderungen entspricht.

Fehlerbehebung bei häufigen Problemen

Auch mit der richtigen Einrichtung funktioniert nicht immer alles perfekt. Hier sind die häufigsten Probleme und wie Sie sie beheben können.

Benutzer-ID nicht gefunden: Wenn Ihr Aufruf Teilnehmer auflisten leer zurückgibt, überprüfen Sie, ob platformConversationId tatsächlich übergeben wird. Überprüfen Sie Ihr Integration Builder-Testpanel, um zu sehen, welche Werte zur Laufzeit verfügbar sind. Die Konversation muss vorhanden sein, bevor Sie ihre Teilnehmer auflisten können.

API-Authentifizierungsfehler: Überprüfen Sie Ihr Basic Auth-Headerformat. Es sollte Base64-codiert KeyID:Secret sein. Ein häufiger Fehler ist das Vertauschen der Schlüssel-ID und der App-ID oder das Vergessen, die App-ID in den URL-Pfad aufzunehmen.

Fehlende Clientdaten: Nicht alle Kanäle füllen das Clients-Array mit denselben Feldern. WhatsApp enthält in der Regel Telefonnummern, Web-Chat-Clients jedoch möglicherweise nicht. Überprüfen Sie die kanalspezifische Dokumentation, um zu verstehen, was verfügbar ist.

Metadaten erscheinen nicht in Agent Workspace: Stellen Sie sicher, dass Ihr benutzerdefiniertes Feld vom Endbenutzer bearbeitbar ist. Überprüfen Sie auch das genaue Schlüsselnamenformat, es muss zen:ticket_field:12345 ohne zusätzliche Leerzeichen oder Variationen sein. Die Feld-ID muss genau übereinstimmen.

Sitzungsparameter leer: Überprüfen Sie die Reihenfolge der Operationen in Ihrem Dialog. API-Integrationen müssen ausgeführt werden, bevor Sie versuchen, ihre Ausgabeparameter zu verwenden. Wenn Sie Parameter von einem API-Aufruf in einem nachfolgenden Aufruf verwenden, überprüfen Sie, ob der erste erfolgreich abgeschlossen wurde.

Ratenbegrenzung (Rate limiting): Sunshine Conversations hat Ratenbegrenzungen pro Konto. Wenn Sie 429-Fehler erhalten, implementieren Sie exponentielles Backoff in Ihrer Wiederholungslogik oder cachen Sie Benutzerdaten, um wiederholte Suchvorgänge für dieselbe Konversation zu reduzieren.

Vereinfachen des Benutzerdatenzugriffs mit eesel AI

Alles, was wir behandelt haben, funktioniert gut, wenn Sie über Entwicklerressourcen und Zeit verfügen, um benutzerdefinierte Integrationen zu erstellen. Aber nicht jedes Team hat das. Wenn Sie KI-gestützten Support ohne Engineering-Overhead benötigen, gibt es einen einfacheren Weg.

Wir haben eesel AI speziell für Teams entwickelt, die ausgefeilte KI-Agentenfunktionen ohne Erstellung benutzerdefinierter API-Integrationen wünschen. Anstatt Integration Builder-Workflows zu erstellen und API-Anmeldeinformationen zu verwalten, verbinden Sie eesel direkt über einen einfachen OAuth-Ablauf mit Ihrem Zendesk-Konto.

Hier ist der Unterschied im Ansatz. Bei der Sunshine Conversations API-Methode erstellen Sie die Infrastruktur: Erstellen von API-Schlüsseln, Schreiben von JSONata-Abfragen, Behandeln von Fehlerszenarien und Warten der Integration im Laufe der Zeit. Bei unserem Ansatz ist diese Infrastruktur bereits aufgebaut. Sie konzentrieren sich auf die Konfiguration des KI-Verhaltens, während wir uns um die Datenleitungen kümmern.

Wenn Sie eesel mit Zendesk verbinden, greifen wir automatisch auf Benutzerprofile, Ticketverlauf und benutzerdefinierte Felder zu, ohne dass Sie separate API-Aufrufe erstellen müssen. Sie definieren Eskalationsregeln in einfachem Deutsch wie "Wenn der Kunde ein Abrechnungsproblem erwähnt, leiten Sie ihn an das Finanzteam weiter", anstatt komplexe bedingte Logik im Integration Builder zu erstellen.

Wenn Sie hochgradig benutzerdefinierte Lösungen mit eindeutigen Kanalanforderungen oder komplexer Multi-System-Orchestrierung erstellen, bietet Ihnen der Sunshine Conversations API-Ansatz die Flexibilität, die Sie benötigen. Wenn Ihr Ziel jedoch darin besteht, KI-gestützten Kundensupport schnell und ohne Engineering-Ressourcen bereitzustellen, übernimmt unsere Zendesk-Integration die Komplexität für Sie.

Beginnen Sie mit dem Aufbau personalisierter KI-Agentenerlebnisse

Sie haben jetzt das vollständige Bild für den Zugriff auf Benutzerdaten in Zendesk Sunshine Conversations. Die Architektur umfasst drei Hauptdatenquellen: die User API für Profilinformationen, die Clients API für kanalspezifische Details wie Telefonnummern und Konversationsmetadaten für benutzerdefinierten Kontext aus Ihren Anwendungen.

Das Implementierungsmuster ist über alle Anwendungsfälle hinweg konsistent: Erstellen Sie API-Integrationen im Integration Builder, verwenden Sie JSONata, um die benötigten Felder zu extrahieren, speichern Sie sie als Sitzungsparameter und referenzieren Sie diese Parameter in Ihren Dialogabläufen. Mit dem zweistufigen Prozess, zuerst Teilnehmer und dann Benutzerdetails abzurufen, können Sie auf alles zugreifen, von grundlegenden Namen bis hin zu WhatsApp-Telefonnummern.

Bevor Sie mit dem Aufbau beginnen, prüfen Sie, welche Benutzerdaten Sie tatsächlich benötigen. Es ist leicht, sich von der Erfassung aller verfügbaren Felder mitreißen zu lassen, aber konzentrieren Sie sich auf die Daten, die das Kundenerlebnis wirklich verbessern. Eine personalisierte Begrüßung mit dem Vornamen des Kunden hat mehr Wirkung als die Anzeige seiner internen Benutzer-ID.

Wenn Sie bereit sind, zu implementieren, aber Bedenken hinsichtlich des Entwicklungsaufwands haben, probieren Sie unsere Plattform zusammen mit Ihrer Zendesk-Einrichtung aus. Sie können Ansätze vergleichen und auswählen, was für die Fähigkeiten und den Zeitplan Ihres Teams am besten geeignet ist.