Metadaten des Chattranskripts

In diesem Dokument wird das Schema des Metadatensatzes für das Chatprotokoll erläutert. Dies ist die JSON-Datei, die die Contact Center AI Platform (CCAI Platform) für ein abgeschlossenes Chatprotokoll generiert. Der Metadatensatz für das Chatprotokoll wird durch den JSON-Export des Chatverlaufs erstellt und kann je nach Instanzkonfiguration über CRM-Protokoll-Uploads und Protokolldateien im externen Speicher bereitgestellt werden. Verwenden Sie dieses Schema, um Transkript-JSON zu parsen, empfangene Nutzlasten zu validieren oder Transkriptnachrichten in nachgelagerte Systeme zu übertragen.

Schemastamm

Der Metadatensatz für das Chatprotokoll ist ein einzelnes JSON-Objekt, das ein Chatprotokollartefakt darstellt. Die Felder auf der Stammebene identifizieren die Kommunikation, die Version des Transkriptformats und die geordnete Gruppe von Transkripteinträgen.

Kommunikationskennungen comm_type und comm_id

Zusammen identifizieren comm_type und comm_id die Kommunikation, die dieser Transkriptdatensatz darstellt.

  • comm_type gibt den Kommunikationstyp an. Der Wert ist normalerweise chat. Bei einem Sprachanruf, der gemischte SMS-Transkriptinhalte enthält, kann es call sein.

  • comm_id ist die Kennung des Chats oder Anrufs, der durch das Transkript dargestellt wird.

Formatversion transcript_version

Gibt die Version des JSON-Transkriptformats an. Integrationen sollten dieses Feld für das vorwärtskompatible Parsen verwenden und nicht erkannte Felder ignorieren.

Eintragsdiskriminator – entries[].type und entries[].body.type

Jedes Element in entries stellt eine Transkriptnachricht oder ein Ereignis dar. Das Feld type auf Einstiegsebene spiegelt den Typ des Nachrichtentexts wider. Das verschachtelte body-Objekt enthält die Nutzlast, deren Form je nach Typ variiert, z. B. text, markdown, photo, noti oder action.

Metadatenschema für Chattranskripte

In diesem Schema wird die Datenstruktur von Chattranskripten beschrieben. In den folgenden Abschnitten werden die Kernkomponenten beschrieben.

Wichtige Informationen zum Transkript

Die folgenden Properties enthalten die grundlegenden Informationen zum Transkript selbst:

  • comm_type (String): Der Kommunikationstyp, den das Transkript darstellt. Mögliche Werte: chat, call. Der Wert call gibt einen Sprachanruf mit gemischten SMS-Transkriptinhalten an.

  • comm_id (Ganzzahl): Eindeutige Kennung der Kommunikation, die durch das Transkript dargestellt wird.

  • transcript_version (String): Version des JSON-Formats des Transkripts. Der aktuelle Wert ist "1.0". Weitere Informationen finden Sie unter Versionsverwaltung und Einstellungen.

  • assigned_at (String, Datum/Uhrzeit): Zeitstempel, der angibt, wann der Chat zugewiesen wurde.

  • timezone (String): Zeitzone für den Transkriptkontext, z. B. "America/Los_Angeles".

Transkripteinträge

  • entries (Array): Sortierte Liste der Transkripteinträge. Jeder Eintrag steht für eine Nachricht, eine Benachrichtigung oder eine Aktion in der Unterhaltung.

    • timestamp (Ganzzahl): Unix-Epochen-Zeitstempel in Sekunden, zu dem das System den Eintrag erstellt hat.

    • type (String): Typ des Inhalts der Nachricht. Dieser Wert spiegelt body.type wider. Unterstützte Körpertypen finden Sie unter Definitionen.

    • body (Objekt): Nutzlast des Eintrags. Die Form hängt vom Wert von type / body.type ab.

    • role (String): Rolle des Teilnehmers oder der Systemkomponente, die den Eintrag erstellt hat. Mögliche Werte: end_user, agent, manager, virtual_agent, external_agent, task_virtual_agent, system.

    • user_data (Objekt): Absendermetadaten. Bei den Einträgen agent, manager, virtual_agent, external_agent und task_virtual_agent enthält dieses Objekt die Anzeigedaten des Absenders. Bei end_user- und system-Einträgen ist dieses Objekt leer.

      • name (String; nur vorhanden, wenn Absendermetadaten verfügbar sind): Anzeigename des Absenders.

      • id (Ganzzahl; nur vorhanden, wenn Absendermetadaten verfügbar sind): Kennung des Absenders.

      • avatar_url (String, URI; nur vorhanden, wenn Absendermetadaten verfügbar sind): URL des Avatarbilds des Absenders.

