Verwenden von Messaging-Metadaten mit Zendesk Web Widget und SDKs

Welchen Plan habe ich

Suite

Beliebiger Plan

Messaging-Metadaten sind zusätzliche Informationen zu einer Supportanfrage oder zu dem betreffenden Produkt bzw. Service, die mithilfe von Konversationsfeldern und Konversationsstichwörtern (auch angepasste Ticketfelder und angepasste Ticketstichwörter genannt) erfasst werden. Sie können diese Metadaten auch im Admin Center zum Erstellen von Auslösern verwenden, um die Ticketverteilung im Arbeitsbereich für Agenten zu verbessern. Sie können Messaging-Metadaten zu Tickets hinzufügen und in das Supportanfrageformular Ihres Help Centers aufnehmen, damit die angepassten Felder für Endbenutzer sichtbar sind.

Sie können Konversationsfelder und -stichwörter auch verwenden, um Messaging-Metadaten vom Web Widget und den Zendesk SDKs über clientseitige APIs an Agenten zu senden. Auf diese Weise lassen sich relevante Informationen wie Artikel-, Bestätigungs- oder Auftragsnummern automatisch an Agenten übermitteln. Diese zusätzlichen Metadaten tragen dazu bei, den Support durch die Bereitstellung umfassender Kontextinformationen zu verbessern.

Messaging-Metadaten bieten folgende Vorteile:

• Besserer Kontext für Agenten. Agenten sind darauf angewiesen, dass in ihrer Ansicht im Arbeitsbereich für Agenten korrekte Kontextinformationen angezeigt werden. Fehlende oder vom Endbenutzer eingegebene Daten können zu Fehlern führen. Indem Sie relevante Informationen programmgesteuert bereitstellen, können Sie Fehler und unnötige Rückfragen vermeiden.
• Verbesserte Verteilung. Unternehmen benötigen Informationen in Ticketfeldern und Stichwörtern, damit Tickets schnell an die richtige Agentengruppe weitergeleitet werden können. Je umfassender die bereitgestellten Daten sind, desto effizienter kann das Ticket an die richtige Agentengruppe übergeben werden.
• Optimales Endbenutzerlebnis. Endbenutzer brauchen im Client bereits verfügbare Daten nicht erneut einzugeben.
• Verbesserte Automatisierungsabläufe. Bot-Entwickler können die zusätzlichen Daten für ein besseres Endbenutzererlebnis nutzen.
• Funktionsparität mit den Classic Web Widgets Support SDKs, die Ticketfelder und -stichwörter unterstützen.

Dieser Beitrag enthält die folgenden Themen:

• Überblick über Messaging-Metadaten
• Konfigurieren für Messaging-Metadaten
• Hinzufügen eines Konversationsfelds
• Verwenden der Metadata APIs
• Bot-Builder (Legacy AI Agents)

Überblick über Messaging-Metadaten

Angenommen, Sie betreiben einen Onlineshop, in dem sich ein Endbenutzer einen bestimmten Schuh ansieht. Auf der betreffenden Seite werden die Artikelnummer sowie die erhältlichen Größen und Farbvarianten angezeigt. Wenn der Endbenutzer Fragen zu diesem Schuh hat, muss er die genannten Informationen angeben, damit der Agent weiß, für welchen Schuh er sich interessiert. Ohne angepasste Ticketfelder muss der Live-Agent bzw der AI Agent den Endbenutzer erst um diese Informationen bitten, bevor er seine Frage beantworten kann.

Mit Messaging-Metadaten können Sie solche Daten programmgesteuert von der Webseite abrufen bzw. vom Endbenutzer in ein Formular eintragen lassen. Zum Beispiel können Sie mit einem angepassten Ticketfeld die Artikelnummer per API von der Produktseite abrufen. Da der Endbenutzer die Farbe und Größe möglicherweise noch nicht ausgewählt hat, kann zum Beispiel ein AI Agent diese Daten mithilfe angepasster Ticketfelder abfragen und die entsprechenden Standardwerte anzeigen. Der Endbenutzer kann diese dann aktualisieren oder übernehmen.

Im Gegensatz zu Variablen und angepassten Feldern in AI Agent-Standardantworten oder im Bot-Builder (Legacy) bieten Messaging-Metadaten deutlich mehr Möglichkeiten:

• Endbenutzer brauchen Daten, die sie auf der Webseite bereits eingegeben haben, nicht erneut manuell einzugeben. Wenn sich ein Endbenutzer beispielsweise in einem Rücksendeformular befindet, in dem die Auftragsnummer bereits angezeigt wird, können Sie diese Nummer programmgesteuert abrufen, statt sie vom Endbenutzer anzufordern.
• Zur Unterstützung des Agenten kann automatisch zusätzlicher Kontext hinzugefügt werden. So können Sie beispielsweise dafür sorgen, dass ein Konversationsfeld „Einkaufswagen aktiv“ auf „Wahr“ gesetzt wird, wenn ein Endbenutzer den Einkaufswagen geöffnet hat.
• Sie können steuern, welchem Pfad ein AI Agent folgen soll. Wenn sich ein Endbenutzer beispielsweise auf einer Seite der Marke A befindet, können Sie durch eine entsprechende Einstellung in einem Feld dafür sorgen, dass der Bot den für die Marke A vorgesehenen Pfad durchläuft.

Konfigurieren für Messaging-Metadaten

Konversationsfelder müssen im Admin Center so konfiguriert werden, dass ihre Werte beim Erstellen der Felder von einem Endbenutzer festgelegt werden können. Konversationsstichwörter müssen für die Verwendung der Metadata API nicht extra vorbereitet werden.

Als Erstes müssen Sie festlegen, welche Daten Sie sammeln möchten und wie sie verwendet werden sollen. Das hängt ganz von Ihrem Anwendungsfall ab. Sie müssen genau wissen, wie das Endbenutzererlebnis aussieht, wenn Ihr Entwickler die Werte für Ticketfelder und -stichwörter im Zendesk Web Widget und den SDKs programmgesteuert festlegt.

Nachdem Sie mit Ihren Daten vertraut sind, werden die folgenden Schritte ausgeführt:

1. Ein Zendesk-Administrator erstellt ein angepasstes Ticketfeld und übergibt den Namen und die ID des Felds zusammen mit der Verwendung und den zu erfassenden Daten an einen Entwickler.
2. Der Entwickler kodiert den Aufruf der Metadata API mit der Feld-ID, um den Wert mit dem Feld zu verbinden.
3. Die Daten werden zur Laufzeit programmgesteuert in der Metadata API gesetzt und sind in der nächste Sitzung verfügbar.
4. Die Ticketfeld- und Ticketstichwortdaten werden dem Support-Ticket zum Zeitpunkt der Ticketerstellung hinzugefügt.

Hinweis: Messaging-Metadaten werden nur auf ein Ticket angewendet. Wenn zu einer laufenden Konversation ein weiteres Ticket erstellt wird, werden die Messaging-Metadaten nur auf das erste Ticket angewendet.

Die Metadaten für Ticketfelder und -stichwörter werden bei der Ticketerstellung festgelegt. Wenn Sie Ihr Widget beispielsweise so konfigurieren, dass Kunden direkt mit einem Live-Agenten (und nicht mit einem AI Agent) chatten, wird beim Öffnen des Widgets sofort ein neues Ticket erstellt; nur die Ticketfelder und -stichwörter, die vor Erstellung des Tickets festgelegt wurden, werden zum Ticket hinzugefügt.

Beim Schließen eines Tickets werden die Messaging-Metadaten im Backend (beispielsweise in Tickets) auf einen leeren Nullzustand zurückgesetzt. Derzeit bleiben Messaging-Metadaten auf der Clientseite erhalten. Dies wird in einem zukünftigen Release behoben.

Hinzufügen eines Konversationsfelds

Kunden können unabhängig vom Support-Plan Konversationsfelder erstellen, müssen aber Messaging konfiguriert haben und das Messaging Web Widget oder SDKs für Messaging verwenden.

Systemticketfelder, wie z. B. das Feld „Priorität“, werden nicht unterstützt. Sie erscheinen im Standardkontaktformular (und in allen anderen Ticketformularen), wenn Sie das Formular im Help Center aufrufen, werden aber nicht im Web Widget angezeigt.

Hinweis: Angepasste Felder vom Typ „Regulärer Ausdruck“, „Datum“ und „Mehrfachauswahl“ lassen sich über die Metadata APIs festlegen, erscheinen aber nicht in der Konversation.

Um zu überprüfen, ob ein Konversationsfeld festgelegt wurde, können Sie die Ticketinformationen im Zendesk-Arbeitsbereich für Agenten oder mit einer Zendesk-API einsehen. Weitere Informationen finden Sie unter Using Messaging Metadata (Englisch).

So fügen Sie ein Konversationsfeld hinzu

