---
sourceDocument: Yokohama 対話型インターフェース
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/yokohama/conversational-interfaces

 Release :

    - yokohama

ft:locale :

    - ja-JP

ft:publication_title :

    - Yokohama 対話型インターフェース

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# ストアリリース 3.0.x で利用可能な仮想エージェント API 機能

# ストアリリース 3.0.x で利用可能な仮想エージェント API 機能 {#ariaid-title1}

* リリースバージョン: Yokohama
* 
* 更新日 2025年01月30日
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：10分

仮想エージェント API バージョン 3.0.x では、仮想エージェントおよびエージェントチャットで利用可能な同じ機能の多くにアクセスできます。これには、プライベート URL からファイルをアップロードする機能や同期ハンドシェイクの機能拡張などが含まれます。

## 破棄された仮想エージェントの会話の終了 {#va-api-features-v3__section_y1m_khj_dsb}

エラーが原因で会話が不完全な場合、仮想エージェントはプライマリボットに制御を依頼することができます。takeControl フラグが true の場合、仮想エージェントは (セカンダリボットとして) 会話を自動的に終了します。プライマリボットが会話を開始する場合、`"hi"/START_CONVERSATION` のアクションメッセージを送信できます。  
次の状況では、プライマリボットに制御を依頼することができます。

