Virtual Agent Aktionsskripts

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 9 Minuten Lesedauer

    • Sie müssen einen Satz von obligatorischen schreiben Workflow-Studio Aktions- und Subflow-Skripts, um die Anwenderdaten an VACS zu übergeben, Transformationen anzuwenden und die Antwort an Ihren Chat-Schnittstellenendpunkt zurückzusenden.

    Provider und ein-/ausgehende Skripts

    Ein Anbieter, z. B. Twilio, stellt die Chat-Fähigkeit bereit. Anwenderaktionsskripts führen Anbieteraktionen sowie die Konfiguration der anwenderdefinierten Chat-Integration für Konversationen für eingehende und ausgehende Umwandleraktionen für Ihren Chatbot oder anwenderdefinierte Konversationen aus. Beispiele für jedes Skript werden bereitgestellt. Sie enthalten eine Beschreibung dessen, was jedes Skript tut, sowie die Aktionseingabe und Aktionsausgabe. Sie sehen auch Beispiele für das Skript-JSON.

    Sie verwenden Workflow-Studio Zum Erstellen dieser Skripts zum Transformieren von Server- und Client-Nachrichten. Provider, Absender und ein-/ausgehende Umwandlerskripts sind erforderlich. Sie können die zusätzlichen Skripts verwenden, um Ihrem Chat weitere Funktionen hinzuzufügen.

    Tabelle : 1. Skripte
    Skriptname Zweck Erforderlich (J/N)
    Anbieterattribut Enthält ein Provider-Authentifizierungstoken, einen Anwenderbezeichner, Anwendereingabe und Kontextvariablen. Y
    Absenderaktion

    Bündelt die Anforderung und sendet eine Antwort asynchron über Workflow-Studio Oder Integrations-Hub.

    		 Y
    Antwortprozessor Führt Plattformaktionen aus, z. B. einen Aktualisierungsnachrichtenstatus, der auf einer Antwort basiert, die für eine ausgehende Nachricht empfangen wurde. ​ N
    Kontextbezogene Aktion Unterstützt kontextbezogene Aktionen. N
    Accountaktion verknüpfen Bietet einen Rückruf darüber, ob die Accountverknüpfung erfolgreich war oder nicht​. N
    Ausgehender Umwandler Wandelt die unterstützte Steuerung eines Chatservers in ein Chat-Schnittstellenspezifisches Rendern um. Y
    Eingehender Umwandler Optional. Sie können die standardmäßigen Rich-Steuerungen verwenden, wenn sie für Ihren Chatanbieter gelten. Sie müssen nicht für jedes Eingabesteuerelement eine separate eingehende Transformation bereitstellen. Wenn ein Standardverhalten nicht funktioniert, können Sie den Standard mit Ihrer eigenen eingehenden Transformation für ein bestimmtes Virtual Agent-Serversteuerelement überschreiben. Y

    Aktionsskript für Provider-Attribute

    Das Aktionsskript „Provider-Attribute“ extrahiert Daten aus der eingehenden Nachricht. Das Skript kennt das anwenderdefinierte Protokoll zur Chat-Integration für Konversationen und gibt den Inhalt der eingehenden Nachricht, die Anwender-ID des Absenders und ein optionales Authentifizierungstoken aus.
    Hinweis:
    Wenn Ihr Aktionsskript für Provider-Attribute eine kontextbezogene Aktion aufweist, muss Ihr Skript sowohl „Request_context.contextual_action“ als auch „Request_context.typed_value“ haben, damit die Anwendereingabe (die mit einer kontextbezogenen Aktion abgeglichen wird) im Transkript enthalten ist. Wenn Sie „Request_context.type_value“ nicht festlegen, wird dieser Nachrichteninhalt nicht im Transkript angezeigt.
    Tabelle : 2. Eingabe/Ausgabe des Skripts für Anbieterattribute-Aktion
    Eingabe Ausgabe
    • Header (JSON): Anforderungsheader
    • Nutzlast (JSON): Anforderungstext ​
    • Token (Zeichenfolge): Authentifizierungstoken.
    • Provider_user_ID (Zeichenfolge): Name des Absenders, z. B. ein Anwendername in einer Slack-Nachricht.
    • Request_context (JSON): Tatsächlich erhaltener Inhalt.
      • Typed_value: Eingetippter Inhalt, z. B. eine Antwort auf eine Frage.
      • Attachment_value.url: URL des Anhangs.
      • Attachment_value.content_type: Inhaltstyp des Anhangs.
      • attachment_value.name: Dateiname des Anhangs.
      • Kontextbezogene Aktion: Auszuführende Aktion, z. B. END_CONVERSATION, START_CONVERSATION, AGENT. Dieses Skript betrachtet die eingehende Nachricht. Wenn ein erkanntes Stichwort vorhanden ist, kann eine der Aktionen festgelegt werden, z. B. Ausgaben.Request_context.contextual_action = „END_CONVERSATION“;. Das Framework erkennt dieses Stichwort und ruft das kontextbezogene Aktionsskript auf.
      • Context_vars: Kontextbezogene Variablen, die an eine Konversation übergeben werden sollen, z. B. „output.Request_context.context_vars = {language: „en“};“.
    Abbildung : 1. Beispiel: Workflow-Studio Eingabe des Aktionsskripts für Provider-Attribute, einschließlich Header und Nutzlast
    Eine Aktionseingabe in Workflow-Studio Mit Headern und Nutzlast, die auf die Verwendung von JSON festgelegt sind.
    Abbildung : 2. Beispiel: Workflow-Studio Ausgabe des Aktionsskripts für Provider-Attribute, einschließlich Token, Request_context und Provider_user_ID
    Eine Aktionsausgabe in Workflow-Studio Gibt die Werte „Token“, „Request_context“ und „Provider_user_ID“ an.

    Beispiel: Aktionsskript für Provider-Attribute.

    (function execute(inputs, outputs) {
    var headers = (inputs.headers);
    var payload = (inputs.payload);

    // check if an authentication token was included. this is optional.
    var smsUtil = new VASMSTwilioUtil();
    outputs.token = JSON.stringify(smsUtil.getToken(headers, payload));

    var data = payload.data;
    var request_context = {}; 
    // inspect the actual message. it could be an MMS (attachment) or raw text
    if (data['MediaUrl0']) {
        var attachment_value = {};
        attachment_value.url = data['MediaUrl0'];
        attachment_value.content_type = data['MediaContentType0'];
        attachment_value.name = smsUtil.getFileName(attachment_value.url , attachment_value.content_type);
        request_context.attachment_value = attachment_value;
    } else {
       request_context.typed_value = data['Body'];
    }

    // set the mandatory outputs
    outputs.request_context = request_context;
    outputs.provider_user_id = data.From;
})(inputs, outputs);

    Absenderaktionsskript (außer Betrieb genommen in Quebec siehe Absender-Subflow)

    Das Absenderaktionsskript weiß, wie eine Nachricht an den Anbieter gesendet wird. Das Skript sollte asynchron aufrufen Workflow-Studio Oder IntegrationHub subflow. Die Virtual Agent Ist frei, um Nachrichten weiter zu verarbeiten, anstatt zu versuchen, externe Anforderungen zu senden.

    Tabelle : 3. Skripteingabe der Absenderaktion
    Eingabe Ausgabe
    • Ergebnisse (JSON): Array von zu sendenden Nachrichten.
    • Nutzlast (JSON): Letzte Nutzlast, die von einer anfordernden Person empfangen wurde.
    • App_inbound_ID (Zeichenfolge): Bezeichner des Absenders, z. B. die „von“-Telefonnummer in einem SMS-Fall.
    • Channel_user_ID (Zeichenfolge): Bezeichner des Empfängers, z. B. die Telefonnummer „an“ in einem SMS-Fall.
    		 Keine

    Beispiel: Absenderaktionsskript.

    (function execute(inputs, outputs) {
    var results = inputs.results;
    // transform the inputs to something this custom subflow knows about
    var sendInputs = {
        app_inbound_id : inputs["app_inbound_id"],
        channel_user_id: inputs["channel_user_id"],
        messages: JSON.stringify(results)
    };

    // invoke an asynchronous subflow which will send the external request. so this sender script will immediately return,
    // freeing up the chat server thread to do further message processing while putting the external request work on the
    // Workflow Studio/Integration Hub
    sn_fd.FlowAPI.startSubflowQuick('sn_va_sms_twilio.va_sms_twilio_adapter_send_sms', sendInputs);
})(inputs, outputs);

    Absender-Subflow

    Anstelle eines Skripts verarbeitet der Absender-Subflow den Prozess des Sendens einer Nachricht an einen Anbieter. Die Nachricht ist in enthalten payloadZeichenfolge als Teil des Subflows. Der Absender hat einen service_urlUnd origin_service_url, Während die ausgehende URL je nach Anbieter variiert. Beispielsweise verwendet eine Nachricht, die über MS Teams gesendet wird, den Wert tenant_id. Wenn Virtual Agent die Nachricht mit Optionen sendet, wählt der Empfänger eine Option aus. Der Subflow aktualisiert die Nachrichtenanzeige basierend auf ihrer Auswahl und entfernt die Optionen. Die Konversation wird basierend auf der ausgewählten Option des Anwenders fortgesetzt. Die Virtual Agent Ist frei, um Nachrichten weiter zu verarbeiten, anstatt zu versuchen, externe Anforderungen zu senden. Wenn Sie einen Subflow erstellen, haben Sie keine Aktion, rufen Sie eine Aktion innerhalb des Subflows auf. Weitere Informationen zu Subflows finden Sie unter Subflows and actions.

    Skript für kontextbezogene Aktion

    Das Skript für kontextbezogene Aktionen führt spezielle Stichwortaktionen wie die Eingabe aus Service Desk-Mitarbeiter Während in einem Virtual Agent Thema, das sofort an einen Servicemitarbeiter übergeben werden soll.

    Tabelle : 4. Skripteingabe für kontextbezogene Aktion
    Eingabe Ausgabe
    • Conversation_ID (Zeichenfolge): Die Konversations-ID.
    • Request_context (JSON): Anforderung, die vom Attributskript des Anbieters übergeben wurde, das die auszuführende Aktion enthält, z. B. (END_CONVERSATION, START_CONVERSATION, AGENT).
    		 Keine

    Beispiel: Kontextbezogenes Aktionsskript.

    (function execute(inputs, outputs) {
  var contextual_action = inputs.request_context.contextual_action;
  if (contextual_action === "END_CONVERSATION") {
    sn_cs.VASystemObject.endConversation(inputs.conversation_id);
  } else if (contextual_action === "AGENT") {
    sn_cs.VASystemObject.switchToLiveAgent(inputs.conversation_id);
  } else if (contextual_action === "START_CONVERSATION") {
    sn_cs.VASystemObject.startConversation(inputs.conversation_id);
  }
})(inputs, outputs);

    Accountaktionsskript verknüpfen

    Das Aktionsskript „Account verknüpfen“ enthält Bezeichner für den Anwender, der die Verknüpfung durchführt. Das Skript enthält auch den Account, mit dem es verknüpft ist.

    Tabelle : 5. Skripteingabe der Accountaktion verknüpfen
    Eingabe Ausgabe
    • Provider_user_ID (Zeichenfolge): Bezeichner des Anwenders, der die Verknüpfung durchführt, z. B. eine Telefonnummer in einem SMS-Fall.
    • Status (Zeichenfolge): Erfolg/Fehler.
    • User_ID (Zeichenfolge): ServiceNow user_sys_ID für den Account, mit dem verknüpft wurde.
    		 Keine

    Beispiel: Accountaktionsskript verknüpfen.

    (function execute(inputs, outputs) {
  
  var richControl = (inputs.rich_control);
  var value = richControl.value;
  outputs.result = richControl.header + ': ' + value.action;
  
})(inputs, outputs);

    Antwortprozessor-Aktionsskript

    Das Antwortprozessoraktionsskript führt Spezialaktionen aus, die auf der Antwort auf eine Sendeanfrage basieren. Das Framework führt bereits eine grundlegende Nachverfolgung des Nachrichtenstatus durch.

    Tabelle : 6. Eingabe des Accountaktionsskripts des Antwortprozessors
    Eingabe Ausgabe
    • Message_ID (Zeichenfolge): Bezeichner des sys_cs_message-Datensatzes, der dieser Antwort zugeordnet ist.
    • Header (JSON): Empfangene Header.
    • Textkörper (Zeichenfolge): Textkörper, der empfangen wird.
    • Statuscode (Ganzzahl): Der empfangene HTTP-Statuscode.
    		 Keine

    Beispiel: Antwortprozessor-Aktionsskript.

    (function execute(inputs, outputs) {
    gs.debug("Response from provider: message_id = " + inputs.message_id + ", status_code = " +
      inputs.status_code + ", headers = " + JSON.stringify(inputs.headers) + ", body = " + inputs.body);
})(inputs, outputs);

    Ausgehende Umwandlerskripts

    Die ausgehenden Umwandlerskripts konvertieren ausgehend Virtual Agent Nachrichten an ein Protokoll, das sich auf die Integration des anwenderdefinierten Chats für Konversationen bezieht.

    Eingabe.

    • Rich_Control (JSON) – Virtual Agent Umfassende Serversteuerungskomponente, die transformiert werden muss.
    • Nutzlast (JSON): Letzte Antwort, die von einer anfordernden Person empfangen wurde.

    Ausgabe.

    Ergebnis (Zeichenfolge): Nachricht der anbietergeeigneten Komponente zum Senden.

    Tabelle : 7. Beispiele: Ausgehende Transformatorskripts
    Name des ausgehenden Transformators Skriptbeispiel
    Adapter „Virtual Agent – SMS Twilio“ Standardtext Ausgehender Umwandler 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  outputs.result = rich_control['label'];
})(inputs, outputs);
    Adapter „Virtual Agent – SMS Twilio“ Standardlink Ausgehender Umwandler 
    (function execute(inputs, outputs) {
  var richControl = (inputs.rich_control);
  var value = richControl.value;
  outputs.result = richControl.header + ': ' + value.action;
})(inputs, outputs);
    Adapter „Virtual Agent – SMS Twilio“ Standardauswahl Ausgehender Umwandler 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  var options = rich_control['options'];
  if (options && options.length > 0) {
      var optionsLength = options.length;
      var picker = rich_control['label'] || "";
      for (var x = 0; x < optionsLength; x++) {
          picker += "\n" + (x+1) +  ": " + options[x].label;
      }
  }
  outputs.text_message = picker;
})(inputs, outputs);
    Adapter „Virtual Agent – SMS Twilio“ Standard Ausgehender Multilink-Umwandler 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  var linkResult = rich_control['header'];
  var totalValues = rich_control['values'].length;
  for (var i = 0; i < totalValues; i++) {
    linkResult = linkResult + '\n';
    var linkValue = rich_control['values'][i];
    linkResult = linkResult + '\n' + linkValue['description'] + ': ' + linkValue['action'];
  }
  outputs.result  = linkResult;
})(inputs, outputs);
    Adapter „Virtual Agent – SMS Twilio“ Standardkarte Ausgehender Umwandler 
    (function execute(inputs, outputs) {
  var richControl = (inputs.rich_control);
  var data = JSON.parse(richControl.data);    
  var tableTitle = data.title;
  var fields = data.fields;
  var subtitle = data.subtitle;
  var url = data.url;    
  var message = subtitle ? getCardLine(tableTitle, subtitle) : tableTitle + "\n";
  for (var i= 0; i<fields.length; i++) {
     message += getCardLine(fields[i].fieldLabel, fields[i].fieldValue);
  }
  message += url;
  outputs.result = message;

  function getCardLine(key, value) {
      if (value == '' || value == null || key == '' || key == null)
          return;
      return key + ": " + value + "\n";
  }
})(inputs, outputs);

    Eingehende Umwandlerskripts

    Die eingehenden Umwandlerskripts konvertieren eingehende anwenderdefinierte Chat-Integrationsnachrichten für Konversationen in ein Protokoll, das der Virtual Agent Erkennt an. Bestimmt den erforderlichen Wert, der in die Rich-Steuerung eingefügt werden soll, die dem Anwender angezeigt wird.

    Eingabe.

    • Request_context (JSON): Die Anforderung, die vom Anbieterattribut-Skript übergeben wurde.
    • Rich_Control (JSON): Die letzte Rich-Steuerung, die an die anfordernde Person gesendet wurde und die ursprüngliche „Frage“ enthält.

    Ausgabe.

    Ergebnis (JSON): Das von erwartete Ergebnis Virtual Agent Server. Wenn die anfordernde Person auf eine Themenauswahl antwortet, ist dies die sys_ID des Themas. Wenn die anfordernde Person auf einen Eingabetext antwortet, ist dies die Textantwort.
    • Wert: Sys_ID oder Textwert.
    • Search_Text: Text, der verwendet wird, wenn die anfordernde Person etwas unerwartetes ausgewählt hat. Beispielsweise hat ein Anwender etwas eingegeben, bei dem die NLU helfen könnte, z. B. „keine dieser Optionen stimmt mit dem überein, was ich möchte“ als Antwort auf eine Themenauswahlkomponente.
    Tabelle : 8. Beispiele: Eingehende Transformatorskripts
    Name des eingehenden Umwandlers Skriptbeispiel
    Adapter „Virtual Agent – SMS Twilio“ Standard Eingehender Umwandler Für Text

    Zweck: Suchen Sie die Textantwort auf die gestellte Eingabetext-Frage

    		 
    (function execute(inputs, outputs) {
  var requestContext = inputs.request_context;
  var richControl = inputs.rich_control;
  var typedValue = requestContext['typed_value'];
  var attachmentValue = requestContext['attachment_value'];
  var smsUtil = new VASMSTwilioUtil();
  var result = {};
  if(richControl['itemType'] == 'image' || richControl['itemType'] == 'file')	{
    if (attachmentValue && attachmentValue.content_type.includes('image')) {
      result.url = attachmentValue.url;
      result.content_type = attachmentValue.content_type;
      result.name = attachmentValue.name;
      result.headers = attachmentValue.headers;
    } else if (typedValue) {
      result.url = typedValue;
      var contentType = smsUtil.getContentType(typedValue);
      if (typeof contentType === 'undefined')
        gs.error('Please enter a valid image link. Inbound image link: {0}', typedValue);
      else
        result.content_type = contentType;
    } else {
      gs.error('Please upload an image or enter a valid image link.');
    }
  }
  result['value'] = typedValue;
  result['search_text'] = '';
  outputs.result = result;
})(inputs, outputs);
    Adapter „Virtual Agent – SMS Twilio“ Standard Auswahl – Eingehender Umwandler

    Zweck: Suchen Sie die sys_ID der Option, die der Anwender für diese Auswahlfrage ausgewählt hat. Dieses Skript verwendet denselben Algorithmus des ausgehenden Umwandlers. Wenn keine Optionen ausgewählt sind und der Anwender stattdessen etwas eingegeben hat, wird „search_Text“ festgelegt und in NLU eingespeist, wenn er in dieser Instanz aktiviert ist.

    		 
    (function execute(inputs, outputs) {
  var request_context = inputs.request_context;
  var rich_control = inputs.rich_control;
  var selectedValue = request_context["typed_value"];
  var result = {};
  result["value"] = "";
  result["search_text"] = "";
  if (rich_control['options']) {
    var options = rich_control['options'];
    var optionsLength = options.length;
    selectedValue === Number(selectedValue)
    if (selectedValue > 0 && selectedValue <= optionsLength) {
        var selectedOption = options[selectedValue - 1];
        result["value"] = selectedOption.value;
    } else {
        result["search_text"] = request_context["typed_value"];
    }
  }
  outputs.result = result;
})(inputs, outputs);