1. Klicken Sie in der Seitenleiste des Admin Centers auf Objekte und Regeln und dann auf Tickets > Felder.
2. Klicken Sie auf Feld hinzufügen.
3. Wählen Sie den gewünschten Feldtyp aus und geben Sie einen Anzeigenamen ein.
4. (Optional) Geben Sie eine Beschreibung für das angepasste Feld ein. Dies ist nur für Administratoren sichtbar.
5. Klicken Sie unter Berechtigungen auf Kunden können bearbeiten.
   Hinweis: Da die Werte durch den Aufruf einer öffentlichen clientseitigen API festgelegt werden können, sollten die Daten immer so behandelt werden, als ob sie von einem Endbenutzer bereitgestellt wurden. Diese APIs sollten nicht für sensible Daten verwendet werden.
6. Füllen Sie das Feld Für Kunden sichtbarer Titel aus.
7. Wenn das Feld vor dem Lösen des Tickets vom Agenten ausgefüllt werden muss, markieren Sie die Option Zum Lösen eines Tickets erforderlich. Diese Option ist nicht für alle Feldtypen verfügbar.
   Hinweis: Wenn Agenten zwei Tickets zusammenfassen, brauchen die erforderlichen Felder nicht ausgefüllt zu werden, da zusammengefasste Tickets nicht erst auf den Status „Gelöst“, sondern direkt auf „Geschlossen“ gesetzt werden. Diese Einstellung wird auch übersprungen, wenn eine Business-Regel das Ticket auf „Gelöst“ setzt, da es in diesem Fall nicht von einem Agenten, sondern von einem Systemprozess gelöst wird.
8. Wenn das Feld vor dem Einreichen des Tickets vom Endbenutzer ausgefüllt werden muss, markien Sie die Option Zum Einreichen einer Anfrage erforderlich.
9. Konfigurieren Sie je nach Feldtyp weitere Optionen.
10. (Optional) Geben Sie für das angepasste Feld einen Standardwert ein.
    Hinweis: Der Standardwert in einer Dropdownliste gilt nur für neue Tickets, die von Agenten über die Support-Oberfläche oder von Benutzern über ein beliebiges Ticketformular erstellt werden. Wenn Sie ein vorhandenes Ticketformular durch ein Formular ersetzen, das eine Dropdownliste mit einer Standardoption enthält, wird die Standardoption nicht angezeigt und erscheint leer.
11. Klicken Sie auf Speichern oder, wenn Sie ein weiteres angepasstes Feld erstellen möchten, im Dropdownsymbol auf Speichern und weiteres Feld hinzufügen.
12. Notieren Sie sich die Feld-ID des soeben erstellten Felds. Sie brauchen sie, wenn Sie die Metadata API verwenden.

Nachdem Sie das Konversationsfeld erstellt haben, können die Entwickler die entsprechenden Daten über die API /api/v2/ticket_fields anzeigen. Ein Beispiel für eine Antwort:

[
 {
   url: "https://z3n-lhills.zendesk.com/api/v2/ticket_fields/10093547287955.json",
   id: 10093547287955,
   type: "integer",
   title: "Bike Order id",
   raw_title: "Bike Order id",
   description:
     "An API will populate this bike order id value",
   raw_description:
     "An API will populate this bike order id value",
   position: 9999,
   active: true,
   required: false,
   collapsed_for_agents: false,
   regexp_for_validation: "\A[-+]?\d+\z",
   title_in_portal: "Bike Order Id",
   raw_title_in_portal: "Bike Order Id",
   visible_in_portal: true,
   editable_in_portal: true,
   required_in_portal: false,
   tag: null,
   created_at: "2022-10-04T04:48:05Z",
   updated_at: "2022-10-04T04:48:05Z",
   removable: true,
   agent_description: "Order id from our bikes catalog",
 },
]

Löschen des Konversationsfelds

Es gibt Situationen, in denen Sie die Werte eines Konversationsfelds löschen müssen. Das kann je nach Anwendungsfall nötig sein, wenn die abgerufenen Daten nicht mehr gültig sind. Angenommen, Sie verwenden Konversationsfelder, um Daten aus dem Einkaufswagen eines Endbenutzers abzurufen. Wenn der Endbenutzer alle Artikel in seinem Einkaufswagen löscht, können Sie auch die Werte dieser Konversationsfelder löschen, da die in ihnen erfassten Daten nicht mehr gültig sind.

Sie können Konversationsfelder mit der API clearConversationFields( ) löschen.

Hinzufügen eines Konversationsstichworts

Stichwörter sind Wörter oder Wortkombinationen, mit denen Sie Kontextinformationen zu Tickets und Themen hinzufügen können. Stichwörter können auf Tickets, Benutzer und Organisationen angewendet werden. So können Sie beispielsweise alle Anfragen, bei denen es sich um reine Verkaufsanfragen handelt, mit einem Stichwort wie „verkauf“ oder „sales“ kennzeichnen. Anschließend können Sie eine Ansicht oder einen Bericht zum Verfolgen dieser Anfragen erstellen.