* アイドルタイムアウト：インタラクションステータスが \[破棄してクローズ\] です。ステータスの理由は \[アクティビティなし\]です。
* 技術的な問題：インタラクションのステータスが \[破棄してクローズ\] です。ステータスの理由は \[ボットの問題 (Bot issues)\] です。
* 無効なユーザー入力：インタラクションステータスが \[破棄してクローズ\] です。ステータスの理由は \[無効なユーザー入力 (Invalid user input)\] です。
{#va-api-features-v3__ul_zts_y3j_dsb}

プライマリボットに制御を求めるには、ペイロードの本文にある takeControl フラグを true の値でプライマリボットに送信します。  
メッセージペイロードの例：

    {​ 
       "requestId": "xxxx-xxxx-xxxx-xxxx",
       "clientSessionId": "xxx-xxx-xxx-xxx",
       "message": {
           "text":"invalid3",
           "typed":true
           }
       "body":[{
           "uiType":"OutputText",
           "group":"DefaultText",
           "value":"Sorry, I didn't get that. Could you help me by answering this?"
           },
           {
           "uiType":"Boolean",
           "group":"DefaultPicker",
           "required":true,
           "nluTextEnabled": false,
           "label":"Choose a value",
           "options":[
              {"label":"Yes"},
              {"label":"No"}
              ]
           }],
        "takeControl":true,
        "score":0
    } 

## トピックの切り替えエラーとトラブルシューティングの改善 {#va-api-features-v3__section_b3w_cks_2rb}

トピックの切り替えは、次のいずれかの理由で失敗することがあります。

* 要求に、トピック名とトピック ID (キーワードトピックディスカバリー) またはトピックインテント名とトピックインテント ID (NLU トピックディスカバリー) の両方が含まれています。いずれか一方を指定します。
* 要求に無効なトピックかインテント名、または ID が含まれています。
* トピック/インテント名または ID は有効ですが、非アクティブであるかトピックでないため、仮想エージェントで実行できません。たとえば、名前または ID がトピックブロックまたはカスタムコントロール資産を参照している場合などです。
* 要求されたトピックが既に実行されています。
* 要求されたトピックは有効ですが、セキュリティ条件によりアクセスできません。たとえば、トピックの実行がチャネルで許可されていない場合や、その他のアクセス制御条件が適用されている場合などがあります。
{#va-api-features-v3__ul_ekg_rnt_2rb}  
トピックの切り替えに失敗した場合、仮想エージェント API は、同期的に使用しているか非同期的に使用しているかにかかわらず次のように応答します。

* トピックの切り替えに失敗すると、会話を続行できないことを示すメッセージが表示されて会話が終了します。会話はオープンステータスのままではなくなります。
* 前の要求は処理済みとしてマークされるため、タイムアウトを待たずに新しい要求を行うことができます。
* 失敗の理由は、システムログテーブル (自動テストフレームワーク (ATF)システムログエラー).
{#va-api-features-v3__ul_xzw_wqt_2rb}

## 同期ハンドシェイクの機能拡張 {#va-api-features-v3__synchronous_support_enhancements}

バージョン 3.0.x 以降、仮想エージェント API はライブエージェントへの転送を同期的に行うことができます。ユーザーまたはエージェントが会話を終了すると、仮想エージェントへの転送も同期的に行われます。一部のシステムメッセージと待機時間メッセージも同期的に送信されます。  
ライブエージェントへの同期転送を使用するには、次のガイドラインに注意してください。

* 仮想エージェントの応答エンドポイントを構成します。エージェントチャットのメッセージは、指定したエンドポイントに配信されます。
* インスタンスの通知は手動でオフにする必要があります。
* ライブエージェントへの同期転送を使用している場合、仮想エージェント API は、入力インジケーターが有効になっている場合は送信します。

      {
        "uiType": "ActionMsg",
        "actionType": "StartTypingIndicator",
      }

* 次の機能を使用するトピックは、同期モードではサポートされていません： [ファイルアップロード](https://servicenow-prod.fluidtopics.net/JIOzvnuMtkVwYtyoJhwixg "仮想エージェントデザイナーに用意されている一連の入力コントロール使用して、会話中のユーザーからの情報を求めてキャプチャします。")、 [アクション ユーティリティ](https://servicenow-prod.fluidtopics.net/UOej~UXFDFc3osi50PzPBw "仮想エージェント トピックのアクションユーティリティを使用して、ノードが作成する必要があるフローアクションプロパティを選択します。アクションユーティリティは 仮想エージェント を ServiceNow ワークフロースタジオ 製品と統合します。")、および[一時停止トピックブロック](https://servicenow-prod.fluidtopics.net/~4gSTq36qptUdFe0X4qoOg "仮想エージェントは、トピック作成者またはアドミニストレーターがボットの会話で特定のプラットフォーム関連の機能またはタスクを実行するために使用できる、ビルド済みのトピックブロックを提供します。たとえば、特定のトピックブロックを使用すると、エージェントの可用性を確認したり、AI 検索 結果を生成したりできます。")。
{#va-api-features-v3__ul_pmt_p2s_2rb}  
これらの機能を無効にして同期サポートを有効にするには、次の手順を実行します。

1. 移動先 すべてsys_cs_channel.list.
2. \[ボット間 (Bot to Bot)\] レコードを選択します。
3. 無効にするには、\[通知の有効化\] チェックボックスをオフにします。
4. 同期モードでライブエージェントへの転送を行わない場合は、\[入力インジケーターをサポート\] チェックボックスをオフにして無効にします。
5. \[同期\] チェックボックスをオンにします。  
   図 : 1. 同期サポートを有効にしたボット間チャネル
6. \[更新\] をクリックします。
{#va-api-features-v3__ol_icm_x3j_gqb}

## アクションメッセージのサポート {#va-api-features-v3__section_c4v_wr3_dsb}

ServiceNow® 仮想エージェントのセカンダリボットにメッセージを渡すだけでなく、プライマリボットまたはチャットクライアントはエージェントチャットを介してエージェントにメッセージを渡すことができます。要求の本文で渡された action パラメーターを使用して、コンテンツの処理方法を指定します。  
仮想エージェント API は、次のアクションメッセージタイプをサポートしています。{#va-api-features-v3__table_g3b_cyp_dsb__entry__2}

| actionType 値 | 説明 |
|-|-|
| ChatSubHeader | 次のいずれかが発生したことを示す送信メッセージ： * 動的翻訳が失敗しました。 * ライブエージェントのオートパイロットが開始され、完了しました。 {#va-api-features-v3__ul_kmy_xcg_hsb} |
| StartSpinner | メッセージが AI 検索 や汚い言葉フィルターなどの非同期プロセスのために処理待ち状態になっているときにスピナーを開始する送信メッセージ。 |
| EndSpinner | 以前に送信されたスピナーを停止する送信メッセージ。 |
| StartTypingIndicatorActionMsg | (エージェントがチャットを受け入れた後に) ユーザーまたはエージェントが入力を開始したことを示す送信メッセージ。 |
| EndTypingIndicatorActionMsg | ユーザーまたはエージェントが入力を停止したことを示す送信メッセージ。 |
| SubscribeToSupportQueue | 会話がサポートキューに設定されていることを示します。 |
| SubscribeToChatPresence | ライブエージェント会話が開始されたことを示す送信メッセージ。 |
| SwitchToLiveAgent | ライブエージェントが会話を受け入れたことを示す送信メッセージ。 |
| SwitchToVirtualAgent | ライブエージェントセッションが終了し、会話が仮想エージェントに戻されたことを示す送信メッセージ。 |
| SwitchConversation | 通知が送信されたことを示す送信メッセージ。これにより新しい会話が作成されるため、仮想エージェントは新しい会話に切り替わります。 |
| システム | 次のいずれかを示す送信メッセージ： * ライブエージェントが cat を入力しました。 * ライブエージェントまたはユーザーのいずれかがチャットをクローズしました。 * ライブエージェントとの会話がタイムアウトしました。 {#va-api-features-v3__ul_bdd_nlq_dsb} |
[表 : 1. サポートされているアクションメッセージタイプ]

{#va-api-features-v3__table_g3b_cyp_dsb}

## silentMessage フラグのサポート {#va-api-features-v3__section_t1b_lrq_dsb}

サイレントメッセージは、応答を必要としないメッセージです。仮想エージェント が silentMessage=true の要求を受信した場合、仮想エージェント がサイレントモードをオフにする要求 (silentMessage=false) を受信するまで、その後のすべてのボットメッセージは非表示になります。  
プライマリボットからのメッセージペイロードの例：

    { 
       "token": "BOT_TOKEN",
       "botToBot": true,
       "clientSessionId": "884502214730301027f83ee4070f589a",
       "clientVariables": {},
       "requestId": "48450221d23030107300b7756770bc9b",
       "silentMessage": "true",
       "timestamp": 1623916324820,
       "timezone": "GMT",
       "userId": "abel.tuter",
       "emailId": "abel.tuter@example.com" 
    }

注:  
silentMessage=true の場合、通知は配信されません。

## プライベート URL からの安全なファイルアップロード {#va-api-features-v3__section_xjy_j12_2rb}

仮想エージェント API は、プライベート URL からの最大 1 GB のサイズのファイルアップロードをサポートしています。プライマリボットは、ユーザー ID、オプションのプロバイダーアプリケーション ID、およびファイルの名前を渡す必要があります。次のガイドラインに従ってください。

* プロバイダーアプリケーション ID はオプションです。
* ユーザー ID とプロバイダーアプリケーション ID は、ペイロードのファイル名の前に送信する必要があります。
* エンドユーザーは、glide.attachment.role プロパティで指定されたロールを持っている必要があります。詳細については、「[ファイルを添付するために必要なロール](https://www.servicenow.com/docs/access?context=t_DisablingTheDragAndDropFeature&version=yokohama&pubname=yokohama-platform-administration&ft:locale=en-US)」を参照してください。
* 基本認証または OAuth 認証はサポートされていますが、メッセージ認証はサポートされていません。
{#va-api-features-v3__ul_dvc_vn2_2rb}  
プライマリボットからのメッセージペイロードの例：

    curl -X POST \
      https://instance.service-now.com/api/now/v1/cccif/media/upload \
      -H 'authorization: Basic YWRtaW46YWRtaW4=' \
      -H 'content-type: multipart/form-data; \
      -F user_id=xxxxxx \
      -F provider_application_id=optionalId \
      -F 'file=@SomeFile.png'

仮想エージェント API は、次の JSON の例を送信します：

    {
      "result": {
        "mediaUrl": "http://123.456.7.8:8080//api/now/v1/cs/media/string",
        "name":"imagefile.png",
        "state":"pending",
        "attachmentId":"abcdefghijklmno12345"
      }
    }

## 仮想エージェント API バージョン 3.14.3 でのエージェントチャットの機能拡張 {#va-api-features-v3__section_qft_pcv_c2c}

* プライマリボットがライブエージェントにチャットを転送すると、 仮想エージェント API エージェント名とアバターに加えて、エージェント ID がプライマリボットに送信されます。
* 仮想エージェント API は、進行中の会話中にプライマリボットからライブエージェントにチャット履歴を要求内の任意の場所に送信します。この動作は、allow_storing_history_in_ongoing-conversation システムプロパティによって制御されます。要求内の任意の場所にチャット履歴を送信するには、プロパティの値を true に設定します。
* インタラクションレコードには、チャット履歴のトランスクリプトと個々のメッセージのタイムスタンプが含まれています。
{#va-api-features-v3__ul_fd3_rcv_c2c}