Inhalt von Textnachrichten

  • text (Objekt): Nur-Text-Nachrichtentext.

    • type (String): Immer text.

    • content (String): Nachrichtentext.

    • lang (String; nur vorhanden, wenn Sprachmetadaten verfügbar sind): Sprachcode, der mit der Nachricht verknüpft ist.

  • text_template (Objekt): Vorlagenbasierter Inhalt der Nachricht.

    • type (String): Immer text_template.

    • content (String): Vorlagentext.

  • markdown (Objekt): Markdown-formatierter Inhalt der Nachricht.

    • type (String): Immer markdown.

    • content (String): Markdown-Inhalt.

    • lang (String; nur vorhanden, wenn Sprachmetadaten verfügbar sind): Sprachcode, der mit der Nachricht verknüpft ist.

  • markdown_template (Objekt): Vorlagenbasierter Markdown-Inhalt der Nachricht.

    • type (String): Immer markdown_template.

    • content (String): Inhalt der Markdown-Vorlage.

Inhalt von Medien- und Dateinachrichten

  • photo (Objekt): Inhalt der Nachricht für Foto oder Screenshot.

    • type (String): Immer photo.

    • media_id (Ganzzahl): Kennung der gespeicherten Fotomedien.

  • video (Objekt): Inhalt der Videonachricht.

    • type (String): Immer video.

    • media_id (Ganzzahl; vorhanden, wenn das System das Video als CCAI Platform-Medien speichert): Kennung der gespeicherten Videomedien.

    • title (String; vorhanden, wenn ein eingebettetes Videoobjekt das Video darstellt): Titel des Videos.

    • video (Objekt; vorhanden, wenn ein eingebettetes Videoobjekt das Video darstellt): Videodetails.

      • url (String, URI): URL des Videos.

      • text (String): Textalternative oder Fallback-URL für das Video.

  • image (Objekt): Inhalt der Bildnachricht.

    • type (String): Immer image.

    • title (String; vorhanden, wenn vom Absender der Nachricht angegeben): Titel des Bildes.

    • image (Objekt): Bilddetails.

      • url (String, URI): URL des Bildes.

      • text (String): Textalternative oder Fallback-URL für das Bild.

  • document (Objekt): Textkörper der Dokumentnachricht.

    • type (String): Immer document.

    • media_id (Ganzzahl; vorhanden, wenn das System das Dokument als CCAI Platform-Medium speichert): Kennung des gespeicherten Dokumentmediums.

    • title (String; vorhanden, wenn ein eingebettetes Dokumentobjekt das Dokument darstellt): Titel des Dokuments.

    • document (Objekt; vorhanden, wenn ein eingebettetes Dokumentobjekt das Dokument darstellt): Dokumentdetails.

      • url (String, URI): URL des Dokuments.

      • text (String): Textalternative oder Fallback-URL für das Dokument.

  • audio (Objekt): Text der Sprachnachricht.

    • type (String): Immer audio.

    • media_id (Ganzzahl; vorhanden, wenn das System die Audioinhalte als CCAI Platform-Medien speichert): Kennung der gespeicherten Audiomedien.

    • title (String; vorhanden, wenn ein eingebettetes Audioobjekt die Audiodatei darstellt): Titel der Audiodatei.

    • audio (Objekt; vorhanden, wenn ein eingebettetes Audioobjekt die Audiodatei darstellt): Audiodetails.

      • url (String, URI): URL der Audiodatei.

      • text (String): Textalternative oder Fallback-URL für die Audiodatei.

