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

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：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 の「送信元」電話番号など)。
    • 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 を使用します。仮想エージェントがオプションを含むメッセージを送信すると、受信者はオプションを選択します。サブフローは、選択に基づいてメッセージ表示を更新し、オプションを削除します。会話は、ユーザーが選択したオプションに基づいて続行されます。仮想エージェントは、外部要求を送信しようとするのではなく、メッセージの処理を続行するために解放されます。サブフローを作成するときは、サブフロー内でアクションを呼び出すアクションを持たせないでください。サブフローの詳細については、「 」を参照してください。

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

    コンテキストアクションスクリプトは、仮想エージェントトピック内でエージェントを入力するなどの特別なキーワードアクションを実行して、ライブエージェントにすぐに渡します。

    表 : 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です。要求者が入力テキストに応答している場合は、テキスト応答です。
    • 値: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」が設定され、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);