サポートされている機能

オーストラリアの対話型インターフェース

Release

australia

ft:locale

ja-JP

ft:publication_title

オーストラリアの対話型インターフェース

ft:clusterId

convint

bundleId

convint

workflow

Platform

仮想エージェント APIでサポートされている機能

リリースバージョン: Australia

更新日 2026年03月12日

所要時間：28分

この仮想エージェント API を使用して、仮想エージェントおよびエージェントチャットで利用可能な同じ機能の多くをチャット環境に統合できます。機能のサポートは、 ServiceNow リリースと仮想エージェント APIのストアアプリのバージョン番号によって異なります。

仮想エージェント API の要求と応答テンプレートの詳細、および一般的なユースケースの例については、「仮想エージェントボット統合 API」を参照してください。

バージョン 4.3.0

仮想エージェント API でのプレミアムチャットのサポート

バージョン 4.1.1

仮想エージェント API での合成された応答のサポート

Now Assistエクスペリエンスを通じて合成された応答を有効にすると、仮想エージェント API は引用付きの応答をプライマリボットに送信します。引用は、個別の引用リンクとともに citations パラメーターに含まれます。

引用と引用リンクを含む合成された応答の JSON の例を次に示します。

{
  "clientSessionId": "va_api_conv_16875",
  "score": 1,
  "interactionId": "0dce3e37ffe1f610f71affffffffff8a",
  "requestId": "1765195564288",
  "streamActive": false,
  "streamState": "END",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "feedback": {
        "messageId": "dcde7a7739e1f610beed69f9e5960355",
        "feedbackEnabled": true
      },
      "maskType": "NONE",
      "citations": [
        {
          "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33",
          "sysId": "24d9243187032100deddb882a2e3ec33",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "What is Spam?",
          "index": 0,
          "source": "internal",
          "category": "kb",
          "citationLabel": "What is Spam?",
          "table": "kb_knowledge",
          "citationRef": "[1]"
        },
        {
          "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2",
          "sysId": "0b48fd75474321009db4b5b08b9a71c2",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "How to Deal with Spam",
          "index": 1,
          "source": "internal",
          "category": "kb",
          "citationLabel": "How to Deal with Spam",
          "table": "kb_knowledge",
          "citationRef": "[2]"
        },
        {
          "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d",
          "sysId": "3020c9b1474321009db4b5b08b9a712d",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "What are phishing scams and how can I avoid them?\n\t\t",
          "index": 2,
          "source": "internal",
          "category": "kb",
          "citationLabel": "What are phishing scams and how can I avoid them?\n\t\t",
          "table": "kb_knowledge",
          "citationRef": "[3]"
        }
      ],
      "streamId": "4fcef677ffe1f610f71affffffffffee",
      "uiType": "OutputText",
      "messageId": "dcde7a7739e1f610beed69f9e5960355",
      "relatedList": [],
      "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, quack health products, pornographic site ads, offers for bulk emailing services, chain letters, and pirated software. Most reputable marketers do not use spam for advertising. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes.\n- Use judgment when unsubscribing or responding to unfamiliar sources \u200b[1]\u200b\u200b[2]\u200b.\n\nPhishing scams, a dangerous form of spam, attempt to trick you into revealing personal information by pretending to be legitimate organizations. Always verify requests for sensitive information and avoid clicking suspicious links \u200b[3]\u200b.\n\n[1] [What is Spam?](http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)\n[3] [What are phishing scams and how can I avoid them?\n\t\t](http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d)",
      "group": "DefaultText"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}

詳細については、「仮想エージェント APIでの合成された応答の有効化」を参照してください。

仮想エージェント API でのエージェント型応答のサポート

仮想エージェント API は、 Now Assist エクスペリエンスを通じてエージェント型応答をサポートします。仮想エージェント API でエージェント型応答を有効にすると、出力メッセージはロード中または処理中としてユーザーに表示されます。
仮想エージェント API 新しい DynamicLoader パラメーターを使用してプライマリボットにメッセージを送信します。

