仮想エージェントのアクションスクリプト

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：20分

    • ユーザーデータを VACS に渡し、変換を適用し、応答をチャットインターフェイスエンドポイントに戻すには、必須の ワークフロースタジオ アクションとサブフロースクリプトのセットを作成する必要があります。

    プロバイダーおよび着信/送信スクリプト

    チャット機能は Twilio などのプロバイダーにより提供されます。ユーザーアクションスクリプトでは、プロバイダーアクションの実行のほかに、チャットボットまたはカスタム会話の着信/送信トランスフォーマーアクション用に会話型カスタムチャット統合が構成されます。各スクリプトの例が用意されています。これには、各スクリプトの実行内容の説明と、アクション入力およびアクション出力が含まれています。スクリプト JSON の例もあります。

    ワークフロースタジオ を使用して、サーバーメッセージとクライアントメッセージを変換するスクリプトを構築します。プロバイダー、送信者、および着信/送信トランスフォーマースクリプトが必要です。追加のスクリプトを使用して、チャットに機能を追加することができます。

    表 : 1. スクリプト
    スクリプト名 目的 必須 (Y/N)
    プロバイダー属性 プロバイダー認証トークン、ユーザー識別子、ユーザー入力、およびコンテキスト変数が含まれています。 Y
    送信者アクション

    要求をバンドルし、ワークフロースタジオ または統合ハブを介して応答を非同期に送信します。

    		 Y
    応答プロセッサ 送信メッセージに対して受信した応答に基づいて、メッセージステータス更新などのプラットフォームアクションを実行します。​ N
    コンテキストアクション コンテキストアクションをサポートします。 N
    アカウントのリンクアクション アカウントのリンクが成功したかどうかに関するコールバックを提供します​。 N
    送信トランスフォーマー チャットサーバーでサポートされているコントロールを、チャットインターフェイス固有のレンダリングに変換します。 Y
    着信トランスフォーマー オプション。デフォルトのリッチコントロールがチャットプロバイダーに適用される場合は、これらのリッチコントロールを使用できます。入力コントロールごとに個別の着信変換を指定する必要はありません。デフォルトの動作が機能しない場合は、特定の仮想エージェントサーバーコントロールに対し、独自の着信変換でデフォルトを上書きできます。 Y

    プロバイダー属性アクションスクリプト

    プロバイダー属性アクションスクリプトは、受信メッセージからデータを抽出します。このスクリプトは、会話型カスタムチャット統合プロトコルを認識し、着信メッセージの内容、送信者のユーザー ID、およびオプションの認証トークンを出力します。
    注:
    プロバイダー属性アクションスクリプトにコンテキストアクションが含まれている場合、スクリプトには request_context.contextual_action と request_context.typed_value の両方が必要です。これにより、(コンテキストアクションに一致する) ユーザー入力が転写に含まれます。request_context.typed_value を設定しないと、そのメッセージの内容は転写に含まれません。
    表 : 2. プロバイダー属性アクションスクリプトの入力/出力
    入力 出力
    • ヘッダー (JSON)：要求ヘッダー
    • ペイロード (JSON)：要求本文​
    • トークン (文字列)：認証トークン
    • provider_user_id (文字列)：送信者の名前 (Slack メッセージのユーザー名など)。
    • request_context (JSON)：実際に受信した内容。
      • typed_value：あらかじめ入力されている内容 (質問への回答など)。
      • attachment_value.url：添付ファイルの URL。
      • attachment_value.content_type：添付ファイルのコンテンツタイプ。
      • attachment_value.name：添付ファイルのファイル名。
      • コンテキストアクション：実行するアクション (END_CONVERSATION、START_CONVERSATION、AGENT など)。このスクリプトは、受信メッセージを調べます。認識されるキーワードがある場合は、いずれかのアクションを設定できます (outputs.request_context.contextual_action = "END_CONVERSATION"; など)。フレームワークはこのキーワードを認識し、コンテキストアクションスクリプトを呼び出します。
      • context_vars：会話に渡すコンテキスト変数 (`outputs.request_context.context_vars = {language: "en"};` など)。
    図 : 1. 例：ワークフロースタジオ のプロバイダー属性アクションスクリプトの入力 (ヘッダーとペイロードを含む)
    ヘッダーとペイロードが JSON を使用するように設定された ワークフロースタジオ のアクション入力。
    図 : 2. 例：ワークフロースタジオ のプロバイダー属性アクションスクリプトの出力 (トークン、request_context、provider_user_id を含む)
    ワークフロースタジオのアクション出力は、トークン、request_context、およびprovider_user_idの値を指定します。

    例：プロバイダー属性アクションスクリプト。

    (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);

    送信者アクションスクリプト (Quebec で廃止。送信者サブフローを参照)

    送信者アクションスクリプトは、プロバイダーにメッセージを送信する方法を認識しています。このスクリプトは ワークフロースタジオ または 統合ハブ サブフローを非同期に呼び出す必要があります。仮想エージェントは、外部要求の送信を試行する代わりに、メッセージの処理を続行するために解放されます。

    表 : 3. 送信者アクションスクリプトの入力
    入力 出力
    • 結果 (JSON)：送信するメッセージの配列。
    • ペイロード (JSON)：要求者から受信した最後のペイロード。
    • app_inbound_id (文字列)：送信者の識別子 (SMS の「発信元 (From)」の電話番号など)。
    • channel_user_id (文字列)：受信者の識別子 (SMS の「発信先 (To)」の電話番号など)。
    		 なし

    例：送信者アクションスクリプト。

    (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);

    送信者サブフロー

    スクリプトの代わりに、送信者サブフローがプロバイダーにメッセージを送信するプロセスを処理します。メッセージは、サブフローの一部として payload 文字列に含まれています。送信者には service_url と origin_service_urlがありますが、送信 URL はプロバイダーによって異なります。たとえば、MS Teams を介して送信されるメッセージでは、値 tenant_id が使用されます。仮想エージェントがオプションを含むメッセージを送信するときに、受信者はオプションを選択します。サブフローは、選択に基づいてメッセージ表示を更新し、オプションを削除します。会話は、ユーザーが選択したオプションに基づいて続行されます。仮想エージェントは、外部要求の送信を試行する代わりに、メッセージの処理を続行するために解放されます。サブフローを作成するときには、サブフロー内でアクションが別のアクションを呼び出すことがないようにしてください。サブフローの詳細については、「 Subflows and actions」を参照してください。

    コンテキストアクションスクリプト

    コンテキストアクションスクリプトは、仮想エージェントトピック内でライブエージェントにすぐにハンドオフするために、特別なキーワードアクション (「agent」の入力など) を実行します。

    表 : 4. コンテキストアクションスクリプトの入力
    入力 出力
    • conversation_id (文字列)：会話 ID。
    • request_context (JSON)：実行するアクション (END_CONVERSATION、START_CONVERSATION、AGENT など) を含むプロバイダー属性スクリプトから渡される要求。
    		 なし

    例：コンテキストアクションスクリプト。

    (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);

    アカウントリンクアクションスクリプト

    アカウントリンクアクションスクリプトには、リンクするユーザーの識別子が含まれています。スクリプトには、リンク先のアカウントも含まれています。

    表 : 5. アカウントリンクアクションスクリプトの入力
    入力 出力
    • provider_user_id (文字列)：リンクするユーザーの識別子 (SMS の場合の電話番号など)。
    • status (文字列)：成功/失敗。
    • user_id (文字列)：リンク先のアカウントの ServiceNow user_sys_id。
    		 なし

    例：アカウントリンクアクションスクリプト。

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

    応答プロセッサアクションスクリプト

    応答プロセッサアクションスクリプトは、メッセージ送信要求に対する応答に基づく特別なアクションを実行します。フレームワークは、基本的なメッセージステータストラッキングを既に実行しています。

    表 : 6. 応答プロセッサアカウントアクションスクリプトの入力
    入力 出力
    • message_id (文字列)：この応答に関連付けられている sys_cs_message レコードの識別子。
    • headers (JSON)：受信したヘッダー。
    • body (文字列)：受信した本文。
    • status code (整数)：受信した HTTP ステータスコード。
    		 なし

    例：応答プロセッサアクションスクリプト。

    (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);

    送信トランスフォーマースクリプト

    送信トランスフォーマースクリプトは、仮想エージェントの送信メッセージを、会話型カスタムチャット統合に関連するプロトコルに変換します。

    入力。

    • rich_control (JSON)：変換する必要がある仮想エージェントサーバーリッチコントロールコンポーネント。
    • payload (JSON)：要求者から受信した最後の応答。

    出力。

    result (文字列)：送信するプロバイダーに適したコンポーネントメッセージ。

    表 : 7. 例：送信トランスフォーマースクリプト
    送信トランスフォーマー名 スクリプトの例
    仮想エージェント：SMS Twilio アダプタのデフォルトのテキスト送信トランスフォーマー 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  outputs.result = rich_control['label'];
})(inputs, outputs);
    仮想エージェント：SMS Twilio アダプタのデフォルトのリンク送信トランスフォーマー 
    (function execute(inputs, outputs) {
  var richControl = (inputs.rich_control);
  var value = richControl.value;
  outputs.result = richControl.header + ': ' + value.action;
})(inputs, outputs);
    仮想エージェント：SMS Twilio アダプタのデフォルトのピッカー送信トランスフォーマー 
    (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);
    仮想エージェント：SMS Twilio アダプタのデフォルトのマルチリンク送信トランスフォーマー 
    (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);
    仮想エージェント：SMS Twilio アダプタのデフォルトのカード送信トランスフォーマー 
    (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);

    着信トランスフォーマースクリプト

    着信トランスフォーマースクリプトは、会話型カスタムチャット統合の着信メッセージを、仮想エージェントが認識するプロトコルに変換します。これにより、ユーザーに提示されるリッチコントロールに挿入する必要がある値が決定します。

    入力。

    • request_context (JSON)：プロバイダー属性スクリプトから渡された要求。
    • rich_control (JSON)：元の「質問」を含む、要求者に送信された最後のリッチコントロール。

    出力。

    result (JSON)：仮想エージェントサーバーで想定されている結果。要求者がトピックピッカーに応答している場合は、トピックの sys_id です。要求者が入力テキストに応答している場合は、テキスト応答です。
    • value：sys_id またはテキスト値。
    • search_text：要求者が想定されていないものを選択した場合に使用されるテキスト。たとえば、ユーザーがトピックピッカーコンポーネントに応答して、NLU が役立つ可能性がある内容 (「どのオプションも私に必要なものに一致しません」など) を入力した場合などです。
    表 : 8. 例：着信トランスフォーマースクリプト
    着信トランスフォーマー名 スクリプトの例
    仮想エージェント：SMS Twilio アダプタのデフォルトのテキスト着信トランスフォーマー

    目的：提示される InputText の質問に対するテキスト応答を検索します。

    		 
    (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);
    仮想エージェント：SMS Twilio アダプタのデフォルトのピッカー着信トランスフォーマー

    目的：ユーザーがこのピッカーの質問に対して選択したオプションの sys_id を検索します。このスクリプトは、送信トランスフォーマーと同じアルゴリズムを使用します。オプションが選択されておらず、ユーザーが代わりに何かを入力した場合、このインスタンスで「search_text」が有効になっていると、「search_text」が設定され、NLU にフィードされます。

    		 
    (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);