Interaktive Nachrichtentexte

  • inline_button (Objekt): Inhalt der Nachricht für Inline-Schaltfläche.

    • type (String): Immer inline_button.

    • title (String): Titel, der über den Schaltflächen angezeigt werden soll.

    • buttons (Array): Liste der Schaltflächendefinitionen.

      • title (String): Button-Label.

      • action (String): Aktion, die mit der Schaltfläche verknüpft ist.

      • link (String, URI; nur für Kurzantworten im Link-Stil vorhanden): URL, die mit der Schaltfläche verknüpft ist.

  • sticky_button (Objekt): Inhalt der Nachricht mit fixierter Schaltfläche.

    • type (String): Immer sticky_button.

    • title (String): Titel, der über den Schaltflächen angezeigt werden soll.

    • buttons (Array): Liste der Schaltflächendefinitionen.

      • title (String): Button-Label.

      • action (String): Aktion, die mit der Schaltfläche verknüpft ist.

      • link (String, URI; nur für Kurzantworten im Link-Stil vorhanden): URL, die mit der Schaltfläche verknüpft ist.

  • content_card (Objekt): Inhalt der Nachricht auf der Inhaltskarte.

    • type (String): Immer content_card.

    • cards (Array): Liste der Inhaltskarten.

      • title (String): Titel der Karte.

      • body (String; nur vorhanden, wenn Sie den Text im Kartentext konfigurieren): Text im Kartentext.

  • form_complete (Objekt): Nachrichtentext für das Ausfüllen des Formulars, den der Client sendet, wenn ein Nutzer ein Formular ausfüllt, nicht ausfüllt oder abbricht.

    • type (String): Immer form_complete.

    • signature (String; nur vorhanden, wenn das Abschlussereignis eine Signatur enthält): Signatur für die Nutzlast des Formularabschlusses.

    • data (Objekt): Details zum Ausfüllen des Formulars.

      • status (String): Abschlussstatus. Mögliche Werte: success, error, cancelled.

      • smart_action_id (Ganzzahl): Kennung der Smart Action, die mit dem Formular verknüpft ist.

      • timestamp (String, Datum/Uhrzeit): Zeitstempel des Ereignisses, bei dem das Formular ausgefüllt wurde. Dies unterscheidet sich vom Eintrag timestamp, der ein ganzzahliger Unix-Epochenzeitstempel in Sekunden ist.

      • details (Objekt; nur vorhanden, wenn die Nutzlast zusätzliche Abschlussdetails enthält): Zusätzliche Statusdetails.

        • error_code (String; nur bei Fehlern mit einem Code vorhanden): Fehlercode, der mit dem Ergebnis der Vervollständigung verknüpft ist.

        • message (String): Menschenlesbares Statusdetail.

Vom Server generierte und weitergeleitete Inhalte der Nachricht

  • server_message (Objekt): Vom Server generierter Inhalt der Nachricht. Das Transkript enthält nur dann server_message-Einträge, wenn Sie Transkriptinhalte für virtuelle Agenten für Ihr Konto aktivieren. Andernfalls werden diese Einträge im Transkript weggelassen. Verwenden Sie dieses Objekt, wenn das Transkript auf eine gespeicherte serverseitige Nachricht verweist.

    • type (String): Immer server_message.

    • message_id (Ganzzahl): Kennung der gespeicherten Servernachricht.

    • visibility (String oder Null): Sichtbarkeitseinstellung für die gespeicherte Servernachricht.

  • passthrough (Objekt): Eine benutzerdefinierte Nutzlast, die das System für eine Integration mit einem virtuellen Agenten oder CCaaS über die CCAI Platform weitergibt. Ihre Integration definiert ihre content, die nicht Teil des CCAI Platform-Schemas ist. Behandeln Sie sie als intransparent.

    • type (String): Immer passthrough.

    • content (String oder Objekt): Integrationsdefinierte Nutzlast. Die Struktur variiert je nach Integration und wird von der CCAI Platform nicht interpretiert.

Inhalt von Aktionsnachrichten

  • action (Objekt): Aktion, die von einem virtuellen Agenten oder Chatbot-Flow angefordert wird. Das Feld action bestimmt die Form der Aktionsnutzlast.

    • type (String): Immer action.

    • action (String): Aktionstyp. Mögliche Werte sind escalation, deflection und end.

    • escalation_reason (String; nur vorhanden, wenn action den Wert escalation hat): Grund für die Eskalation der Unterhaltung.

    • menu_id (Ganzzahl; nur vorhanden, wenn action den Wert escalation hat): Kennung des Menüs, zu dem die Unterhaltung eskaliert werden soll.

    • language (String; nur vorhanden, wenn action den Wert escalation hat): Sprachcode der Zielwarteschlange.

    • deflection_type (String; nur vorhanden, wenn action den Wert deflection hat): Typ der angeforderten Ablenkung.

    • sip_parameters (Objekt oder null; nur vorhanden, wenn action den Wert deflection hat): SIP-Parameter, die im Rahmen der Weiterleitung weitergeleitet werden sollen.