エージェント型応答の JSON の例を次に示します。

{
  "clientSessionId": "va_api_conv_16875",
  "score": 1,
  "interactionId": "0dce3e37ffe1f610f71affffffffff8a",
  "requestId": "1765195564288",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "progressMessages": [
        {
          "message": "Searched for relevant documents and actions",
          "status": "COMPLETED"
        },
        {
          "message": "Generated the response",
          "status": "COMPLETED"
        }
      ],
      "actionType": "DynamicLoader",
      "defaultHeader": "View AI Steps",
      "uiType": "ActionMsg",
      "parentMessageId": "87cef677ffe1f610f71affffffffff4d",
      "header": "View AI Steps",
      "messageId": "87cef677ffe1f610f71affffffffff4d",
      "shouldUpdateParentMessage": true
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}

仮想エージェント API での応答ストリーミングのサポート

仮想エージェント API は、 Now Assist エクスペリエンスを介した応答ストリーミングをサポートしています。詳細については、「仮想エージェント API での Now Assistエクスペリエンスの有効化」を参照してください。
注:
プライマリボットは、ストリーミング応答をエンドユーザーに渡す必要があります。詳細については、「チャットストリーミング応答」を参照してください。

仮想エージェント API は、応答ストリーミングの次の状況をサポートしています。

開始

{
  "clientSessionId": "va_api_conv_16875",
  "requestId": "1762864530268",
  "streamActive": true,
  "streamState": "START",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "streamId": "cb928c9f53097e10f71a6dc230e5e639",
      "uiType": "StreamStart",
      "streamSequence": 1,
      "value": "Looking into your request"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}

進行中

