--- sourceDocument: Xanadu-Konversations-Schnittstellen sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/de-DE/xanadu/conversational-interfaces Release : - xanadu ft:locale : - de-DE ft:publication_title : - Xanadu-Konversations-Schnittstellen ft:clusterId : - convint bundleId : - convint workflow : - Platform --- # Virtual Agent API Funktionen, die in Store-Version 3.0.x verfügbar sind # Virtual Agent API Funktionen, die in Store-Version 3.0.x verfügbar sind {#ariaid-title1} * Freigeben Version: Xanadu * * Aktualisiert 1. August 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 Minuten Lesedauer Virtual Agent API Version 3.0.x bietet Zugriff auf weitere der gleichen Funktionen, die in Virtual Agent und Mitarbeiterchatverfügbar sind, einschließlich der Möglichkeit, Dateien von einer privaten URL hochzuladen, und Verbesserungen des synchronen Handshake. ## Abgebrochene Virtual Agent Konversationen werden beendet {#va-api-features-v3__section_y1m_khj_dsb} Wenn eine Konversation aufgrund eines Fehlers unvollständig ist, kann Virtual Agent den primären Bot bitten, die Kontrolle zu übernehmen. Wenn die Kennzeichnung \[ takeControl den Wert truehat, schließt Virtual Agent (als sekundärer Bot) die Konversation automatisch. Wenn der primäre Bot eine Konversation starten möchte, kann er die folgende Aktionsnachricht senden: `„hi"/START_CONVERSATION`. Sie können den primären Bot bitten, in den folgenden Situationen die Kontrolle zu übernehmen: * Leerlauf-Zeitüberschreitung: Interaktionsstatus ist „ Geschlossen verworfen" . Statusgrund ist „Keine Aktivität". * Technische Probleme: Interaktionsstatus ist „Geschlossen verworfen". Statusgrund ist „Bot-Probleme". * Ungültige Anwendereingabe: Interaktionsstatus ist „Geschlossen verworfen". Statusgrund ist „Ungültige Anwendereingabe". {#va-api-features-v3__ul_zts_y3j_dsb} Um anzufordern, dass der primäre Bot die Kontrolle übernimmt, senden Sie die Kennzeichnung takeControl im Textkörper der Nutzlast mit dem Wert truean den primären Bot. Beispiel für Nachrichtennutzlast: {​   "requestId": "xxxx-xxxx-xxxx-xxxx",   "clientSessionId": "xxx-xxx-xxx-xxx", "message": {   "text":"invalid3", "typed":true } "body":[{ "uiType":"OutputText", "group":"DefaultText", "value":"Sorry, I didn't get that. Could you help me by answering this?" }, { "uiType":"Boolean", "group":"DefaultPicker", "required":true, "nluTextEnabled": false, "label":"Choose a value", "options":[ {"label":"Yes"}, {"label":"No"} ] }], "takeControl":true, "score":0 } ## Fehler beim Themenwechsel und Fehlerbehebung verbessert {#va-api-features-v3__section_b3w_cks_2rb} Der Themenwechsel kann aus einem der folgenden Gründe fehlschlagen: * Die Anforderung enthält sowohl den Themennamen als auch die Themen-ID (Stichwort-Themen-Discovery) oder den Namen der Themenabsicht und die ID der Themenabsicht (NLU-Themen-Discovery). Geben Sie den einen oder den anderen an. * Die Anforderung enthält einen ungültigen Themen- oder Absichtsnamen oder eine ungültige ID. * Der Name oder die ID des Themas/der Absicht ist gültig, aber Virtual Agent kann ihn/sie nicht ausführen, da er/sie inaktiv oder kein Thema ist. Zum Beispiel, wenn der Name oder die ID auf einen Themenblock oder ein anwenderdefiniertes Steuerungsobjekt verweisen. * Das angeforderte Thema wird bereits ausgeführt. * Das angeforderte Thema ist gültig, aber eine Sicherheitsbedingung verhindert den Zugriff. Beispielsweise darf das Thema möglicherweise nicht im Kanal ausgeführt werden, oder es kann eine andere Zugriffssteuerungsbedingung gelten. {#va-api-features-v3__ul_ekg_rnt_2rb} Wenn der Themenwechsel fehlschlägt, reagiert Virtual Agent API auf folgende Weise, unabhängig davon, ob Sie es synchron oder asynchron verwenden: * Wenn der Themenwechsel fehlschlägt, wird die Konversation mit einer Meldung geschlossen, dass sie nicht fortgesetzt werden kann. Die Konversation verbleibt nicht mehr im Status „Offen". * Die vorherige Anforderung wird als verarbeitet markiert, sodass eine neue Anforderung gestellt werden kann, ohne eine Zeitüberschreitung abzuwarten. * Der Grund für den Fehler wird in der Systemprotokolltabelle () protokolliert.Automated Test FrameworkSystemprotokolleFehler) an. {#va-api-features-v3__ul_xzw_wqt_2rb} ## Verbesserungen des synchronen Handshake {#va-api-features-v3__synchronous_support_enhancements} Ab Version 3.0.x kann Virtual Agent API synchron an einen Servicemitarbeiter übertragen. Wenn ein -Benutzer oder Service Desk-Mitarbeiter eine Konversation beendet, erfolgt die Übertragung zurück an Virtual Agent ebenfalls synchron. Einige Systemnachrichten und Wartezeitnachrichten werden auch synchron gesendet. Beachten Sie bei der Verwendung der synchronen Übertragung an einen Servicemitarbeiter die folgenden Richtlinien: * Konfigurieren Sie den Antwortendpunkt Virtual Agent. Mitarbeiterchat Nachrichten werden an den von Ihnen angegebenen Endpunkt übermittelt. * Sie müssen Benachrichtigungen für die Instanz manuell deaktivieren. * Wenn Sie die synchrone Übertragung an einen Servicemitarbeiter verwenden, sendet Virtual Agent API den Eingabeindikator, sofern aktiviert: { "uiType": "ActionMsg", "actionType": "StartTypingIndicator", } * Themen, die die folgenden Funktionen verwenden, werden im synchronen Modus nicht unterstützt: [Datei-Upload](https://servicenow-prod.fluidtopics.net/3zaUFpbXKVVAwZAaqD2zwQ "Nutzen Sie die verschiedenen Eingabesteuerelemente, die in Virtual Agent-Designer verfügbar sind, um Informationen von Benutzern in Konversationen abzufragen und zu erfassen."), [Aktionsdienstprogramm](https://servicenow-prod.fluidtopics.net/0fru34jhJzCB0atBuWKCkQ "Verwenden Sie das Aktionsdienstprogramm in einem Virtual Agent -Thema, um die Flow-Aktionseigenschaften auszuwählen, die der Knoten erstellen soll. Das Aktionsdienstprogramm integriert Virtual Agent in das Produkt ServiceNow Workflow-Studio.")und der [Themenblock Pause](https://servicenow-prod.fluidtopics.net/4xPY1kqnSfDOEDbjnUXB1w "Virtual Agent stellt vorgefertigte Themenblöcke bereit, mit denen Themenautoren oder -administratoren in Bot-Konversationen bestimmte plattformbezogene Funktionen oder Aufgaben ausführen können. Mit bestimmten Themenblöcken können Sie beispielsweise die Mitarbeiterverfügbarkeit überprüfen oder KI-Suche -Ergebnisse generieren."). {#va-api-features-v3__ul_pmt_p2s_2rb} Um diese Funktionen zu deaktivieren und synchrone Unterstützung zu aktivieren, gehen Sie wie folgt vor: 1. Navigieren zu Allesys_cs_channel.list. 2. Wählen Sie den Datensatz Bot zu Bot aus. 3. Deaktivieren Sie das Kontrollkästchen Benachrichtigungen aktivieren, um es zu deaktivieren. 4. Wenn Sie im synchronen Modus nicht an einen Servicemitarbeiter übertragen, deaktivieren Sie das Kontrollkästchen Support-Eingabeindikator, um ihn zu deaktivieren. 5. Aktivieren Sie die Checkbox Synchron. Abbildung : 1. Bot-zu-Bot-Kanal mit aktivierter synchroner Unterstützung 6. Klicken Sie auf Aktualisieren. {#va-api-features-v3__ol_icm_x3j_gqb} ## Unterstützung für Aktionsnachrichten {#va-api-features-v3__section_c4v_wr3_dsb} Der primäre Bot oder Chat-Client kann Nachrichten nicht nur an einen sekundären ServiceNow® Virtual Agent -Bot, sondern auch über Mitarbeiterchatan einen Service Desk-Mitarbeiter übergeben. Verwenden Sie den im Anforderungstext übergebenen Parameter action, um anzugeben, wie der Inhalt behandelt werden soll. Virtual Agent API unterstützt die folgenden Aktionsnachrichtentypen:{#va-api-features-v3__table_g3b_cyp_dsb__entry__2} | actionType-Wert | Beschreibung | |-|-| | ChatSubHeader | Ausgehende Nachricht, die angibt, dass eines der folgenden Ereignisse aufgetreten ist: * Dynamische Übersetzung fehlgeschlagen. * Servicemitarbeiter-Autopilot wurde initiiert und abgeschlossen. {#va-api-features-v3__ul_kmy_xcg_hsb} | | StartSpinner | Ausgehende Nachricht, die einen Ladekreisel startet, wenn sich eine Nachricht aufgrund asynchroner Prozesse im Status „Ausstehend" befindet, z. B. KI-Suche oder der Obszönitätsfilter. | | EndSpinner | Ausgehende Nachricht, die den zuvor gesendeten Ladekreisel anhält. | | StartTypingIndicatorActionMsg | Ausgehende Nachricht, die angibt, dass ein Anwender oder Service Desk-Mitarbeiter mit der Eingabe begonnen hat (nachdem ein Service Desk-Mitarbeiter den Chat akzeptiert hat). | | EndTypingIndicatorActionMsg | Ausgehende Nachricht, die angibt, dass ein Benutzer oder Service Desk-Mitarbeiter mit der Eingabe aufgehört hat. | | SubscribeToSupportQueue | Gibt an, dass die Konversation auf die Support-Warteschlange festgelegt ist. | | ChatPresence abonnieren | Ausgehende Nachricht, die angibt, dass eine Konversation mit einem Servicemitarbeiter begonnen hat. | | SwitchToLiveAgent | Ausgehende Nachricht, die angibt, dass ein Servicemitarbeiter die Konversation akzeptiert hat. | | Zu Virtual Agent wechseln | Ausgehende Nachricht, die angibt, dass die Sitzung des Servicemitarbeiters beendet wurde und die Konversation an Virtual Agentzurückgegeben wird. | | SwitchConversation | Ausgehende Nachricht, die angibt, dass eine Benachrichtigung gesendet wurde. Dadurch wird eine neue Konversation erstellt, sodass Virtual Agent zur neuen Konversation wechselt. | | System | Ausgehende Nachricht, die eine der folgenden Optionen angibt: * Ein Servicemitarbeiter hat die Kat. eingegeben. * Entweder der Servicemitarbeiter oder der Benutzer hat den Chat geschlossen. * Bei der Konversation mit einem Servicemitarbeiter ist eine Zeitüberschreitung aufgetreten. {#va-api-features-v3__ul_bdd_nlq_dsb} | [Tabelle : 1. Unterstützte Aktionsnachrichtentypen] {#va-api-features-v3__table_g3b_cyp_dsb} ## Unterstützung für die Kennzeichnung „stummMessage". {#va-api-features-v3__section_t1b_lrq_dsb} Eine stille Nachricht ist eine Nachricht, die keine Antwort erfordert. Wenn Virtual Agent eine Anforderung mit silentMessage=true\] erhält, werden alle nachfolgenden Bot-Nachrichten unterdrückt, bis Virtual Agent eine Anforderung zum Deaktivieren des unbeaufsichtigten Modus (silentMessage=false) erhält. Beispiel-Nachrichtennutzlast vom primären Bot: { "token": "BOT_TOKEN", "botToBot": true, "clientSessionId": "884502214730301027f83ee4070f589a", "clientVariables": {}, "requestId": "48450221d23030107300b7756770bc9b", "silentMessage": "true", "timestamp": 1623916324820, "timezone": "GMT", "userId": "abel.tuter", "emailId": "abel.tuter@example.com" } Hinweis: Bei silentMessage=truewerden Benachrichtigungen nicht zugestellt. ## Sichere Datei-Uploads von einer privaten URL {#va-api-features-v3__section_xjy_j12_2rb} Virtual Agent API unterstützt das Hochladen von Dateien mit einer Größe von bis zu 1 GB von einer privaten URL. Der primäre Bot muss die Anwender-ID, die optionale ID der Anbieteranwendung und den Namen der Datei übergeben. Beachten Sie die folgenden Richtlinien: * Anbieteranwendungs-ID ist optional. * Die Anwender-ID und die ID der Anbieteranwendung müssen vor dem Dateinamen in der Nutzlast gesendet werden. * Der Endanwender muss eine Rolle aufweisen, die in der Eigenschaft glide.attachment.role angegeben ist. Weitere Informationen finden Sie [unter Zum Anhängen von Dateien eine Rolle erfordern](https://www.servicenow.com/docs/access?context=t_DisablingTheDragAndDropFeature&version=xanadu&pubname=xanadu-platform-administration&ft:locale=en-US). * Standard- oder OAuth-Authentifizierung wird unterstützt, Nachrichtenauthentifizierung jedoch nicht. {#va-api-features-v3__ul_dvc_vn2_2rb} Beispiel-Nachrichtennutzlast vom primären Bot: curl -X POST \ https://instance.service-now.com/api/now/v1/cccif/media/upload \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H 'content-type: multipart/form-data; \ -F user_id=xxxxxx \ -F provider_application_id=optionalId \ -F 'file=@SomeFile.png' Virtual Agent API sendet das folgende JSON-Beispiel: { "result": { "mediaUrl": "http://123.456.7.8:8080//api/now/v1/cs/media/string", "name":"imagefile.png", "state":"pending", "attachmentId":"abcdefghijklmno12345" } }