Inhalt von Benachrichtigungen

  • noti (Objekt): Text der Benachrichtigung. In Benachrichtigungen werden Systemereignisse beschrieben, die während des Chats aufgetreten sind.

    • type (String): Immer noti.

    • event (String): Ereignisname der Benachrichtigung.

    • agent (Objekt; nur für Ereignisse vorhanden, die mit einem menschlichen Kundenservicemitarbeiter verknüpft sind): Kundenservicemitarbeiter, der mit dem Ereignis verknüpft ist.

      • id (Ganzzahl): Agent-ID.

      • email (String, E-Mail-Adresse): E-Mail-Adresse des KI-Agenten.

      • name (String): Anzeigename des KI-Agenten.

    • from_agent (Objekt; nur für Übertragungsereignisse mit einem Quell-Agent vorhanden): Quell-Agent für das Ereignis.

      • id (Ganzzahl): Agent-ID.

      • email (String, E-Mail-Adresse): E-Mail-Adresse des KI-Agenten.

      • name (String): Anzeigename des KI-Agenten.

    • to_agent (Objekt; nur bei Weiterleitungs- oder Eskalationsereignissen mit einem menschlichen Kundenservicemitarbeiter als Ziel vorhanden): Ziel-Kundenservicemitarbeiter für das Ereignis.

      • id (Ganzzahl): Agent-ID.

      • email (String, E-Mail-Adresse): E-Mail-Adresse des KI-Agenten.

      • name (String): Anzeigename des KI-Agenten.

    • from_virtual_agent (Objekt; nur für Eskalationsereignisse von einem virtuellen Agenten vorhanden): Virtueller Quell-Agent für das Ereignis.

      • id (Ganzzahl): ID des virtuellen Agenten.

      • name (String): Anzeigename des virtuellen Agenten.

      • avatar_url (String, URI oder Null): URL des Avatarbilds des virtuellen Agenten.

    • to_virtual_agent (Objekt; nur bei Weiterleitungsereignissen an einen virtuellen Agenten vorhanden): Virtueller Zielagent für das Ereignis.

      • id (Ganzzahl): ID des virtuellen Agenten.

      • name (String): Anzeigename des virtuellen Agenten.

      • avatar_url (String, URI oder Null): URL des Avatarbilds des virtuellen Agenten.

    • target (String; nur für Übertragungsereignisse vorhanden): Zieltyp der Übertragung. Mögliche Werte sind menu und agent.

    • status (String; nur für Ereignisse mit einem Chatstatus vorhanden): Der mit dem Ereignis verknüpfte Chatstatus.

    • timeout (boolescher Wert; nur für Ereignisse im Zusammenhang mit Zeitüberschreitungen vorhanden): Gibt an, ob das Ereignis durch eine Zeitüberschreitung verursacht wurde.

    • memberIdentity (String; nur für Ereignisse, bei denen ein Teilnehmer beitritt oder den Termin verlässt): Identität des Teilnehmers.

    • memberName (String; nur für Ereignisse, bei denen ein Teilnehmer beitritt oder die Videokonferenz verlässt): Anzeigename des Teilnehmers.

    • name (String; nur für Ereignisse vom Typ „virtual-agent“ oder „task-va“ vorhanden): Der mit dem Ereignis verknüpfte Anzeigename.

    • reason (String; nur bei task-va-Abschlussereignissen vorhanden): Grund für das Ende der task-va-Sitzung.

    • escalation_reason (String; nur bei Eskalationsereignissen vorhanden): Grund für die Eskalation.

    • deflection (Objekt; nur bei Ablenkungsereignissen vorhanden): Details zur Ablenkung.

    • detail (Objekt; nur für benutzerdefinierte Benachrichtigungsereignisse vorhanden): Details zum benutzerdefinierten Ereignis.

      • key (String): Schlüssel für benutzerdefiniertes Ereignis.

      • data (Objekt): Nutzlast des benutzerdefinierten Ereignisses.

Namen von Benachrichtigungsereignissen

Das Feld event gibt das Benachrichtigungsereignis an. Der Chatanbieter, der als zentrale Informationsquelle dient, speichert alle Benachrichtigungsereignisse in der folgenden Liste im JSON-Transkript. In der Liste werden diese Ereignisse nach Familie gruppiert.

Anfragen für intelligente Aktionen

  • verificationRequested

  • photoRequested

  • videoRequested

  • screenshotRequested

  • textRequested

  • cobrowseRequestedFromAgent

Ergebnisse von intelligenten Aktionen

  • Abgeschlossen: photoFinished, videoFinished, screenshotFinished, textFinished
  • Abgebrochen: photoCanceled, videoCanceled, screenshotCanceled, textCanceled
  • Fehlgeschlagen: photoFailed, videoFailed, screenshotFailed, textFailed, verificationFailed

Überprüfung

  • endUserVerified

Co-Browsing

  • cobrowseRequestedFromEndUser

  • cobrowseCodeGenerated

  • cobrowseStarted

  • cobrowseEnded

  • cobrowseFailed