{
  "clientSessionId": "va_api_conv_16875",
  "requestId": "1762864530268",
  "streamActive": true,
  "streamState": "INPROGRESS",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "streamId": "cb928c9f53097e10f71a6dc230e5e639",
      "uiType": "StreamChunk",
      "streamSequence": 2,
      "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}

終了

{
  "clientSessionId": "va_api_conv_16875",
  "score": 1,
  "interactionId": "d592c89f53097e10f71a6dc230e5e68c",
  "requestId": "1762864530268",
  "streamActive": false,
  "streamState": "END",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "feedback": {
        "messageId": "6f92cc9f34097e108001c582b67b2a1f",
        "feedbackEnabled": true
      },
      "maskType": "NONE",
      "citations": [
        {
          "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33",
          "sysId": "24d9243187032100deddb882a2e3ec33",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "What is Spam?",
          "index": 0,
          "source": "internal",
          "category": "kb",
          "citationLabel": "What is Spam?",
          "table": "kb_knowledge",
          "citationRef": "[1]"
        },
        {
          "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2",
          "sysId": "0b48fd75474321009db4b5b08b9a71c2",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "How to Deal with Spam",
          "index": 1,
          "source": "internal",
          "category": "kb",
          "citationLabel": "How to Deal with Spam",
          "table": "kb_knowledge",
          "citationRef": "[2]"
        }
      ],
      "streamId": "cb928c9f53097e10f71a6dc230e5e639",
      "uiType": "OutputText",
      "messageId": "6f92cc9f34097e108001c582b67b2a1f",
      "relatedList": [],
      "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, \"get rich quick\" offers, quack health products, ads for pornographic sites, offers for bulk emailing services, chain letters, and pirated software. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online or with companies.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes \u200b[1]\u200b\u200b[2]\u200b.\n\n[1] [What is Spam?](http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)",
      "group": "DefaultText"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}

次の構成を使用して、仮想エージェント API でのストリーミングを有効にします。
1. 仮想エージェントのNow Assistで [応答ストリーミングを許可] が選択されていることを確認します。詳細については、「追加のチャット機能を有効にする」を参照してください。
2. [ すべて ] に移動し、ナビゲーションフィルターに 「sys_now_assist_channel_config.list 」と入力します。
3. Now Assistチャネル構成 [now_assist_channel_config] テーブルで、ボット間デバイスに対して [ストリーミング準備完了] フィールドの値を true に設定します。
  図 : 1. Now Assist チャネル構成テーブル

新しい送信認証のサポート

仮想エージェント API はワークフロースタジオ以前の REST メッセージの代わりに REST ステップを使用するように設定 ServiceNow AI Platform ました。
詳細については、「仮想エージェント API の出力応答 REST エンドポイントと送信認証の構成 (v4.1 以降)」を参照してください。

バージョン 4.0.0

仮想エージェント API ライブエージェントとプライマリボットの間のメッセージテキストとメッセージの配信ステータスを更新します。
仮想エージェント API は、プライマリボットに応答してインタラクション ID とメッセージ ID (ライブエージェントとの会話の場合はエージェント ID) を送信します。

インタラクションレコードには、サポートされているサードパーティ製チャットアプリケーション (またはプライマリボット) からエンドユーザーとの会話ごとに送信される clientSessionId パラメーターが保存されます。詳細については、「clientSessionId を保存するインタラクションレコードを構成します仮想エージェント API」を参照してください。
プライマリボットとエンドユーザーとの会話のチャット履歴には、個々のメッセージのタイムスタンプが含まれます。ライブエージェントは、このチャット履歴を個々のメッセージまたは単一のブロックで表示できるようになりました。詳細については、「仮想エージェント APIでチャット履歴をサポートするように構成する」を参照してください。チャット履歴に表示されるプライマリボットのロゴを設定することで、エージェントチャットインターフェイスをカスタマイズできます。詳細については、「仮想エージェント APIでのプライマリボットのロゴの設定」を参照してください。

バージョン 3.0.x

バージョン 3.14.3 でのエージェントチャットの機能拡張

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

Now Assist エクスペリエンスのサポート

Now Assist仮想エージェント APIエクスペリエンスは、複数のプロバイダーチャネルにわたる生成 AI スキルを提供します。
詳細については、「仮想エージェント API での Now Assistエクスペリエンスの有効化」を参照してください。

複数のプロバイダーアプリケーションの構成のサポート

仮想エージェント API を使用すると、複数のプロバイダーアプリケーションを構成して、仮想エージェント API を使用する複数のプライマリボットがあり、それらを区別する必要があるユースケースをサポートすることができます。
詳細については、「複数のプロバイダーアプリケーションの構成」を参照してください。

仮想エージェント API の要求と応答の変換のサポート

仮想エージェント API は、要求ペイロードと応答ペイロードの相互変換仮想エージェント APIをサポートしています。これは、プライマリボットにすべてのセカンダリボットで共通の応答テンプレートがある場合に役立ちます。
詳細については、「要求と応答仮想エージェント API 変換」を参照してください。

プライベート URL からの安全なファイルアップロード

仮想エージェント API は、プライベート URL からの最大 1 GB のサイズのファイルアップロードをサポートしています。プライマリボットは、ユーザー ID、オプションのプロバイダーアプリケーション ID、およびファイルの名前を渡す必要があります。次のガイドラインに従ってください。
- プロバイダーアプリケーション ID はオプションです。
- ユーザー ID とプロバイダーアプリケーション ID は、ペイロードのファイル名の前に送信する必要があります。
- エンドユーザーは、 glide.attachment.role プロパティで指定されたロールを持っている必要があります。詳細については、「ファイルを添付するためにロールが必要」を参照してください。
- ベーシック認証または OAuth 認証はサポートされていますが、メッセージ認証はサポートされていません。

プライマリボットからのメッセージペイロードの例:

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"
  }
}

silentMessage フラグのサポート

サイレントメッセージは、応答を必要としないメッセージです。仮想エージェントが 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場合、通知は配信されません。

アクションメッセージのサポート

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

仮想エージェント API は、次のアクションメッセージタイプをサポートしています。

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

同期ハンドシェイクの機能拡張

