Virtual Agent API-Funktionen, die in Store-Version 2.0.x verfügbar sind

Konversations-Schnittstellen von Yokohama

Release

yokohama

ft:locale

de-DE

ft:publication_title

Konversations-Schnittstellen von Yokohama

ft:clusterId

convint

bundleId

convint

workflow

Platform

Virtual Agent API-Funktionen, die in Store-Version 2.0.x verfügbar sind

Freigeben Version: Yokohama

Aktualisiert 30. Januar 2025

10 Minuten Lesedauer

DieVirtual Agent API-Version 2.0.x bietet Zugriff auf weitere der gleichen Funktionen, die in Virtual Agent und Mitarbeiterchatverfügbar sind, einschließlich Rich Control-Unterstützung und Benachrichtigungen.

Unterstützung für zusätzliche Rich Controls

Virtual Agent Die API unterstützt jetzt die folgenden Rich Controls.

Boolesche Steuerelemente

Boolesche Steuerelemente geben Antworten zur einfacheren Lokalisierung als Zeichenfolgen zurück (entweder Yes oder No).

Weitere Informationen zur Themenlokalisierung finden Sie unter Virtual Agent -Konversationen werden lokalisiert.

Virtual Agent Die API sendet das folgende JSON-Beispiel für ein boolesches Steuerelement:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "7a36412253a13010ff59ddeeff7b12fb",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "Boolean",
      "group": "DefaultPicker",
      "required": true,
      "nluTextEnabled": false,
      "label": "Sample Response for boolean control",
      "options": [
        {
          "label": "Yes"
        },
        {
          "label": "No"
        }
      ]
    }
  ],
  "score": 1
}

Anwenderdefinierte Steuerungen

Themen, die anwenderdefinierte Steuerungen verwenden, werden jetzt unterstützt. Weitere Informationen zu anwenderdefinierten Steuerungen finden Sie unter Anpassen von Virtual Agent mit anwenderdefinierten Steuerungen.

Steuerelemente für Tabellen-Bot-Antworten

Themen, die Steuerelemente für Tabellen-Bot-Antworten verwenden, werden jetzt unterstützt. Weitere Informationen finden Sie unter Steuerelement für Tabellen-Bot-Antworten.

Alle Datensätze werden gleichzeitig von Virtual Agent der API zurückgegeben. Virtual Agent wartet auf eine Antwort vom API-Client, um das nächste Steuerelement zu senden. Verwenden Sie die Eigenschaft paginationBreak, um dem Benutzer Datensätze in Blöcken anzuzeigen. Beispiel: Wenn paginationBreak auf 10 festgelegt ist, werden dem Benutzer 10 Datensätze gleichzeitig angezeigt. Wenn der Client bereit ist, zum nächsten Steuerelement zu wechseln, sollte er DONEsenden.

Virtual Agent Die API sendet das folgende JSON-Beispiel für ein Tabellen-Bot-Antwortsteuerelement:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Yes",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputTable",
      "group": "DefaultOutputTable",
      "label": "Sample Table Rich control",
      "headers": [
        "Number",
        "Short description"
      ],
      "data": [
        [
          "INC0000005",
          "CPU load high for over 10 minutes"
        ],
        [
          "INC0000015",
          "I can't launch my VPN client since the last software update"
        ],
        [
          "INC0000025",
          "Need to add more memory to laptop"
        ],
        [
          "INC0000035",
          "Reset my password"
        ],
        [
          "INC0000055",
          "SAP Sales app is not accessible"
        ],
        [
          "INC0009005",
          "Email server is down."
        ]
      ],
      "paginationBreak": 10,
      "totalSearchResultsCount": 6,
      "navigationBtnLabel": "Click for more"
    }
  ],
  "score": 1
}

Steuerelemente für HTML-Bot-Antworten

Themen, die HTML-Bot-Antwortsteuerelemente verwenden, werden jetzt unterstützt. Weitere Informationen finden Sie unter Steuerelement für HTML-Bot-Antworten.

Virtual Agent Die API sendet das folgende JSON-Beispiel für ein HTML-Bot-Antwortsteuerelement:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Yes",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputHtml",
      "group": "DefaultOutputHtml",
      "style": "inline",
      "height": 100,
      "width": 100,
      "value": "<html> <body> Sample Response for Html control </body> </html> ",
      "imageUrl": null,
      "imageHeight": 0,
      "imageWidth": 0,
      "links": null
    },
    {
      "uiType": "InputText",
      "group": "DefaultText",
      "required": true,
      "nluTextEnabled": false,
      "label": "some text",
      "maskType": "NONE"
    }
  ],
  "score": 1
}