Weitere Informationen finden Sie im Beitrag Überblick über Stichwörter.

Verwenden der Metadata APIs

Ein Beispiel für die Verwendung der Metadata APIs finden Sie in der Dokumentation für Entwickler unter Using Messaging Metadata.

Festlegen von Konversationsfeldern und -stichwörtern

Konversationsfeldwerte werden mit der API setConversationFields festgelegt. Mit dem folgenden Aufruf wird der Wert des angepassten Ticketfelds mit der ID „10093547287955“ zum Beispiel auf die Zeichenfolge „548832222“ gesetzt:

zE('messenger:set', 'conversationFields', [{ id: '10093547287955', value: '548832222'}]);

Wenn Sie ein angepasstes Dropdownfeld oder ein anderes angepasstes Feld verwenden, dass einen Feldwert mit einem Stichwort verknüpft, wird beim Festlegen des Feldwerts auch der Wert des angepassten Stichworts im resultierenden Ticket festgelegt.

	Clientseitige API zum Einstellen von Konversationsfeldern
Web Widget	zE('messenger:set', 'conversationFields', [{ id: '{field ID}', value: '{value}'}])
iOS	Zendesk.instance.setConversationFields(["{field ID}” : “{field ID}"])
Android	Zendesk.instance.setConversationFields(listOf( TicketField(id="{field ID}", value="{value}" )))
Unity	ZendeskSdk.Instance.Messaging.SetConversationFieldsAsync(Dictionary<string, object> ticketFields)

Ein mögliche Antwort für setConversationFields:

conversation: {
  ...
  metadata: {
        "zen:ticket_field": "30289064739483",
        ...
  },
}

Hinweis: {field ID} muss eine Zeichenfolge sein. Andernfalls wird der Wert in eine Zeichenfolge umgewandelt. {value} muss eine Zeichenfolge, eine Zahl oder ein boolescher Wert sein.

Die Werte von Konversationsstichwörtern werden mit der API setConversationTags festgelegt. Ähnlich wie bei der API setConversationFields gilt, dass beim Festlegen eines angepassten Stichworts, das mit einem bearbeitbaren angepassten Feld verknüpft ist, auch das angepasste Feld eingestellt wird. Wenn das angepasste Stichwort mit einem privaten (nicht bearbeitbaren) angepassten Feld verknüpft ist, wird das angepasste Feld nicht eingestellt.

	Clientseitige API zum Einstellen von Konversationsstichwörtern
Web Widget	zE('messenger:set', 'conversationTags', ['{tag value}', '{tag value}'])
iOS	Zendesk.instance.setConversationTags(["{tag value}", "{tag value}"])
Android	Zendesk.instance.setConversationTags(listOf("{tag value}", "{tag value}"))
Unity	ZendeskSdk.Instance.Messaging.SetConversationTags(List<string> tags)

Dieses Beispiel zeigt eine Antwort mit setConversationTags:

conversation: {
  ...
  metadata: {
    "zen:ticket:tags": "likes-nike-trainers, frequent-shopper",
  },
}

Löschen von Konversationsfeldern und -stichwörtern

Wenn sich der clientseitige Kontext ändert, können Sie Konversationsfeldwerte und -stichwörter löschen. Wenn der Endbenutzer zum Beispiel von einer Produktseite zur Hauptseite Ihres Onlineshops wechselt, sind die auf der Produktseite erfassten Daten nicht mehr gültig.

Verwenden Sie in diesem Fall die APIs ClearConversationFields und ClearConversationTags. Diese APIs löschen alle Konversationsfelder und -stichwörter. Es ist nicht möglich, einzelne Felder oder Stichwörter zu löschen.

	Clientseitige API zum Löschen von Konversationsfeldern und -stichwörtern
Android	Zendesk.instance.clearConversationFields() Zendesk.instance.removeConversationTags()
Unity	ZendeskSdk.Instance.Messaging.ClearConversationFields() ZendeskSdk.Instance.Messaging.ClearConversationTags()

Bot-Builder (Legacy AI Agents)

Mit Metadata APIs aktualisierte Felder werden mit vorhandenen Daten gefüllt und können von Endbenutzern bearbeitet werden, wenn sie in diesem Schritt angezeigt werden. Weitere Informationen finden Sie in den Beiträgen Überblick über die Schrittarten in Antworten und Erstellen angepasster Ticketfelder.