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

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：14分

    • ServiceNow® 仮想エージェントスクリプトメソッドと変数を使用して、応答、トリガー、フロースクリプトなどのチャットスクリプトを記述します。変数は、ライブサポートトピックと会話のコンテキストを提供することもできます。

    仮想エージェント スクリプトは、ユーザーまたはユーザーの入力に関する情報を保持するなど、トピックのコンテキストを提供できます。この情報を使用して、スクリプトによる挨拶や確認を表示するなど、会話をカスタマイズできます。スクリプトでは、会話中に得られた情報に対して実行する特定のアクションを指定することもできます。これらのアクションを使用して、 ServiceNow レコードを作成または更新できます。

    スクリプトは、トピックが定義されているスコープ内のサーバー上で実行されます。すべてのスコープ保護が適用されます。スコープ対象のアプリケーションの会話を開発する場合は、スコープ付き API を使用する必要があります。サーバースクリプトで実行されるほとんどの API を使用できます。

    ユーザー入力および ServiceNow レコード変数

    仮想エージェント では、トピック用に作成するスクリプトで次の変数を使用できます。

    ユーザー入力変数

    入力コントロールをトピックに追加すると、ユーザー入力 (文字列、ブール値など) を格納する変数が自動的に作成されます。構文は vaInputs.myvar で、 myvar は入力ノードに割り当てた名前です。

    たとえば、「 最初のプロンプト 」という名前のテキスト入力プロンプトには、「 vaInputs.first_prompt」と呼ばれるシステム定義変数があります。名前のスペースはアンダースコア文字に置き換えられ、大文字は小文字に変更されます。

    ServiceNow レコード変数

    ServiceNowテーブルにクエリを実行するトピックのスクリプトを作成すると、返されたレコードオブジェクト (GlideRecord) がトピックで自動的に使用できるようになります。変数の構文は vaInputs.myvar で、 myvar はレコードオブジェクトです。ServiceNowテーブルをクエリしてレコードオブジェクトを返す方法の詳細については、「スクリプトでのテーブルのクエリ」を参照してください。

    ServiceNowレコードを含む変数でドット連結を使用して、テーブルの特定のフィールドを指定します。構文は vaInputs.myvar.field です。スクリプト内でのドット連結の詳細については、「 ドット連結の例」を参照してください。

    ユーザー入力と ServiceNow レコード変数へのアクセス

    vaInputs オブジェクトを使用して、スクリプト内のServiceNowレコード変数にアクセスします。たとえば、 vaInputs.myvar == "expected value" です。レコードではないユーザー入力から値にアクセスするには、 vaInputs.myvar.getValue() を使用します。

    次の方法が利用可能です。

    表 : 1. vaInputs メソッド
    手法 説明
    vaInputs.myvar == "expected value" myvar が予想値と一致するかどうかを評価します。
    注:
    ユーザー入力変数の値は、ユーザー入力コントロールを使用して割り当てられます。これらの値はスクリプト内では変更できません。
    • オーストラリア リリースでは、追加のデータタイプがサポートされています。詳細については、「仮想エージェントトピックの入力データタイプ」を参照してください。
    • デフォルトでは、ユーザー変数は利用可能であり、ユーザーのsys_userレコードへの参照となります。
    vaInputs.myvar.getValue(); 値を返します。
    vaInputs.myvar.getDisplayValue();

    保存された値が ServiceNow レコードでない場合は表示値を返します。ServiceNowレコードを含む変数の場合、このメソッドは、そのテーブルの表示フィールドで定義された表示値を返します。

    次の例は、ユーザー入力のラベルと選択値を示しています。この場合、 myVar.getValue() は 10、20、または 30 の値を返し、 myVar.getDisplayValue() は Apple、Orange、または Pear を返します。

    図 : 1. 選択リストの例
    ラベルフィールドには、選択肢として Apple、Orange、および Pear が含まれます。それぞれの値は 10、20、および 30 です。
    vaInputs.myvar.getDefaultValue(); 確認メッセージでデフォルト値を返します。
    vaInputs.myvar.getDefaultDisplayValue(); 確認メッセージのデフォルト値の表示値を返します。
    vaInputs.myvar.unbindEntity(); NLU予測サービスによって抽出されたエンティティがスロットに入力された入力変数の値を削除します (初期入力値からバインド解除されます)。

    たとえば、ユーザーが確認プロンプトで選択を変更する場合は、入力変数からエンティティの値をバインド解除できます。ユーザーが対応する入力ノードに戻ると、再度プロンプトが表示されます。

    注:
    NLU トピックで有効にする必要があります。アシスタントデザイナーで、[プロパティ] タブを選択してNLUを設定します。NLUエンティティの定義については、「エンティティ」を参照してください。

    スクリプト変数

    ServiceNowテーブルには格納されていないが、トピック内の他の場所で情報を共有するために使用できる情報に対してスクリプト変数を定義できます。スクリプト変数は、整数、ブール値、文字列などのプリミティブを格納するワークフロースクラッチパッド変数に似ています。文字列値は、静的または動的なスクリプト値のいずれかです。変数サイドバーを使用して、 アシスタントデザイナー のトピックのスクリプト変数を定義します。

    図 : 2. 変数サイドバー
    トピックスクリプトで使用されるスクリプト変数を手動で追加するためのアシスタントデザイナー キャンバスのサイドバー。
    注:
    スクリプト変数は、高度なスクリプティングスキルを持つトピック作成者が使用することを目的としています。

    変数の構文は vaVars.myvar です。 ここで、myvar は変数に割り当てる名前です。たとえば、 vaVars.myvar = value; を使用して変数に値を割り当てることができます。ユーザー入力変数とは異なり、スクリプト変数にはスクリプト内の値を割り当てることができます。

    トピックでのスクリプト変数の定義については、「 トピックのスクリプト変数の定義」を参照してください。

    コンテキスト変数

    コンテキスト変数はグローバルスコープで機能しますが、システム変数はトピックのスコープ内で機能します。Web クライアント URL 内のシステムパラメーターでコンテキスト変数を使用できます。これらの変数は、 vaContext オブジェクトを使用して会話のどこでも使用できます。これらのオプションを使用して、事前定義された変数で 仮想エージェント へのリンクを作成します。

    次のリンク例には、 パラメーター sysparm_city=milan が含まれています。仮想エージェント会話を開くだけでなく、このリンクを使用すると、値が milan の city という変数が作成されます。この変数には、 vaContext.city を使用してスクリプトでアクセスできます。

    https://<instance>.service-now.com/$sn-va-web-client-app.do?sysparm_city=milan
    多くの ライブエージェント 変数をトピックスクリプトで使用できます。これらの変数には次のものが含まれます。
    • application
    • language
    • portal
    • search_text
    • short_description

    変数構文は vaContext.LiveAgent_myvar です。 ここで、myvar は使用可能な ライブエージェントコンテキスト変数の 1 つです。vaContext.LiveAgent_myvar = value; を使用して変数にアクセスします。

    トピックスクリプトで ライブエージェント 変数を使用するには、 アシスタントデザイナーでトピックを開きます。[ プロパティ] タブで、[ ライブエージェント変数 ] の横にある鉛筆アイコンを選択して、トピックに追加します。

    仮想エージェントに含まれるライブエージェントコンテキスト変数の詳細については、「ライブエージェントチャットコンテキスト変数」を参照してください。

    表 : 2. vaVars メソッド
    メソッド 説明
    vaVars.global_utterance スキルピッカーがレンダリングされ、発言が入力されたときに更新されます。

    vaSystem メソッド

    vaSystem オブジェクトのメソッドを使用して、さまざまなタスクを実行できます。これらのタスクには次のようなものがあります。
    • レコードに画像を添付します。
    • 現在のトピックの検索に使用された検索文字列にアクセスします。
    • ライブエージェントが会話を受信できることを確認します。
    • ユーザーをライブエージェントに接続します。
    注:
    文書化されていないシステムメソッドの使用はお勧めしません。これらのメソッドはサポートされておらず、事前の通知なしにいつでも中止または変更される可能性があるためです。
    表 : 3. 仮想エージェントトピックスクリプトで使用されるメソッド
    手法 説明
    vaSystem.applyLinkTemplate(String sysId, String tableName, String actionName) ポータルに固有の外部リンクを作成します。
    vaSystem.attachRecordToConversation(String tableName, String sysId)

    仮想エージェントインタラクションレコードの [関連タスク] リストにServiceNowレコードを添付します。これらのレコードは、 仮想エージェント 会話中に更新または作成されます。
    vaSystem.attachToRecord(String mediaId, String tableName, String sysId)
    アップロードした画像を ServiceNow レコードに添付します。このメソッドでは、次のパラメーターを使用します。
    • mediaId:添付する画像のパス。顧客が入力した画像を使用するには、画像入力変数で getValue() を使用します。たとえば、 vaInputs.image_input.getValue() などです。
    • tableName:テーブルの名前を含む文字列。
    • sysId:レコードのsys_id。
    vaSystem.connectToAgent() 顧客をライブエージェントに接続します。このメソッドの詳細については、「 ライブエージェントへの 仮想エージェント 会話の転送」を参照してください。
    vaSystem.didConnectToLiveAgent() 現在の会話がライブエージェントに接続されたかどうかを示すブール値 (true または false) を返します。
    vaSystem.getClosingMessage() システムプロパティ com.glide.cs.general.closing_message から会話の終了メッセージを返します。(メッセージは、 Microsoft Teams や Slack などのサードパーティのメッセージングアプリでは異なります)。
    vaSystem.getConversationId() 現在の会話の会話 ID を返します。
    vaSystem.getGreetingMessage() UI メッセージから、「こんにちは。私は仮想エージェントです。今日はどうお役に立てるか教えてください。」
    vaSystem.getInteractionSysId() 現在の会話のインタラクション ID を返します。
    vaSystem.getSearchText() ユーザーが最後に入力した発言を返します。
    vaSystem.getTopicSelectionMessage() キー「問題または要求は何ですか? または、私が何を手伝うことができるか見てください。」(メッセージは、 Microsoft Teams や Slack などのサードパーティのメッセージングアプリでは異なります)。このメソッドは、システムプロパティ com.glide.cs.topic_picker_msg から返されます。
    vaSystem.getTranscript() 会話のトランスクリプトを取得します。
    vaSystem.isLiveAgentAvailable() ライブエージェントがボットから転送された会話を受信できるかどうかを確認します。会話をライブエージェントに転送するには、 vaSystem.connectToAgent() を使用する前にこのメソッドを呼び出します。
    vaSystem.isLiveAgentConfigured() ライブチャットが有効かどうかを返します。
    vaSystem.resetAllEntities() 会話に記録されたすべてのエンティティをリセットします。
    vaSystem.sendBatchedMessages() キューに格納されたメッセージをすぐに送信します。
    vaSystem.sendSeparatorMessage() セパレーターメッセージ行を送信し、 getClosingMessage() から終了メッセージを返します。
    vaSystem.sendSystemMessage(String message, Boolean showAvatar) システムメッセージを送信し、 getGreetingMessage() から挨拶メッセージを返します。
    vaSystem.sendTopicPickerControl(String topicSelectionMessage, String topicPickerButtonLabel) メッセージと [すべて表示] ボタンのラベルに関連付けられた値を含むトピックピッカーコントロールを送信します。
    vaSystem.sendSkillPickerControl(skillSelectionMessage, args)

    スキルピッカーコントロールをユーザーに送信します。

    skillSelectionMessage は、ピッカーを表示する前に表示されるメッセージです。args パラメーターを使用すると、追加の構成オプションを使用できます。

    • hideSkillDetails は、スキル選択メッセージを非表示にします。デフォルトは false です。
    • hidePromotedTopics は、昇格されたトピックをスキルピッカーから非表示にします。デフォルトは false です。
    • hideShowMeEverything は、スキルピッカーから [すべて表示] ボタンを削除します。デフォルトは false です。
    • 該当するスキルがない場合、showNoSkillsConfigured に「スキルが構成されていません」というメッセージが表示されます。デフォルトは false です。
    • appendPromotedSkillsToMsg は、昇格されたスキルの箇条書きリストをスキル選択メッセージに追加します。デフォルトは true です。
    vaSystem.switchTopicByName() ユーザーが現在の会話トピックから指定されたトピック名にジャンプできるようにします。[ X ] ボタンが使用可能で、ユーザーは会話を終了できます。トピックが終了すると、ユーザーはグローバルトピックを再開します。会話が終了したら、ユーザーはチャットウィンドウの下部にある [ ここをクリックして新しい会話を開始する] を選択して、トピックを再開できます。
    オプションの resumeBehavior パラメーターは、次のように会話フローを再開する方法を指定します。
    • resumeBehavior=resumeすると、仮想エージェント呼び出し元トピックが再開されます。
    • resumeBehavior=skip場合、仮想エージェント呼び出し元トピックをスキップします。

    resumeBehaviorが指定されていない場合は、インスタンスのデフォルトの動作が使用されます。
    vaSystem.switchTopicById(sysid) このメソッドは sys_cb_topic の sysid であり、ユーザーが現在の会話トピックから指定されたトピック ID にジャンプできるようにします。[ X ] ボタンが使用可能で、ユーザーは会話を終了できます。トピックが終了すると、ユーザーはグローバルトピックを再開します。会話が終了したら、ユーザーはチャットウィンドウの下部にある [ ここをクリックして新しい会話を開始する] を選択して、トピックを再開できます。
    オプションの resumeBehavior パラメーターは、次のように会話フローを再開する方法を指定します。
    • resumeBehavior=resumeすると、仮想エージェント呼び出し元トピックが再開されます。
    • resumeBehavior=skip場合、仮想エージェント呼び出し元トピックをスキップします。

    resumeBehaviorが指定されていない場合は、インスタンスのデフォルトの動作が使用されます。
    vaSystem.topicDiscovery(String searchTextOverride, Boolean keywordImpl) searchTextOverrideパラメーターの用語に基づいてトピックディスカバリーを実行します。このメソッドでは、次のパラメーターを使用します。
    • searchTextOverride:トピックディスカバリーを実行する文字列。
    • keywordImpl:キーワードを使用するかどうかを決定するブール値。
    表 : 4. 仮想エージェントトピックの外部で使用できる方法
    手法 説明
    sn_cs。VASystemObject.getTranscriptById(<conversation sysId>)

    現在の 仮想エージェント 会話のトランスクリプトを取得します。