Steuerelemente für Bot-Antworten mit mehreren Antworten

Themen, die Bot-Antwortsteuerungen mit mehreren Antworten verwenden, werden jetzt unterstützt. Weitere Informationen finden Sie unter Steuerelement für Bot-Antworten mit mehreren Antworten.

Virtual Agent Die API sendet das folgende JSON-Beispiel für ein Bot-Antwortsteuerelement mit mehreren Antworten:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "MultiPartOutput",
      "group": "DefaultMultiPartOutput",
      "navigationBtnLabel": "Click for more",
      "content": {
        "uiType": "OutputText",
        "value": "Text response from multiflow control example",
        "maskType": "NONE"
      }
    }
  ],
  "score": 1
}

Rich-Text-Unterstützung

Themen, die Rich-Text verwenden, werden jetzt unterstützt. Rich-Text enthält fetten oder kursiven Text, Hyperlinks, Aufzählungslisten und Emojis.

Zusätzliche Funktionen von Mitarbeiterchat

Die Virtual Agent API unterstützt jetzt bei der Übertragung von an Mitarbeiterchatdie folgenden Funktionen.

Übergeben Sie Name und Avatar des Service Desk-Mitarbeiters

Wenn der primäre Bot einen Chat an einen Servicemitarbeiter überträgt, kann Virtual Agent den Namen und das Avatar des Service Desk-Mitarbeiters an den primären Bot senden. Aktivieren Sie dazu Namen und Avatare der Service Desk-Mitarbeiter in den Mitarbeiterchat-Einstellungen.

Eine Beispiel-Nachrichtennutzlast könnte wie folgt aussehen:

{ 
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c", 
"clientSessionId":"U94CSJLEN", 
"message":{ 
"text":"Live Agent support.", 
"typed":true 
}, 
"userId":"U94CSJLEN", 
"body":[ 
{ 
"uiType":"OutputText", 
"group":"DefaultText", 
"agentInfo":{ 
"sentFromAgent":true, 
"agentName":"Beth Anglin", 
"agentAvatar":"ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" 
}, 
"value":"Thank you for contacting support. I am looking into your question now and will be with you shortly." 
} 
], 
"agentChat":true, 
"score":1 
}

Weitere Informationen finden Sie unter Mitarbeiterchat konfigurieren.

Wartezeit des Servicemitarbeiters

Bei der Übertragung an einen Servicemitarbeiter kann der primäre Bot die Wartezeit erhalten und dem Anwender anzeigen. Um dies zu aktivieren, wählen Sie in den Mitarbeiterchat-Einstellungen im Feld Live-Chat-Wartestatusdie Option Wartezeit aus. Der Wert spinnerType wird auf wait_timefestgelegt. Wenn der Live-Chat-Wartestatus auf Keinefestgelegt ist, lautet der Wert spinnerTypenone.

Virtual Agent Die API sendet das folgende JSON-Beispiel im Parameter body der Nutzlast.

{
"uiType":"ActionMsg",
"actionType":"StartSpinner",
"spinnerType":"wait_time",
"message":"Routing you to a live agent...",
"waitTime":"8 Seconds"
}

Weitere Informationen finden Sie unter Mitarbeiterchat konfigurieren.

Chatverlauf vom primären Bot an senden Virtual Agent

Der primäre Bot kann den Chatverlauf an einen Servicemitarbeiter übergeben, sodass dieser den Kontext der Konversation sehen kann.

Virtual Agent konvertiert den Nachrichtenverlauf in HTML und dann in ein Bild.

Das konvertierte Bild wird als erste Nachricht im Chat an den Servicemitarbeiter gesendet.
Der primäre Bot sollte den Nachrichtenverlauf in der ersten Anforderung senden. In jeder anderen Anforderung nach der ersten Anforderung wird die Nutzlast des Nachrichtenverlaufs ignoriert.
Nur Textnachrichten werden unterstützt.
Der primäre Bot kann jede URL als Wert in der Textnachricht übergeben, der Servicemitarbeiter kann diese jedoch nur als Teil des Bildes anzeigen. Der Servicemitarbeiter kann nicht auf den Link klicken.

Beispiel für Nachrichtennutzlast:

{ 
      "value": "Help me with password reset", 
      "displayName": "able", 
      "type": "text" 
      "isBotMessage": false, 
    }

Hinweis:

Im vorherigen Beispiel wird type für zwischen Groß- und Kleinschreibung unterschieden, und der Wert muss textsein.

Ergänzte Anforderungen vom primären Bot

Die Virtual Agent API unterstützt jetzt die folgenden Anforderungen vom primären Bot.

Systemparameter und Kontextvariablen

Der primäre Bot kann Systemparameter und Kontextvariablen als Eingabe übergeben, und Virtual Agent berücksichtigt diese Parameter. Systemparameter wie liveagent_devicetype, liveagent_requester_session_language, liveagent_topic, topic, live_agent_onlyund liveagent_devicetimezone werden unterstützt. Anwenderdefinierte Kontextvariablen und Mitarbeiterchat -Kontextvariablen werden ebenfalls unterstützt.

Beispiel für Nachrichtennutzlast:

{ 
"requestId": "f42f3550-5b44-4cde-aa52-xxxxxxxxxx", 
"clientSessionId": "xxxxxxxxxx", 
"token": "abcd", 
"message": { 
    "text": "Test", 
    "typed": true 
}, 
"contextVariables": { 
       "requester_session_language": "es" 
}, 
"userId": ""abel.tuter", 
"emailId": "abel.tuter@example.com" 
}

Weitere Informationen finden Sie unter Kontextvariablen des Servicemitarbeiter-Chats und Konfigurieren Sie Kontextvariablen zum Speichern chatbezogener Informationen.

Anwenderzeitzone

Legen Sie die Zeitzone des Anwenders fest, indem Sie sie in der Nutzlast der Anforderung übergeben. Einmal festgelegt, wird diese Zeitzoneneinstellung beibehalten, bis sie zurückgesetzt wird.

Beispiel für Nachrichtennutzlast:

{ 

    "requestId": "xxxxxx-xxxxxx-xxxx-xxxx-xxxxxxxxxx", 
    "clientSessionId": "xxxxxxxx-xxxx", 
    "token": "xxxxx", 
    "action" : "SET_USER_TIMEZONE", 
    "userId": "able.tuter", 
    "emailId": "abel.tuter@example.com", 
     "timezone":"Asia/Kolkata" 
}

Beachten Sie bei der Verwendung dieser Funktion Folgendes:

Die Konversation muss geöffnet (aktuell) sein, um Datum und Uhrzeit in die Zeitzone des Anwenders zu konvertieren.
Der primäre Bot muss Datum und Uhrzeit in einem der folgenden Formate senden:
- Zeitzonenname. Zum Beispiel Asia/Kolkata oder America/New_York.
- Datum/Uhrzeit 24-Stunden-Format. Beispiel: YYYY-MM-DD HH:MM:SS
Die Virtual Agent -API verwendet die vom primären Bot angegebene Zeitzone, auch wenn die von ihr festgelegte Zeitzone von dem in der Tabelle [sys_user] gespeicherten Wert abweicht.
Um die Anwenderzeitzone festzulegen, senden Sie die Aktion SET_TIMEZONE. Wenn der Zeitzonenname nicht gültig ist, wird der Zeitzonenwert standardmäßig auf UTC-Zeit festgelegt. Zum Beispiel 2021-02-16 20:13:13.

Unterstützung für das Überspringen von Knoten

Virtual Agent Die API unterstützt das Überspringen eines Knotens, wenn dies im Thema vorgesehen ist. Beispielsweise können Sie in Virtual Agent-Designerein Benutzereingabe-Steuerelement als überspringbar in festlegen Erweitert > Diesen Knoten ausblenden oder überspringen Bereich des Eigenschaftsblatts.

In diesem Beispiel ist die Option Skript ausgewählt und definiert, wann der Benutzer den Knoten überspringen kann. — Abbildung : 1. Bedingung oder Skript, die bzw. das es dem Anwender ermöglicht, den Knoten zu überspringen

Weitere Informationen zum Definieren eines Knotens als überspringbar finden Sie unter Virtual Agent-Designer-Steuerelemente für Benutzereingaben.

Wenn ein Knoten als überspringbar markiert ist, zeigt der Bot dem Anwender diese Option an. Wenn der Anwender ihn überspringt, sollte der primäre Bot den Überspringungsbefehl wie im folgenden Beispiel dargestellt übergeben.

{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "835607",
"token": "snow",
"message": {
"text": "_skip_",
"typed": false
},
"emailId": "beth.anglin@example.com",
"userId": "beth.anglin"
}

Unterstützung für synchrones Handshake

Hinweis:

Diese Anforderungen gelten für Version 2.0.x der Virtual Agent API. Führen Sie für eine bessere synchrone Handshake-Funktion ein Upgrade auf Version 3.0.x durch, die die Übertragung von Aufgaben an Service Desk-Mitarbeiter und andere Verbesserungen unterstützt. Details finden Sie unter Verbesserungen des synchronen Handshake.

Wenn diese Option aktiviert ist, liefert Virtual Agent synchron Antworten an den primären Bot. Wenn Sie die Kommunikation mit Virtual Agent im synchronen Modus aktivieren möchten, müssen Sie die folgenden Funktionen manuell deaktivieren, damit der Handshake funktioniert:

Mitarbeiterchat
Benachrichtigungen
Eingabeindikatoren

Hinweis:

Themen, die die folgenden Funktionen verwenden, werden im synchronen Modus nicht unterstützt: Datei-Upload, Aktionsdienstprogrammund der Themenblock Pause.

Um diese Funktionen zu deaktivieren und synchrone Unterstützung zu aktivieren, gehen Sie wie folgt vor:

Bot-to-Bot-Kanal aus Mitarbeiterchatausschließen.
1. Navigieren Sie zu Alle, und geben Sie im Filter sys_properties.list ein.
2. Wählen Sie die Systemeigenschaft com.glide.cs.exclude.liveagent.support aus, um sie zu öffnen.
3. Addieren Sie Bot To Bot zum Feld Wert.
  Abbildung : 2. Schließen Sie den Bot-zu-Bot-Kanal aus aus Mitarbeiterchat
4. Klicken Sie auf Aktualisieren.
Navigieren Sie zu Alle, und geben Sie im Navigationsfilter sys_cs_channel.list ein.
Wählen Sie den Datensatz Bot zu Bot aus.
Deaktivieren Sie das Kontrollkästchen Benachrichtigungen aktivieren, um es zu deaktivieren.
Deaktivieren Sie das Kontrollkästchen Eingabeindikator unterstützen, um ihn zu deaktivieren.
Aktivieren Sie die Checkbox Synchron.
Abbildung : 3. Bot-zu-Bot-Kanal mit aktivierter synchroner Unterstützung

Hinweis:
Wenn das Feld Synchron (Synchron) nicht sichtbar ist, können Sie das Formularlayout so konfigurieren, dass es angezeigt wird.
Klicken Sie auf Aktualisieren.

Unterstützung für Benachrichtigungen

Verwenden Sie die API Virtual Agent, um die folgenden Arten von Benachrichtigungen im Bot-zu-Bot-Kanal zu senden, wenn sie im asynchronen Modus aktiviert ist:

Einfach: Nur Textbenachrichtigungen. Einfache Benachrichtigungen werden übermittelt, sobald sie eingehen.
Bildkarte: Ein Bild, das auf den Server hochgeladen oder mit einer URL angegeben wird.
Datensatzkarte: Angegebene Spalten aus einem Datensatz in einer Tabelle.
Umsetzbar: Bietet dem Anwender die Möglichkeit, bestimmte Aktionen auszuführen. Umsetzbare Benachrichtigungen werden in die Warteschlange gestellt. Der Benutzer kann sie bei Bedarf abrufen, indem er den Befehl Show Notification sendet.

Weitere Informationen finden Sie unter Virtual Agent -Benachrichtigungen werden konfiguriert.

Virtual Agent Die API sendet das folgende JSON-Beispiel für eine einfache Benachrichtigung:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputCard",
      "group": "DefaultOutputCard",
      "templateName": "Notification",
      "data": "{\"sys_id\":null,\"recordDisplayValue\":null,\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":null,\"tableLabel\":null,\"enableLink\":false,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[],\"table_name\":null,\"url\":\"http://192.168.1.9:8080/null.do?sys_id=null\"}"
    }
  ],
  "completed": true,
  "score": 1
}

Virtual Agent Die API sendet das folgende JSON-Beispiel für eine Bildkartenbenachrichtigung:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputCard",
      "group": "DefaultOutputCard",
      "templateName": "Notification",
      "data": "{\"sys_id\":null,\"recordDisplayValue\":null,\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":\"http://xxxxxx.service-now.com/2b2d0d2653a13010ff59ddeeff7b120d.iix\",\"tableLabel\":null,\"enableLink\":false,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[],\"table_name\":null,\"url\":\"http://192.168.1.9:8080/null.do?sys_id=null\"}"
    }
  ],
  "completed": true,
  "score": 1
}