仮想エージェント API はライブエージェントに同期的に転送できます。ユーザーまたはエージェントが会話を終了すると、仮想エージェントへの転送も同期的に行われます。一部のシステムメッセージと待機時間メッセージも同期的に送信されます。
ライブエージェントへの同期転送を使用するには、次のガイドラインに注意してください。
- 仮想エージェント応答エンドポイントを構成します。エージェントチャットメッセージは、指定したエンドポイントに配信されます。
- インスタンスの通知は手動でオフにする必要があります。
- ライブエージェントへの同期転送を使用している場合、入力インジケーターが有効になっている場合は、仮想エージェント API が送信します。
```
{
  "uiType": "ActionMsg",
  "actionType": "StartTypingIndicator",
}
```
- 次の機能を使用するトピックは、同期モードではサポートされていません: ファイルのアップロード、アクションユーティリティ、および一時停止トピックブロック。
これらの機能を無効にして同期サポートを有効にするには、「仮想エージェント APIでの同期サポートの有効化」を参照してください。

トピックの切り替えエラーとトラブルシューティングの改善

トピックの切り替えは、次のいずれかの理由で失敗することがあります。
- 要求には、トピック名とトピック ID (キーワードトピックディスカバリー) またはトピックインテント名とトピックインテント ID (NLU トピックディスカバリー) の両方が含まれます。いずれか一方を指定します。
- 要求に無効なトピックまたはインテント名または ID が含まれています。
- トピック/インテント名または ID は有効ですが、非アクティブであるかトピック仮想エージェントないため実行できません。たとえば、名前または ID がトピックブロックまたはカスタムコントロール資産を参照している場合などです。
- 要求されたトピックは既に実行中です。
- 要求されたトピックは有効ですが、セキュリティ条件によりアクセスできません。たとえば、トピックがチャネルでの実行が許可されていない場合や、他のアクセス制御条件が適用されている場合などがあります。
トピックの切り替えに失敗した場合、仮想エージェント API は、同期的に使用しているか非同期的に使用しているかにかかわらず、次のように応答します。
- トピックの切り替えに失敗すると、会話を続行できないことを示すメッセージが表示されて会話が終了します。会話はオープンステータスのままではなくなります。
- 前の要求は処理済みとしてマークされるため、タイムアウトを待たずに新しい要求を行うことができます。
- 失敗の理由は、システムログテーブル (自動テストフレームワーク (ATF) > システムログ > エラー) を開きます。

仮想エージェント API の応答時間の改善

仮想エージェント API 応答には、「Take Control」や「NLU Score」などのパラメーターが含まれます。これらのパラメーターは、応答の準備中に処理されます。
バージョン 3.9.0 以降では、仮想エージェント API 応答から [Take Control] パラメーターや [NLU Score] パラメーターを除外して、応答時間を改善できます。
仮想エージェント API応答から [Take Control] パラメーターと [NLU スコア] パラメーターを除外するには、次の手順を実行します。
1. 移動先すべて > sys_cs_custom_adapter_property.list.
2. enable_take_controlプロパティとsend_nlu_scoreプロパティを検索します。
3. 応答 enable_take_control 処理中に [Take Control] 設定を除外するにはプロパティの値を false に、 send_nlu_score プロパティの値を false に設定します。これらのプロパティはデフォルトで [true] に設定されています。

破棄された仮想エージェント会話の終了

エラーのために会話が不完全な場合、仮想エージェントはプライマリボットに制御を依頼できます。takeControlフラグがtrueの場合、仮想エージェント (セカンダリボットとして) 会話は自動的に終了します。プライマリボットが会話を開始する場合は、「 hi」/START_CONVERSATIONアクションメッセージを送信できます。
次の状況では、プライマリボットに制御を依頼できます。
- アイドルタイムアウト:インタラクションステータスは [破棄してクローズ] です。ステータスの理由はアクティビティ なしです。
- 技術的な問題:インタラクションのステータスが [破棄してクローズ] です。ステータスの理由は ボットの問題です。
- 無効なユーザー入力:インタラクションステータスが [破棄してクローズ] です。ステータスの理由は 無効なユーザー入力です。
プライマリボットに制御を要求するには、ペイロードの本文にある 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
}