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

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：13分

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

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

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

    ユーザー入力と ServiceNow レコード変数

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

    ユーザー入力変数

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

    たとえば、First prompt という名前を含むテキスト入力プロンプトには、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 が期待値と一致するかどうかを評価します。
    注:
    ユーザー入力変数の値は、ユーザー入力コントロールを使用して割り当てられます。これらの値は、スクリプトでは変更できません。
    • Xanadu リリースでは、追加のデータタイプがサポートされています。詳細については、「仮想エージェント トピックの入力データタイプ」を参照してください。
    • デフォルトでは、ユーザー変数は使用可能であり、ユーザーの 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 内のシステムパラメーターでコンテキスト変数を使用できます。これらの変数は、vContext オブジェクトを使用して、会話のどこでも使用できます。これらのオプションを使用して、事前定義された変数で 仮想エージェント へのリンクを作成します。

    次のリンク例には、sysparm_city=milan のパラメータが含まれています。仮想エージェント の会話を開くことに加えて、このリンクを使用すると、値が milan である変数 city が作成されます。この変数は、vContext.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 つです。vaVars.LiveAgent_myvar = value; を使用して変数にアクセスします。

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

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

    vaSystem メソッド

    vaSystem オブジェクトのメソッドを使用して、さまざまなタスクを実行できます。実行できるタスクには次のようなものがあります。
    • レコードに画像を添付します。
    • 現在のトピックの検索に使用された検索文字列にアクセスします。
    • ライブエージェントが会話を受信できることを確認します。
    • ユーザーをライブエージェントにコネクトします。
    注:
    文書化されていないシステムメソッドの使用はお勧めしません。このようなメソッドはサポートされていないため、事前の通知なしに中止または変更される可能性があります。
    表 : 2. 仮想エージェント トピックスクリプトで使用されるメソッド
    メソッド 説明
    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() 「問題やご要望を教えてください。リストから、私がお手伝いできる内容をご覧いただけます。」といった UI メッセージが返されます。(メッセージは、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.switchTopicByName() ユーザーが現在の会話トピックから指定されたトピック名にジャンプできるようにします。[X] ボタンを使用して、ユーザーは会話を終了できます。トピックが終了すると、ユーザーはグローバルトピックを再開します。会話が終了したら、ユーザーはチャットウィンドウの下部にある [新しい会話を開始するには、ここをクリックしてください] を選択してトピックを再開できます。
    オプションの resumeBehavior パラメーターは、次のように会話フローを再開する方法を指定します。
    • resumeBehavior=resume の場合、 仮想エージェント は呼び出し元トピックを再開します。
    • resumeBehavior=skip の場合、仮想エージェント は呼び出し元トピックをスキップします。

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

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

    現在の仮想エージェントの会話の転写を取得します。