Virtual Agent Die API sendet das folgende JSON-Beispiel für eine Datensatzkartenbenachrichtigung:

{
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputCard",
      "group": "DefaultOutputCard",
      "templateName": "Notification",
      "data": "{\"sys_id\":\"552c48888c033300964f4932b03eb092\",\"recordDisplayValue\":\"INC0010112\",\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":null,\"tableLabel\":\"Incident\",\"enableLink\":true,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[{\"fieldLabel\":\"Number\",\"fieldValue\":\"INC0010112\"},{\"fieldLabel\":\"Short description\",\"fieldValue\":\"Assessment : ATF Assessor\"}],\"table_name\":\"incident\",\"url\":\"http://192.168.1.9:8080/incident.do?sys_id=552c48888c033300964f4932b03eb092\"}"
    }
  ],
  "completed": true,
  "score": 1
}

Benachrichtigungen für den Bot-zu-Bot-Kanal sind standardmäßig deaktiviert. Um sie zu aktivieren, gehen Sie wie folgt vor:

Navigieren Sie zu Alle, und geben Sie im Navigationsfilter sys_cs_channel.list ein.
Öffnen Sie den Bot-to-Bot-Datensatz.
Aktivieren Sie bei entsprechender Aufforderung die Bearbeitung des Datensatzes.
Aktivieren Sie das Kontrollkästchen Benachrichtigungen aktivieren.
Klicken Sie auf Aktualisieren.

Administratoren können die Anzahl der Empfänger pro Benachrichtigung begrenzen, indem sie die Eigenschaft com.glide.cs.per_notification_user_limit ändern. Der Standardwert ist 1000.

Themenwechsel anhand des Themennamens

Sie können zum Wechseln des Themas nicht nur die Themen-ID oder die Themenabsichts-ID verwenden, sondern auch den Namen des Themas oder der Themenabsicht verwenden. Es wird empfohlen, nur die Themen-ID oder den Themennamen zu senden. Wenn entweder falsch ist oder wenn sich der Bot bereits im angegebenen Thema befindet, sendet Virtual Agent derzeit keine Antwort. Die Nutzung hängt vom verwendeten Modus ab:

NLU-Themen-Discovery: Verwenden Sie den Namen oder die ID der Themenabsicht.
Stichwort-Themen-Discovery: Verwenden Sie den Namen oder die ID des Themas.

Der primäre Bot kann die Aktion SWITCH zusammen mit dem Themennamen senden, um direkt zu einem bestimmten Thema zu wechseln.

Beispiel für Nachrichtennutzlast:

{ 
   "requestId": "xxxx-xxxx-xxxx-xxxx",
   "clientSessionId": "xxx-xxx-xxx-xxx",
   "action":"SWITCH",
   "topic":{
      "name": "Topic Name"
   },
   "userId": "beth"  
}

Unterstützung für Eingabeindikatoren

Sie können Eingabeindikatoren für Benutzer und Servicemitarbeiter aktivieren. Derzeit werden Eingabeindikatoren wie folgt angezeigt:

Wird dem Service Desk-Mitarbeiter angezeigt, wenn der Benutzer etwas tippt
Wird dem Anwender angezeigt, wenn der Bot eine Antwort vorbereitet

Wenn der Eingabeindikator aktiviert ist, sendet die Virtual Agent API die Aktionen StartTypingIndicator und EndTypingIndicatorin der Antwortnutzlast. Zum Beispiel:

{ 
        "uiType":"ActionMsg", 
        "actionType":"StartTypingIndicator" 
}

Um den Benutzereingabeindikator an einen Servicemitarbeiter zu senden, muss der Client die Aktion TYPINGsenden. Wenn der Benutzer mit der Eingabe fertig ist, sollte der Client die AktionVIEWINGsenden. Beispiel:

{ 
    "requestId": "xxxxxx-xxxxxx-xxxx-xxxx-xxxxxxxxxx", 
    "clientSessionId": "xxxxxxxx-xxxx", 
    "action": "TYPING/VIEWING", 
    "userId": "able.tuter", 
    "emailId": "abel.tuter@example.com", 
    "timezone":"Asia/Kolkata" 
}

Führen Sie die folgenden Schritte aus, um Eingabeindikatoren zu aktivieren.

Navigieren Sie zu Alle, und geben Sie im Navigationsfilter sys_cs_channel.list ein.
Wählen Sie den Datensatz Bot zu Bot aus.
Aktivieren Sie das Kontrollkästchen Eingabeindikator unterstützen.
Klicken Sie auf Aktualisieren.