Formulare

  • formRequested

  • formSent

  • formCompleted

Übertragungen

  • transferStarted

  • transferAccepted

  • transferFailed

Eskalationen an virtuelle Kundenservicemitarbeiter

  • escalationStarted

  • escalationAccepted

  • escalationDeflected

  • escalationFailed

Virtueller Kundenservicemitarbeiter für Aufgaben

  • taskVaStarted

  • taskVaFinished

Mitgliedschaft

  • agentJoined

  • memberJoined

  • memberLeft

Sitzungslebenszyklus

  • chatEnded

  • chatEndedWithPostSession

  • chatDismissed

  • chatReactivated

  • checkInRequired

  • checkInTimedOut

  • transcriptRequested

  • transcriptUpdated

Benutzerdefiniert

  • custom

Bei Einträgen, bei denen comm_type auf call festgelegt ist, werden möglicherweise zusätzliche Benachrichtigungsereignisse für Anruftranskripte angezeigt. Diese Ereignisse sind mit der Verarbeitung von Anruf- oder Agent Assist-Transkripten verknüpft und nicht mit den normalen Chat-Ereignisfamilien.

Definitionen

Die folgenden Unterschemas werden im Metadatendokument des Chatprotokolls angezeigt. In diesem Abschnitt wird jedes Unterschema einmal definiert. Attributgruppen, die darauf verweisen, verweisen auf diesen Abschnitt, anstatt ihre Form inline neu zu definieren.

entry (Objekt)

Stellt eine Transkriptnachricht, Benachrichtigung oder Aktion dar. Jeder Eintrag hat eine Unix-Epoche timestamp, eine übergeordnete type, ein body-Objekt, dessen Typ mit dieser Form übereinstimmt, einen Absender role und ein user_data-Objekt. Eine vollständige Liste der Felder finden Sie unter Transkripteinträge.

user_data (Objekt)

Beschreibt den Absender eines Transkripteintrags, wenn Absendermetadaten verfügbar sind. Einträge für „agent“, „manager“, „virtual-agent“, „external-agent“ und „task-virtual-agent“ können name, id und avatar_url enthalten. Nutzer- und Systemeinträge enthalten ein leeres Objekt.

Inhalt der Nachricht (Objekt, oneOf)

Das body-Objekt für jeden Eintrag verwendet den Wert von body.type, um eine der unterstützten Formen des Nachrichtentexts auszuwählen. Zu den unterstützten Textkörpern gehören Textkörper, Medien- oder Dateikörper, interaktive Körper, vom Server generierte Körper, Aktionskörper und Benachrichtigungskörper. Eine vollständige Liste der dokumentierten Varianten finden Sie unter Textnachrichtentexte bis Benachrichtigungstexte.

participant role (String, Enum)

Gibt die Absenderkategorie für einen Transkripteintrag an.

Zulässige Werte

  • end_user: Der Nutzer.

  • agent: Ein menschlicher Kundenservicemitarbeiter.

  • manager: Ein Manager-Teilnehmer.

  • virtual_agent: Ein virtueller Kundenservicemitarbeiter.

  • external_agent: Ein externer Teilnehmer.

  • task_virtual_agent: Ein virtueller Kundenservicemitarbeiter für Aufgaben.

  • system: Ein vom System generierter Eintrag.

Versionsverwaltung und Einstellungen

Das Metadatendokument für das Chatprotokoll unterstützt die abwärtskompatible Schemaentwicklung. Das System kann im Laufe der Zeit neue Felder und Varianten des Nachrichtentexts hinzufügen. Integrationen sollten alle nicht erkannten Schlüssel ignorieren, um die Funktionalität aufrechtzuerhalten.

Aktuelle Formatversion

  • transcript_version (String) – Aktueller Wert: "1.0". Integrationen sollten das Transkript anhand der in der Nutzlast vorhandenen Felder parsen und nicht fehlschlagen, wenn in zukünftigen Versionen neue Felder oder Nachrichtentypen hinzugefügt werden.

Unbekannte Nachrichtentypen

Wenn ein Transkripteintrag einen nicht erkannten type oder body.type enthält, behalten Sie den Roheintrag nach Möglichkeit bei und parsen Sie den Rest des Transkripts weiter. Das System kann neue Nachrichtentexttypen hinzufügen, ohne die Bedeutung vorhandener Felder zu ändern.

Verworfene Felder

In diesem Dokument sind keine verworfenen Felder für den Metadatensatz des Chatprotokolls aufgeführt.