--- sourceDocument: オーストラリア API リファレンス sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/api-reference Release : - australia ft:locale : - ja-JP ft:publication_title : - オーストラリア API リファレンス ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # 仮想エージェントボット統合 API # 仮想エージェントボット統合 API {#ariaid-title1} * リリースバージョン: Australia * * 更新日 2026年03月12日 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：75分 仮想エージェントボット統合 API は、ユーザーがチャットインターフェイスまたはボットエコシステムをServiceNow 仮想エージェントやライブエージェントと統合できるようにするエンドポイントを提供します。 この API は、 仮想エージェント で提供される会話型カスタムチャット統合フレームワークに基づいて構築され、 `sn_va_as_service` 名前空間で動作します。 仮想エージェント ボット統合 API のインストールと構成の詳細については、「[Using Virtual Agent with a live agent](https://www.servicenow.com/docs/access?context=using-va-agent-chat&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)」を参照してください。 ## VA ボット統合:POST /sn_va_as_service/bot/integration {#ariaid-title2} 指定されたメッセージ、添付ファイル、または URL を指定されたセカンダリ ServiceNow 仮想エージェント (VA) ボットに送信します。 顧客のサイトには、1 つ以上のセカンダリ ServiceNow ボットを含めることができます。プライマリボットまたはチャットクライアントは、 ServiceNow VA セカンダリボットにメッセージを渡すことに加えて、このエンドポイントを使用してチャットを介してエージェントにメッセージを渡 ライブエージェント できます。要求本文で渡された action パラメーターを使用して、指定されたコンテンツの処理方法を指定します。 注: このエンドポイントは、構成方法に応じて同期または非同期のいずれかになります。非同期の場合、エンドポイントが要求を受信すると、エンドポイントは要求を検証し、成功または失敗のコールステータスと適切な HTTP ステータスコードで応答します。VA は要求を処理し、構成された応答エンドポイントに 2 番目の応答を送信します。たとえば、ボット間の統合の場合、2 番目の応答はプライマリボットの URL です。これらの応答は両方とも以下で定義されます。この構成された応答エンドポイントの詳細については、「 仮想エージェント API の出力応答 REST エンドポイントと送信認証の構成」を参照してください。 注: このエンドポイントのコード例の応答は、VA から構成された応答エンドポイントに送信される内容を示しています。単純な成功または失敗の応答であるこのエンドポイントに対する実際の応答は表示されません。 ### URL 形式 デフォルト URL: /api/sn_va_as_service/bot/integration ### サポートされている要求パラメーター {#bot-POST-integration__entry__2} | 名前 | 説明 | |-|-| | なし | | [表 : 1. パスパラメーター] {#bot-POST-integration__entry__6} | 名前 | 説明 | |-|-| | なし | | [表 : 2. クエリパラメーター] {#bot-POST-integration__vabot-req-parms__entry__2} | 名前 | 説明 | |-|-| | action | VA が実行する必要があるアクション。 有効な値： * [AGENT](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-agent):会話を VA から ライブエージェント に切り替えます。 * [CREATE_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-createconvo):チャットインタラクションを作成します。 * [END_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-faultconvo):チャットの会話を終了します。このアクションを使用する場合は、message.text パラメーターを空にする必要があります。 * [FAULT_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-faultconvo):会話に欠陥があります。FAULT_CONVERSATION アクションを設定するときは、 cause パラメーターの説明を入力します。 * [SEND_HISTORY](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-sendhist):チャット履歴のみを更新します。チャット履歴は、 history パラメーターで指定した標準のメッセージ処理を使用して送信することもできます。 * SET_USER_TIMEZONE：ユーザーのタイムゾーンを timezone パラメーターで指定されたタイムゾーンに設定します。同じパラメーターを使用してリセットするまで、このタイムゾーンは有効です。 * [START_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-startconvo):チャット会話を開始します。 * [START_CREATED_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-startcreatedconvo): CREATE_CONVERSATIONを使用して開始されたチャット会話を開始します。 * [SWITCH](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-switch): intent.id パラメーターまたは topic.name パラメーターで指定された内容に一致するトピックに会話を切り替えます。 注: トピックの切り替えには、インテントディスカバリーがプライマリボットで発生した場合にのみ、 `SWITCH` アクションを使用します。ServiceNow® VA で Intent Discovery が行われる場合は、message.text パラメーターを使用します。 * TYPING/VIEWING：ライブエージェントに入力インジケーターを表示します。最初に `TYPING` を送信し、ユーザーが入力を終えたら `VIEWING` を送信します。 * [UPDATE_MESSAGES](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-ex-updatemsg):このアクションはライブエージェントの会話中に使用され、エージェントチャットパネルに反映されるライブエージェントから受信したメッセージについて、サードパーティチャット統合用の 2 つのメッセージ更新機能を提供します。 * サードパーティからのメッセージを送信した後の最新のメッセージ配信ステータス。 * エージェントチャットパネルのテキストが更新されました。 {#bot-POST-integration__ul_wty_wpw_4gc} サードパーティチャット統合は、エンドユーザーに送信する前にメッセージのテキスト部分を更新できます。このアクションを呼び出してエージェントチャットパネルのテキストを更新し、更新されたテキストを「更新済み」タグ付きでエージェントに表示できるようにします。 このアクションは、 message.status パラメーターと message.id パラメーターとともに使用します。 このオプションは、プロバイダーアプリケーションに関連付けられた名前third_party_chatカスタムアダプタプロパティが true に設定されている場合にのみ有効です。これは、チャネルの同期/非同期の性質に関係なく、同期アクションです。 * null またはパラメーターが渡されない：メッセージを ServiceNow VA に送信します。 {#bot-POST-integration__ul_dtc_3fg_4mb}サードパーティチャット統合は、エンドユーザーに送信する前に、ライブエージェントからトリガーされたテキストメッセージを更新できます。このアクションを呼び出してエージェントチャットパネルのテキストを更新し、更新されたテキストを「更新済み」タグ付きでエージェントに表示できるようにします。 データタイプ：文字列 デフォルト：Null | | ボットツーボット | 会話がプライマリボットとセカンダリボット間など、ボット間であるかどうかを示すフラグ。 可能な値： * true:ボット間の会話。 * false:スタンドアロン ServiceNow ボットの会話。 {#bot-POST-integration__ul_prw_jkj_qmb} データタイプ：ブーリアン デフォルト：true | | 原因 | チャット会話の障害の原因 ( EXTERNAL_FAILUREなど)。このプロパティは、 action プロパティが FAULT_CONVERSATION に設定されている場合にのみ使用されます。 データタイプ：文字列 | | clientSessionId | エンドユーザーが ServiceNow ボット またはサポートされているサードパーティのチャットアプリケーションとの通信に使用しているアプリケーション/サービスの一意のクライアントセッション識別子。 * この ID は、特定のユーザーの会話に関する要求/応答のセットを識別するのに役立ちます。 * このパラメーターの形式は、実装者が決定します。 * この値は、\[カスタムアダプタプロパティ\] フォームの \[third_party_chat\] フィールドの値が true の場合にのみ更新されます。 {#bot-POST-integration__ul_d12_ywt_fgc} テーブル:インタラクション \[interaction\] データタイプ：文字列 デフォルト：Null | | clientVariables | 応答で返送されるパススルー JSON 形式の名前と値のペア。これらの値はエンドポイントでは処理されませんが、特定の顧客情報を会話に添付しておくために使用できます。 データタイプ: オブジェクト デフォルト：Null | | contextVariables | ユーザーに関する追加情報を提供する JSON 形式の名前と値のペア。会話エクスペリエンスをカスタマイズするには、この情報を入力します。コンテキスト変数の詳細については、「 [チャットコンテキスト変数の定義と公開](https://www.servicenow.com/docs/access?context=ac-configure-context-variables&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)」を参照してください。 例： "contextVariables": { "requester_session_language": "es", "deviceTimeZone": "America/Los_Angeles" "live_agent_only": "true", "liveagent_deviceType": "test_device_type" "topic": "7c3c819073a3101066c7e9344ef6a7e4" } データタイプ: オブジェクト デフォルト：Null | | emailId | アカウントのリンクを有効にする場合に必要です。有効にしない場合は、すべてのユーザーがゲストユーザーと見なされます。チャットクライアントのエンドユーザー (ボットがやり取りしているユーザー) のメールアドレス。アカウントのリンクの詳細については、「 [ServiceNow ユーザーアカウントを仮想エージェント会話のメッセージングアプリケーションにリンクする」](https://www.servicenow.com/docs/access?context=link-accounts-with-virtual-agent&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)を参照してください。 データタイプ：文字列 | | 履歴 | ユーザーによる最初の要求から始まる、プライマリボットとユーザーの会話の履歴。 データタイプ: オブジェクト "history": { "displayName": "String", "isBotMessage": Boolean, "timestamp": "String", "type": "String", "value": "String" } | | history.displayName | メッセージの送信先のユーザーの名前。プライマリボットの場合は、 ボットを渡します。 データタイプ：文字列 | | history.isBotMessage | メッセージがプライマリボットによって送信されたかどうかを示すフラグ。 有効な値： * true:メッセージはプライマリボットによって送信されました。 * false:メッセージはユーザーによって送信されました。 {#bot-POST-integration__ul_mzy_pgc_lqb} データタイプ：ブーリアン | | history.timestamp | メッセージが送信された時刻を示すタイムスタンプ (ミリ秒単位)。 有効な値:13 桁の Unix タイムスタンプ データタイプ：文字列 | | history.type | 送信されるメッセージのタイプ。 有効な値:text データタイプ：文字列 | | history.value | 情報の内容。たとえば、メッセージテキストなどです。 データタイプ：文字列 | | インテント | 会話の意図を説明します。actionパラメーターが `SWITCH` に設定されている場合は、この情報を指定します。 データタイプ: オブジェクト "intent": { "id": "String" } | | intent.id | NLU 会話の切り替え先のシステムトピックのインテント ID。intent.idは、チャットセッションで渡された言語に基づいて解決されます。会話の開始時に言語が渡されない場合は、ユーザーのセッション/プロファイルから言語が取得されます。 データタイプ：文字列 テーブル:CS トピック言語 \[sys_cs_topic_language\] | | メッセージ | 必須です。ServiceNowボットに送信するメッセージの詳細。 データタイプ: オブジェクト "message": { "attachment": [Array of Objects], "clientMessageId": "String", "status": "String", "text": "String", "typed": Boolean } | | message.attachment | 添付ファイルを送信する場合は必須です。送信する各添付ファイルの詳細。 添付ファイルは URL としてのみ渡すことができます。すべての添付ファイルに対してウイルススキャンがトリガーされます。添付ファイルのサイズに制限はありませんが、ファイルが大きい場合は転送にかなりの時間がかかることがあります。 データタイプ：オブジェクトのアレイ "attachment": [ { "clientAttachmentId": "String", "contentType": "String", "fileName": "String", "headers":{Object}, "id": "String", "url": "String" } ] | | message.attachment.clientAttachmentId | ServiceNowボットに送信する添付ファイルの一意の識別子。この識別子の形式は、実装者によって決定されます。 データタイプ：文字列 デフォルト：Null | | message.attachment.contentType | 添付ファイルが指定されている場合は必須です。添付ファイルの標準 MIME タイプ。 有効な値 (値の大文字と小文字を区別しない)： * application/pdf * アプリケーション/msword * image/png * image/jpeg * text/plain * ビデオ/MPEG {#bot-POST-integration__ul_ktc_xnj_4mb} データタイプ：文字列 | | message.attachment.fileName | 添付ファイルが指定されている場合は必須です。添付ファイルのファイル名。 データタイプ：文字列 | | message.attachment.headers | 添付ファイルがプライベートで保護されている場合に必要な追加情報。 データタイプ: オブジェクト "headers":{ "Authorization":"String" } | | message.attachment.headers.Authorization | ユーザー名やパスワードなど、添付ファイルにアクセスするための認証を取得するために必要な情報。 データタイプ：文字列 | | message.attachment.url | 添付ファイルが指定されている場合は必須です。添付ファイルが配置されている URL。VA はこの URL から添付ファイルを取得し、ウイルススキャンを実行してから、ファイルを処理します。添付ファイルがパブリックファイルでない場合は、添付ファイルにアクセスできるように、認証情報を含む message.attachment.header オブジェクトを渡す必要があります。また、 sys_cs_provider に提出された信頼できるドメインに URL ドメインが存在することも確認する必要があります。 データタイプ：文字列 | | message.clientMessageId | メッセージの一意の英数字識別子。この識別子の形式は、実装者によって決定されます。 データタイプ：文字列 デフォルト：Null | | message.id | UPDATE_MESSAGES アクションでのみ使用されます。更新するチャットメッセージの一意の ID。 データタイプ：文字列 | | message.status | メッセージステータス。 有効な値 (値の大文字と小文字を区別しない)： * external_error:サードパーティのチャット統合からエンドユーザーへのメッセージ配信が失敗した場合に使用されます。エージェントチャットパネルは「失敗」タグとして反映されます。 * sent_to_user - 最初は、ライブエージェントからサードパーティのチャット統合に配信されたメッセージに対して単一のチェックマークが表示されます。このステータスは、メッセージがサードパーティのチャット統合からエンドユーザーに正常に配信された場合に使用する必要があります。成功すると、エージェントチャットパネルに二重チェックマークが表示されます。 {#bot-POST-integration__ul_q3g_dnt_4gc} データタイプ：文字列 | | message.text | attachmentパラメーターが指定されていない場合は必須です。メッセージテキスト。 * メッセージの言語は contextVariables パラメーターで渡す必要があります。 * action プロパティの値が END_CONVERSATION の場合は空である必要があります。 * アクションプロパティの値が UPDATE_MESSAGES の場合、エージェントチャットパネルに反映されるように更新されたテキストである必要があります。 {#bot-POST-integration__ul_qbf_bgt_fgc} データタイプ：文字列 最大長:無制限 | | message.typed | 必須です。メッセージが入力されたか、またはオプションの選択 (選択済み) であったかどうかを示すフラグ。 有効な値： * true:メッセージはユーザーによって入力されました。 * false:メッセージはオプションの選択でした。 データタイプ：ブーリアン | | requestId | 必須です。この要求の一意の英数字識別子。この識別子の形式は、実装者によって決定されます。 データタイプ：文字列 | | サイレントメッセージ | サイレントメッセージかどうかを示すフラグ。サイレントメッセージとは、応答を必要としないメッセージです。 有効な値： * true:サイレントメッセージ。応答メッセージは想定されていません。 * false:通常のメッセージ、応答メッセージが必要です。 注: `silentMessage = true` の要求が送信された場合、後続のすべてのボットメッセージは、`silentMessage = false` を渡してサイレントモードをオフにする要求が送信されるまで抑制されたままになります。 データタイプ：ブーリアン デフォルト値：false | | timestamp | チャットクライアントのエンドユーザーからメッセージが送信されたときの Unix エポック時間。 データタイプ：数値 単位：ミリ秒 デフォルト:現在時刻 | | タイムゾーン | チャットクライアントのエンドユーザーの GMT タイムゾーン。 例： "timezone":"Asia/Kolkata" 使用可能なタイムゾーン値のリストについては、「 」を参照してください。 データタイプ：文字列 デフォルト: ServiceNow インスタンスの GMT タイムゾーン。 | | トピック | ユーザーがトピック名を指定して特定のトピックに切り替える場合は必須です。切り替え先のトピックの名前と値のペア。トピック名またはトピック sys_id のいずれかを指定できます。 注: オブジェクトに指定できるトピック名または ID は 1 つだけです。 データタイプ: オブジェクト "topic": { "name": "String", "id": "String" } 例： {​ "requestId": "xxxx-xxxx-xxxx-xxxx",​ "clientSessionId": "xxx-xxx-xxx-xxx",​ "action":"SWITCH",​ "topic":{​     "name": "Topic Name"​   },​   "userId": "beth"​ }​ | | topic.name | 切り替え先のトピックの名前。 データタイプ：文字列 テーブル:仮想エージェントトピック \[sys_cs_topic\] テーブルの名前フィールドにあります。 | | topic.id | 切り替え先のトピックのSys_id。 データタイプ：文字列 テーブル:仮想エージェントトピック \[sys_cs_topic\] | | userId | 必須です。一意のユーザー識別子。これは、ボットとやり取りしているエンドユーザーの識別子です。 データタイプ：文字列 | [表 : 3. 要求本文のパラメーター] {#bot-POST-integration__vabot-req-parms} ### ヘッダー 次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 [サポートされている REST API ヘッダー」](https://servicenow-prod.fluidtopics.net/lLW_uT5I5_l1aD8yR4Jt9A "REST (REpresentational State Transfer) は、Web 上のコンピューター システム間の標準を提供するシンプルなステートレス アーキテクチャであり、コンピューター システム間の通信を容易にします。")を参照してください。 {#bot-POST-integration__entry__84}{#bot-POST-integration__accept-JSON-only-entry-RESTAPI}{#bot-POST-integration__content_type-JSON-only-entry-RESTAPI} | ヘッダー | 説明 | |-|-| | 承認 | 応答本文のデータフォーマット。application/json のみをサポートします。 | | Content-Type | 要求本文のデータ形式。application/json のみをサポートします。 | | トークン | トークンベースの認証を使用する場合は必須です。基本認証または OAuth 認証のオプション。このエンドポイントにトークン認証が設定されている場合に使用する認証トークン。 データタイプ：文字列 | [表 : 4. 要求ヘッダー] {#bot-POST-integration__entry__92} | ヘッダー | 説明 | |-|-| | なし | | [表 : 5. 応答ヘッダー] ### ステータスコード この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 [REST API HTTP 応答コード](https://servicenow-prod.fluidtopics.net/lLW_uT5I5_l1aD8yR4Jt9A "REST (REpresentational State Transfer) は、Web 上のコンピューター システム間の標準を提供するシンプルなステートレス アーキテクチャであり、コンピューター システム間の通信を容易にします。")」を参照してください。 {#bot-POST-integration__entry__96}{#bot-POST-integration__entry-400-status-code}{#bot-POST-integration__entry-401-status-code}{#bot-POST-integration__entry-405-status-code}{#bot-POST-integration__entry-500-status-code} | ステータスコード | 説明 | |-|-| | 200 | 成功。要求が正常に処理されました。 ステータスコード 200 を受信しても応答がない場合は、次の点を確認してください。 * 要求が静的、JWT、またはハッシュベースのトークン検証で失敗しているかどうか (通常は 仮想エージェントのワーカースレッドで発生します)。 * 要求本文の形式が正しいかどうか。間違っていると、変換は正しく行われません。 * 要求本体に一部の必須パラメーターが欠落しているかどうか。ServiceNow インスタンスのシステムログで例外とエラーを追跡できます。 * 応答を受信するために REST メッセージで定義されたサイトが運用可能かどうか。ログで検出できます。 * 応答を投稿する場所を定義する REST メッセージが正しく設定されていることを確認します。 | | 400 | 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。 | | 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 | | 405 | メソッドが無効です。機能が無効になっています。 | | 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 | [表 : 6. ステータスコード] ### 応答本文のパラメーター エンドポイント呼び出しのステータス。これは、最初のコール要求が受信されたときに応答として送信されます。要求はまだ処理されていません。 {#bot-POST-integration__entry__108} | 名前 | 説明 | |-|-| | エラー | 検出されたエラーの説明。エラーが発生した場合にのみ返されます。 データタイプ: オブジェクト "error": { "detail": "String", "message": "String" } | | error.detail | 発生したエラーの詳細。 データタイプ：文字列 | | error.message | エラーメッセージがスローされました。 データタイプ：文字列 | | status | エンドポイント呼び出しのステータス。 有効な値： * 失敗 * 成功 {#bot-POST-integration__ul_mdj_f2f_1nb} データタイプ：文字列 | [ ] ### VA 応答本文パラメーター {#bot-POST-integration__section_vb2_yny_jlb} VA から構成された応答エンドポイントに送信される応答本文。 {#bot-POST-integration__table_bql_jkx_zmb__entry__2} | 名前 | 説明 | |-|-| | エージェントチャット | 会話が ServiceNow ライブエージェントに接続されているかどうかを示すフラグ。 可能な値： * true:チャットメッセージはライブエージェントから送信されています。 * false:チャットメッセージはボットから送信されており、このパラメーターは応答で返されません。 {#bot-POST-integration__ul_cql_jkx_zmb} データタイプ：ブーリアン | | 本文 | 応答メッセージ本文の要素を説明するオブジェクトのリスト。 データタイプ：オブジェクトのアレイ "body": [ { "actionType": "String", "agentInfo": {Object}, "data": "String", "group": "String", "header": "String", "height": Number, "itemType": "String", "label": "String", "maskType": "String", "maxCount": Number, "maxSize": Number, "message": "String", "messageId": "String", "multiSelect": Boolean, "nluTextEnabled": Boolean, "options": {Object}, "promptMsg": "String", "required": Boolean, "style": "String", "templateName": "String", "type": "String", "uiType": "String", "value": "String/{Object}", "width": Number } ] | | body.actionType | セカンダリボットからプライマリボットにディスパッチされるアクションメッセージのタイプ。たとえば、入力インジケーターやエージェントの待機時間などです。 可能な値： * EndTypingIndicator * スタートスピナー * StartTypingIndicator {#bot-POST-integration__ul_dgw_fhy_lqb} 例： 入力インジケーターが有効になっているときに、 `StartTypeIndicator` をプライマリボットに送信します。 "body": {​ "uiType":"ActionMsg",​   "actionType":"StartTypingIndicator"​ }  ライブエージェントへの転送時に `StartSpinner` を送信して、エンドユーザーに待機時間を表示します。 "body": { "uiType":"ActionMsg", "actionType":"StartSpinner", "spinnerType":"wait_time", "message":"Routing you to a live agent...", "waitTime":"8 Seconds" } データタイプ：文字列 | | body.agentInfo | エージェントチャットセットアップで有効になっている場合、関連付けられたエージェントの名前とアバター。 データタイプ: オブジェクト "agentInfo":{ "agentAvatar":"String", "agentId":"String", "agentName": "String", "sentFromAgent": Boolean } 例： "agentInfo":{ "sentFromAgent": true, "agentName":"Beth Anglin", "agentAvatar":"https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" } | | body.agentInfo.agentAvatar | エージェントに関連付けられたアバターファイルの URL。 例:「https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small」 データタイプ：文字列 | | body.agentInfo.agentId | ライブエージェントのsys_id。 テーブル:ライブプロファイル \[live_profile\] データタイプ：文字列 | | body.agentInfo.agentName | エージェントの表示名。 データタイプ：文字列 | | body.agentInfo.sentFromAgent | メッセージがライブエージェントによって送信されたかどうかを示すフラグ。 可能な値： * true:ライブエージェントによって送信されます。 * false:仮想エージェントによって送信されます。 {#bot-POST-integration__ul_arr_gky_lqb} データタイプ：ブーリアン | | body.data | カード内のデータを定義する JSON 文字列。 データタイプ：文字列 | | body.group | 本文要素が属するリッチコントロールグループ。送信変換スクリプトを記述することで、これらのデフォルトコントロールをさらに変換できます。これらのスクリプトの詳細については、「 [仮想エージェントアクションスクリプト」](https://www.servicenow.com/docs/access?context=va-action-scripts&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)を参照してください。 可能な値： * デフォルト出力カード * デフォルト日付 * DefaultGroupedPartsOutputControl * デフォルト HTML * デフォルト出力イメージ * デフォルト出力リンク * デフォルトテキスト * デフォルトピッカー データタイプ：文字列 | | body.header | リンクヘッダー。 データタイプ：文字列 | | body.height | HTML 要素の高さです。 データタイプ：数値 単位：ピクセル | | body.itemType | 本文要素のタイプ。 可能な値:(大文字と小文字を区別) * デフォルトテキスト * ファイル * イメージ * 入力テキスト * 出力テキスト {#bot-POST-integration__ul_fql_jkx_zmb} * デフォルトピッカー * 画像:アイテムがカルーセルに表示されます。 * リスト:アイテムはドロップダウンスタイルのリストに表示されます。 {#bot-POST-integration__ul_gql_jkx_zmb} {#bot-POST-integration__ul_eql_jkx_zmb} データタイプ：文字列 | | body.label | 関連付けられた要素に表示するラベル。 データタイプ：文字列 | | body.maskType | 関連データの機密性。 可能な値： * なし:関連データは一般的な性質のものであり、セキュリティで保護する必要はありません。 * セキュア:関連データは機密性のものであり、安全に処理する必要があります。 {#bot-POST-integration__ul_hbb_dbz_n4b} データタイプ：文字列 | | body.maxCount | uiTypeが `FileUpload` の場合にのみ返されます。一度にアップロードできる添付ファイルの最大数。 データタイプ:数値 (整数) | | body.maxSize | uiTypeが `FileUpload` の場合にのみ返されます。アップロードできる添付ファイルの最大サイズ。 データタイプ:数値 (整数) 単位:メガバイト | | body.message | actionTypeが `StartSpinner` の場合にのみ返されます。ユーザーに表示するメッセージ。 データタイプ：文字列 | | body.messageId | サポートされているサードパーティのチャットアプリケーションに ServiceNow 仮想エージェント から送信されたメッセージの一意の識別子。 テーブル:会話メッセージ \[sys_cs_message\] データタイプ：文字列 | | body.multiSelect | ユーザーが複数のオプションを選択できるかどうかを示すフラグ。 可能な値： * true:複数選択。 * false:単一の選択。 {#bot-POST-integration__ul_hql_jkx_zmb} データタイプ：ブーリアン | | body.nluTextEnabled | ユーザーチャットクライアントが自然言語理解 (NLU) テキストメッセージを受信できるかどうかを示すフラグ。 可能な値： * true:NLU メッセージを受信できます。 * false:NLU メッセージを受信できません。 {#bot-POST-integration__ul_iql_jkx_zmb} データタイプ：ブーリアン | | body.options | ピッカーコントロールで使用できるオプションを説明するリスト。 データタイプ：オブジェクトのアレイ "options": [ { "attachment": "String", "description": "String", "enabled": Boolean, "label": "String", "renderStyle": "String", "value": "String" } ] | | body.options.attachment | 取得するカルーセル内の画像の URL。 データタイプ：文字列 | | body.options.description | カルーセルアイテムの説明。 データタイプ：文字列 | | body.options.enabled | エンドユーザーのチャットクライアントでピッカーコントロールが有効になっているかどうかを示すフラグ。ボット間の実装では、プライマリボットがピッカーコントロールが無効になっていることを確認します。 可能な値： * true:有効 * false:無効 {#bot-POST-integration__ul_jql_jkx_zmb} データタイプ：ブーリアン | | body.options.label | 関連付けられた body.options.value パラメーターに表示するラベル。 データタイプ：文字列 | | body.options.renderStyle | 関連する要素をレンダリングするときに使用するスタイル。 可能な値:data データタイプ：文字列 | | body.options.value | 関連付けられた body.options.label パラメーターに表示する値。 データタイプ：文字列 | | body.promptMsg | ピッカーコントロールで表示するプロンプトメッセージ。 データタイプ：文字列 | | body.required | エンドユーザーが本文要素のクエリに応答する必要があるかどうかを示すフラグ。 可能な値： * true:必須 * false:オプション {#bot-POST-integration__ul_lql_jkx_zmb} データタイプ：ブーリアン | | body.spinnerType | actionTypeが `StartSpinner` の場合にのみ返されます。チャットユーザーに表示されるスピナーのタイプ。 可能な値： wait_time: ライブエージェントに転送されるまでの遅延時間を示すメッセージ。 データタイプ：文字列 | | body.style | 本文要素のスタイル。 可能な値： * ボタン * カルーセル * リスト * null データタイプ：文字列 | | body.templateName | 関連するカードの表示に使用するテンプレートの名前。 データタイプ：文字列 | | body.type | DefaultOutputLink に対してのみ返されます。返されるデータのタイプ。 可能な値:link データタイプ：文字列 | | body.uiType | 本文要素のタイプ。可能な値は、 body.group パラメーターの値によって異なります。これらの値は、仮想エージェントデザイナーで定義されたコントロールにマップされます。詳細については、「 [仮想エージェントデザイナーの概要](https://www.servicenow.com/docs/access?context=conversation-designer-virtual-agent&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)」を参照してください。 可能な値： * アクションメッセージ * デフォルト出力カード出力カード * デフォルト日付 * 日付 * DateTime * 時刻 {#bot-POST-integration__ul_qql_jkx_zmb} * DefaultGroupedPartsOutputControlGroupedPartsOutputControl * デフォルト HTML出力 HTML * デフォルト出力イメージ出力イメージ * デフォルト出力リンクOutputLink * デフォルトテキスト * InputText * 出力テキスト * ファイルのアップロード {#bot-POST-integration__ul_uql_jkx_zmb} * デフォルトピッカー * ピッカー * TopicPickerControl * ブーリアン {#bot-POST-integration__ul_vql_jkx_zmb} データタイプ：文字列 | | body.value | 本文要素の処理に使用するデータ。返される情報のタイプは、本文要素のタイプによって異なります。 OutputLink:オブジェクト。 "value": { "action": "String" } OutputImage:文字列。画像 URL。 OutputHtml:文字列。クライアントがレンダリングする必要がある HTML。 データタイプ:文字列またはオブジェクト | | body.value.action | DefaultOutputLink に対してのみ返されます。返されたリンクの URL。 データタイプ：文字列 | | body.waitTime | ユーザーがライブエージェントに接続されるまでに待機する必要がある時間。 データタイプ：文字列 | | body.width | 関連する HTML 要素の幅。 データタイプ：数値 単位：ピクセル | | clientSessionId | エンドユーザーが ServiceNow ボットとの通信に使用しているチャットアプリケーション/サービスの一意のクライアントセッション識別子。 データタイプ：文字列 | | clientVariables | 要求本文の clientVariables パラメーターで渡されたものからコピーされた JSON 形式の名前と値のペア。これらの値はエンドポイントでは処理されませんが、特定の顧客情報を会話に添付しておくために使用できます。 データタイプ: オブジェクト | | 完了 | ServiceNow 仮想エージェントが会話を正常に完了したかどうかを示すフラグ。 可能な値： * true:会話は正常に完了しました。 * false:会話が完了しておらず、このパラメーターは応答で返されません。 データタイプ：ブーリアン | | エンタープライズ ID | 現在、使用されていません。 | | interactionId | ServiceNow 仮想エージェント とサポートされているサードパーティのチャットアプリケーション間の各会話の一意の識別子。 データタイプ：文字列 | | メッセージ | ServiceNow VA に送信されたメッセージの詳細。これは、渡されたメッセージオブジェクトと同じです。 データタイプ: オブジェクト "message": { "attachment": {Object}, "clientMessageId": "String", "text": "String", "typed": Boolean } | | message.attachment | 添付ファイルの詳細。添付ファイルは、ファイルまたは URL のいずれかです。 データタイプ: オブジェクト "attachment": { "clientAttachmentId": "String", "contentType": "String", "fileName": "String", "url": "String" | | message.attachment.clientAttachmentId | ServiceNow VA に送信される添付ファイルの一意の識別子。この識別子の形式は、実装者によって決定されます。 データタイプ：文字列 | | message.attachment.contentType | 添付ファイルの標準 MIME タイプ。 可能な値 (大文字と小文字は区別されません): * アプリケーション/msword * application/pdf * image/jpeg * image/png * text/plain * ビデオ/MPEG {#bot-POST-integration__ul_xql_jkx_zmb} データタイプ：文字列 | | message.attachment.fileName | 添付ファイルのファイル名。 データタイプ：文字列 | | message.attachment.url | 添付ファイルが配置されている URL。 データタイプ：文字列 | | message.clientMessageId | メッセージの一意の英数字識別子。 データタイプ：文字列 | | message.text | メッセージテキスト。 データタイプ：文字列 最大長:無制限 | | message.typed | メッセージが入力されたか、またはオプションの選択 (選択済み) であったかどうかを示すフラグ。 可能な値： * true:メッセージはユーザーによって入力されました。 * false:メッセージはオプションの選択でした。 データタイプ：ブーリアン | | nowBotId | 現在、使用されていません。 | | nowSessionId | 現在、使用されていません。 | | requestId | この要求の一意の識別子。 データタイプ：文字列 | | スコア | ServiceNow NLUモデルからのインテント信頼スコア (87.3% など、パーセントで指定)。このスコアにより、プライマリボットは、プライマリボットの NLU モデルの信頼度しきい値に基づいて、関連するインテントを表示するかどうかを決定できます。プライマリボットのNLUモデルの信頼度しきい値をすべてのセカンダリボットに一貫して適用できるように、ServiceNow インスタンスではServiceNow NLUモデルの信頼度しきい値は無視されます。 データタイプ：数値 | | takeControl | ServiceNow 仮想エージェントがプライマリボットにコントロールを返すことを示すフラグ。 可能な値： * true:制御をプライマリボットに戻します。 * false:コントロールを維持します。 {#bot-POST-integration__ul_zql_jkx_zmb} データタイプ：ブーリアン デフォルト値：false | | userId | ボットとやり取りしているエンドユーザーの識別子。 データタイプ：文字列 | [ ] {#bot-POST-integration__table_bql_jkx_zmb} ### 会話を開始するSTART_CONVERSATIONアクションを使用して会話を開始します {#bot-POST-integration__vabot-ex-startconvo} 次の例は、 [START_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) アクションを使用して 仮想エージェントとの会話を開始する方法を示しています。この呼び出しにより、ユーザーは挨拶トピックに誘導されます。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "asd2423-sda23-qwe23-we23", "action": "START_CONVERSATION", "enterpriseId": "ServiceNow", "nowBotId": "A85PWLERF", "clientSessionId": "", "nowSessionId": "", "message":{ "text": "", "typed": true, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "emailId": "beth.anglin@example.com", "timestamp": 1588824102, "timezone": "America/New_York" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"asd2423-sda23-qwe23-we23", "clientSessionId":"", "nowSessionId":"", "message":{ "text":"", "typed":true, "clientMessageId":"ABC-123" }, "userId":"beth.anglin", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.", "maskType":"NONE" }, { "uiType":"TopicPickerControl", "group":"DefaultPicker", "nluTextEnabled":false, "promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type help any time when you need help.", "label":"Show me everything", "options":[ { "label":"b2b topic", "value":"2bb7bd7670de6010f877c7f188266fc7", "enabled":true }, { "label":"Live Agent Support.", "value":"ce2ee85053130010cf8cddeeff7b12bf", "enabled":true } ] } ], "score":1 } ### チャットインタラクションの作成 {#bot-POST-integration__vabot-ex-createconvo} 次の例は、 [CREATE_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) アクションを使用してチャットインタラクションを作成する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "action": "CREATE_CONVERSATION", "message": { "text": "hi", "typed": false }, "userId": "abel.tuter", "emailId": "abel.tuter@example.com" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "message": { "text": "hi", "typed": false }, "userId": "abel.tuter", "interactionId": "240c91c8fd9f2e50f877c29ac5fbe8ed", "body": [ { "uiType": "ActionMsg", "actionType": "CreateConversation", "conversationId": "a40c91c8fd9f2e50f877c29ac5fbe8eb", "interactionId": "240c91c8fd9f2e50f877c29ac5fbe8ed", "messageId": "b80c91c8fd9f2e50f877c29ac5fbe8f8" } ], "score": 1 } ### START_CREATED_CONVERSATIONアクションを使用して開始された会話を開始 {#bot-POST-integration__vabot-ex-startcreatedconvo} 次の例は、 [CREATE_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) アクションを使用して開始されたチャット会話を開始する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "action": "START_CREATED_CONVERSATION", "userId": "abel.tuter", "emailId": "abel.tuter@example.com" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9", "clientSessionId":"", "message":{ "text":"hola", "typed":true }, "userId":"abel.tuter", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.", "maskType":"NONE" }, { "uiType":"TopicPickerControl", "group":"DefaultPicker", "nluTextEnabled":false, "promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type hellllp! any time when you need help.", "label":"Show me everything", "options":[ { "label":"boolean check", "value":"1b5257a1db712010d3d6d9595e9619f3", "enabled":true }, { "label":"Test_table_datepicker", "value":"6515f0cadb4220108249f7541d961980", "enabled":true }, { "label":"Test File upload", "value":"76c1f4b2db7520108249f7541d9619a7", "enabled":true }, { "label":"Test B2B 2", "value":"8373e55cdb8120108249f7541d96196d", "enabled":true }, { "label":"FAQ Conversation Builder_Global", "value":"9f3114a3dbc520108249f7541d961981", "enabled":true }, { "label":"Get to know you", "value":"a443dd6adb812010d3d6d9595e961954", "enabled":true }, { "label":"Get to know you_Global", "value":"b1a56b87db8120108249f7541d9619b2", "enabled":true }, { "label":"Live Agent Support.", "value":"ce2ee85053130010cf8cddeeff7b12bf", "enabled":true }, { "label":"Apply for PTO_B2B NLU", "value":"d948c94cdb052010d3d6d9595e961969", "enabled":true } ] } ], "score":1 } ### を使用した会話の不具合 {#bot-POST-integration__vabot-ex-faultconvo} 次の例は、 [FAULT_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) アクションを使用し、 cause パラメーターの値を設定する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "action": "FAULT_CONVERSATION", "cause": "EXTERNAL_FAILURE", "userId": "abel.tuter", "emailId": "abel.tuter@example.com" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "userId": "abel.tuter", "body": [], "takeControl": true, "score": 0 } ### エージェントチャットパネルのメッセージを更新する {#bot-POST-integration__vabot-ex-updatemsg} [UPDATE_MESSAGES](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms)アクションは、ライブエージェントの会話中に使用され、サードパーティのチャット統合からのメッセージの更新をエージェントチャットパネルに反映するために使用されます。このアクションはメッセージのリストを受け入れることができ、すべてのメッセージの更新を 1 回の実行で実行できます。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "message": [ { "status": "external_error", "id": "54623afeff762210efa1ffffffffff77" } ], "userId": "abel.tuter", "emailId": "abel.tuter@example.com", "action": "UPDATE_MESSAGES" }" --user "username":"password" VA から構成された応答エンドポイントに送信される応答メッセージは次のとおりです。 Message Processed Successfully ### チャット履歴のみを更新 {#bot-POST-integration__vabot-ex-sendhist} 次の例は、 [SEND_HISTORY](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) アクションを使用してチャット履歴のみを更新する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "", "userId": "abel.tuter", "emailId": abel.tuter@example.com, "action": "SEND_HISTORY", "history": [ { "isBotMessage": true, "value": "How can I help you?", "displayName": "Genesys Bot", "type": "text", "timestamp": "1739866290393" }, { "isBotMessage": false, "value": "I am facing an issue while creating an incident.", "displayName": "User", "type": "text", "timestamp": "1739877357223" }, { "isBotMessage": true, "value": "Okay. i am routing you to an agent", "displayName": "Genesys Bot", "type": "text", "timestamp": "1739877409746" }, { "isBotMessage": false, "value": "Thanks.", "displayName": "User", "type": "text", "timestamp": "1739877453201" } ] }" --user "username":"password" VA から構成された応答エンドポイントに送信される成功応答は次のとおりです。 {"status": "success"} ### 発言を使用してライブエージェントに会話を転送する {#bot-POST-integration__example_e31_srx_sqb} 次の例は、message.text パラメーターで`エージェント`を発言として渡すことで、挨拶トピックをバイパスして会話をライブエージェント転送する方法を示しています。可能な発言値は、sys_cs_contextual_actionテーブルで定義されます。コンテキストアクションの詳細については、「 [カスタムチャット統合のコンテキストアクション](https://www.servicenow.com/docs/access?context=contextual-actions&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)」を参照してください。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: ORANGE" \ --data " { "requestId": "322bas2be70-sadsa-we32-3eq2-1231ra9", "botToBot": true, "clientSessionId": "", "silentMessage": false, "message":{ "text": "agent", "typed": true }, "userId": "abel.tuter", "emailId": "abel.tuter@servicenow.com", "timestamp": 1588824102, "timezone": "America/New_York" }" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"322bas2be70-sadsa-we32-3eq2-1231ra9", "clientSessionId":"", "message":{ "text":"agent", "typed":true }, "userId":"abel.tuter", "body":[ { "uiType":"Picker", "group":"DefaultPicker", "required":true, "nluTextEnabled":false, "label":"I want to be sure I got this right. What item best describes what you want to do?", "itemType":"List", "style":"list", "multiSelect":false, "options":[ { "label":"Live Agent Support.", "value":"Live Agent Support.", "renderStyle":"data", "enabled":false }, { "label":"Virtual Agent Capabilities.", "value":"Virtual Agent Capabilities.", "renderStyle":"data", "enabled":false }, { "label":"I want something else", "value":"-1", "renderStyle":"data", "enabled":false } ], "scriptedData":null } ], "score":1 } ### ユーザーの選択に基づいてライブエージェントサポートに会話を転送する {#bot-POST-integration__example_f31_srx_sqb} 次の例は、以前のインタラクションからのユーザーの選択に基づいて会話をライブエージェントサポートに転送する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: ORANGE" \ --data "{ "requestId": "322bas2be70-sadsa-we32-3eq2-1231ra9", "botToBot": true, "clientSessionId": "", "silentMessage": false, "message":{ "text": "Live Agent Support.", "typed": true }, "userId": "abel.tuter", "emailId": "abel.tuter@servicenow.com", "timestamp": 1588824102, "timezone": "America/New_York" } " VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"322bas2be70-sadsa-we32-3eq2-1231ra9", "clientSessionId":"", "message":{ "text":"Live Agent Support.", "typed":true }, "userId":"abel.tuter", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"Please stand by while I connect you to a live agent." } ], "agentChat":true, "score":1 } ### アクションパラメーターを設定して 仮想エージェント 会話を終了します {#bot-POST-integration__vabot-ex-endConvo} 次の例は、action パラメーターを [END_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) に設定して仮想エージェント会話を終了する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "s345ew-sjg554-qwe23-we23", "action": "END_CONVERSATION", "enterpriseId": "ServiceNow", "nowBotId": "A85PWLERF", "clientSessionId": "", "nowSessionId": "", "message":{ "text": "b2b topic", "typed": true, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "emailId": beth.anglin@example.com, "timestamp": 1588824102, "timezone": "America/New_York" }" --user "username":"password" 以下は、VA から構成済み応答エンドポイントに送信された応答本文で、会話が終了したことを示しています。 { "requestId":"s345ew-sjg554-qwe23-we23", "clientSessionId":"", "nowSessionId":"", "message":{ "text":"", "typed":true, "clientMessageId":"ABC-123" }, "userId":"beth.anglin", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"The conversation has ended. If you need help again, type hi.", "maskType":"NONE" } ], "score":1 } ### アクションパラメーターを設定して ライブエージェント 会話を終了します {#bot-POST-integration__example_fxw_jbc_s4b} 次の例は、action パラメーターを [END_CONVERSATION](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) に設定してライブエージェント会話を終了する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "sad-sjg554-qwe23-we23", "action": "END_CONVERSATION", "enterpriseId": "ServiceNow", "nowBotId": "A85PWLERF", "clientSessionId": "", "nowSessionId": "", "message":{ "text": "", "typed": true, "clientMessageId": "ABC-123" }, "userId": "beth.anglin", "emailId": "beth.anglin@example.com", "timestamp": 1588824102, "timezone": "America/New_York" }" --user "username":"password" 以下は、VA から構成済み応答エンドポイントに送信された応答本文で、会話が終了したことを示しています。 { "requestId":"sad-sjg554-qwe23-we23", "clientSessionId":"", "nowSessionId":"", "message":{ "text":"", "typed":true, "clientMessageId":"ABC-123" }, "userId":"beth.anglin", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"The conversation has ended. If you need help again, type hi.", "maskType":"NONE" } ], "completed":true, "score":1 } ### sys_cs_contextual_actionテーブルで定義されたコマンドを発言として使用して会話を開始する 仮想エージェント 次の例は、前の例のように action パラメーターを `START_CONVERSATION` に設定するのではなく、sys_cs_contextual_action テーブルで定義された Hi コマンドを発言として使用して、仮想エージェントとの会話を開始する方法を示しています。この例は、 Hi コマンドの言語バリアントの 1 つである「hola」の使用を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: ORANGE" \ --data "{ "requestId": "302bas2be70-sadsa-we32-3eq2-1231ra9", "botToBot": true, "clientSessionId": "", "silentMessage": false, "message":{ "text": "hola", "typed": true }, "userId": "fred.ludy", "emailId": "abel.tuter@servicenow.com", "timestamp": 1588824102, "timezone": "America/New_York" }" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9", "clientSessionId":"", "message":{ "text":"hola", "typed":true }, "userId":"fred.ludy", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.", "maskType":"NONE" }, { "uiType":"TopicPickerControl", "group":"DefaultPicker", "nluTextEnabled":false, "promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type hellllp! any time when you need help.", "label":"Show me everything", "options":[ { "label":"boolean check", "value":"1b5257a1db712010d3d6d9595e9619f3", "enabled":true }, { "label":"Test_table_datepicker", "value":"6515f0cadb4220108249f7541d961980", "enabled":true }, { "label":"Test File upload", "value":"76c1f4b2db7520108249f7541d9619a7", "enabled":true }, { "label":"Test B2B 2", "value":"8373e55cdb8120108249f7541d96196d", "enabled":true }, { "label":"FAQ Conversation Builder_Global", "value":"9f3114a3dbc520108249f7541d961981", "enabled":true }, { "label":"Get to know you", "value":"a443dd6adb812010d3d6d9595e961954", "enabled":true }, { "label":"Get to know you_Global", "value":"b1a56b87db8120108249f7541d9619b2", "enabled":true }, { "label":"Live Agent Support.", "value":"ce2ee85053130010cf8cddeeff7b12bf", "enabled":true }, { "label":"Apply for PTO_B2B NLU", "value":"d948c94cdb052010d3d6d9595e961969", "enabled":true } ] } ], "score":1 } ### sys_cs_contextual_actionテーブルで定義されたコマンドを発言として使用して会話を終了する 次の例は、前の例のように action を `END_CONVERSATION` に設定するのではなく、sys_cs_contextual_actionテーブルで定義された Bye コマンドを使用して、仮想エージェントとの会話を終了する方法を示しています。この例は、 Bye コマンドの言語バリアントの 1 つである「choa」の使用を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: ORANGE" \ --data "{ "requestId": "302bas2be70-sadsa-we32-3eq2-1231ra9", "botToBot": true, "clientSessionId": "", "silentMessage": false, "message":{ "text": "choa", "typed": true }, "userId": "fred.ludy", "emailId": "abel.tuter@servicenow.com", "timestamp": 1588824102, "timezone": "America/New_York" }" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9", "clientSessionId":"", "message":{ "text":"chao", "typed":true }, "userId":"fred.ludy", "body":[ { "uiType":"Picker", "group":"DefaultPicker", "required":true, "nluTextEnabled":false, "label":"Please make a selection.", "itemType":"List", "style":"list", "multiSelect":false, "options":[ { "label":"End conversation", "value":"1", "renderStyle":"data", "enabled":false }, { "label":"Cancel", "value":"0", "renderStyle":"data", "enabled":false } ], "scriptedData":null } ], "score":1 } ### SWITCH アクションパラメーターを使用して進行中の会話を変更します {#bot-POST-integration__vabot-ex-switch} 次の例は、 [SWITCH](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) action パラメーターを使用して、進行中の会話を intent.id パラメーターで指定された内容に一致するトピックに変更する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "sdfsfs-hgfhg-34fssd-zxcz-sd43", "enterpriseId": "ServiceNow", "nowBotId": "A85PWLERF", "clientSessionId": "", "nowSessionId": "", "action": "SWITCH", "intent" : { "id": "Saloon Vehicle" }, "message":{ "typed": true, "clientMessageId": "ABC-123" }, "userId": "Guest", "timestamp": 1588824102, "timezone": "America/New_York" }" --user "username":"password" VA から構成された応答エンドポイントに送信された応答本文を以下に示します。この応答本文は、VA が新しいトピックに切り替わったことを示しています。 { "requestId":"sdfsfs-hgfhg-34fssd-zxcz-sd43", "clientSessionId":"", "nowSessionId":"", "message":{ "typed":true, "clientMessageId":"ABC-123" }, "userId":"Guest", "body":[ { "uiType":"InputText", "group":"DefaultText", "required":true, "nluTextEnabled":false, "label":"limo input:", "maskType":"NONE" } ], "score":1 } ### 発言の 自然言語理解 (NLU) (NLU) 信頼スコアを取得する {#bot-POST-integration__example_onb_ltc_s4b} 次の例は、VA でNLUが有効になっている場合に発言のNLU信頼スコアを取得する方法を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{  "requestId": "sdfsfs-hgfhg-34fssd-zxcz-sd43",  "enterpriseId": "ServiceNow",  "nowBotId": "A85PWLERF",  "clientSessionId": "",  "nowSessionId": "",   "message":{   "text": "most popular choice",     "typed": true,     "clientMessageId": "ABC-123"  },  "userId": "Guest",  "timestamp": 1588824102,  "timezone": "America/New_York" }" --user "username":"password" 以下は、VA から構成された応答エンドポイントに送信される応答本文で、NLU 信頼スコアを示しています。 {   "requestId":"sdfsfs-hgfhg-34fssd-zxcz-sd43",   "clientSessionId":"",   "nowSessionId":"",   "message":{    "text":"most popular choice",    "typed":true,    "clientMessageId":"ABC-123"   },   "userId":"Guest",   "body":[     {     "uiType":"InputText",       "group":"DefaultText",       "required":true,       "nluTextEnabled":false,       "label":"model input:",       "maskType":"NONE"     }   ],   "score":"0.92" } ### 特定のキューのライブエージェントに会話を転送する {#bot-POST-integration__vabot-ex-agent} 次の例は、特定のキューのライブエージェントに会話を転送する方法を示しています。最初に、特定の条件を使用してキューを設定する必要があります。次に、これらの条件を要求本文の contextVariables として渡します。この例では、 [AGENT](https://servicenow-prod.fluidtopics.net/zUBz_BLPqzQJirmpuIOZiA#bot-POST-integration__vabot-req-parms) アクションパラメーターを使用します。作業項目キューの作成の詳細については、「 [作業項目キューの作成](https://www.servicenow.com/docs/access?context=awa-create-queue&version=australia&pubname=australia-conversational-interfaces&ft:locale=en-US)」を参照してください。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --data "{ "requestId": "34re-dasd-qwe23-dsds", // Unique value for a message (hash) "enterpriseId": "ServiceNow", // ServiceNow (Optional "nowBotId": "A85PWLERF", // In case of multiple ServiceNow secondary bots (one for HR, one for ITSM) "action":"AGENT", // Actions to close conversation. Other possible value is END_CONVERSATION "clientSessionId": "", // Client conversation id "nowSessionId": "", // ServiceNow conversation id "message":{ "text": "How are you?", // User passed message "typed": true, // typed or clicked "clientMessageId": "ABC-123" }, "userId": "abraham.lincoln", // User's id in their system "emailId": "abraham.lincoln@example.com", "timestamp": 1588824102, "timezone": "America/New_York", "contextVariables":{ "b2b_category":"humanresource" } }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"34re-dasd-qwe23-dsds", "clientSessionId":"", "nowSessionId":"", "message":{ "text":"How are you?", "typed":true, "clientMessageId":"ABC-123" }, "userId":"abraham.lincoln", "body":[ { "uiType":"OutputText", "group":"DefaultText", "value":"I am sorry but I didn't understand your request.", "maskType":"NONE" }, { "uiType":"OutputText", "group":"DefaultText", "value":"Please try giving me your request in a different way. I'm currently better at understanding short sentences.", "maskType":"NONE" }, { "uiType":"TopicPickerControl", "group":"DefaultPicker", "nluTextEnabled":false, "promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type help any time when you need help.", "label":"Show me everything", "options":[ { "label":"Live Agent Support.", "value":"ce2ee85053130010cf8cddeeff7b12bf", "enabled":true } ] } ], "score":0 } ### 公開アプリケーション/PDF 添付ファイルの転送 {#bot-POST-integration__example_yr4_2ry_lqb} この例では、公開アプリケーション/PDF 添付ファイルを転送する方法を示します。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: BOT_Token" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "U94CSJLEN", "message": { "attachment": { "clientAttachmentId": "my-unique-identifier", "contentType": "application/pdf", "fileName": "MY PDF TEST", "url": "http://www.africau.edu/images/default/sample.pdf" } }, "userId": "U94CSJLEN", "emailId": "admin@example.com" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId":"U94CSJLEN", "message":{ "attachment":{ "clientAttachmentId":"my-unique-identifier", "contentType":"application/pdf", "fileName":"MY PDF TEST", "url":"http://www.africau.edu/images/default/sample.pdf"} }, "userId":"U94CSJLEN", "body":[ { "uiType":"OutputText", "group":"DefaultText", "required":false, "nluTextEnabled":false, "label":"File got", "maskType":"NONE", "itemType":"outputtext" }, { "uiType":"OutputText", "group":"DefaultText", "required":false, "nluTextEnabled":false, "label":"The conversation has ended. If you need help again, type hi.", "maskType":"NONE", "itemType":"outputtext" } ], "completed":true, "score":1 } ### ビデオ/mpeg 添付ファイルの転送 {#bot-POST-integration__example_uyn_mwy_lqb} この例は、ビデオ/mpeg 添付ファイルをアップロードするための要求/応答を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: BOT_TOKEN" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "U94CSJLEN", "message": { "attachment": { "clientAttachmentId": "my-unique-identifier10", "contentType": "video/mpeg", "fileName": "MY TEST10.mp4", "url": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4" } }, "userId": "U94CSJLEN", "emailId": "admin@example.com" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId":"U94CSJLEN", "message":{ "attachment":{ "headers":{ "Authorization":"Basic amFzbWluZS53YWRod2FuaWE6VGVzdGluZ0AxMjM=" }, "clientAttachmentId":"my-unique-identifier10", "contentType":"video/mpeg", "fileName":"MY TEST10.mp4", "url":"https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4" } }, "userId":"U94CSJLEN", "body":[ { "uiType":"OutputText", "group":"DefaultText", "required":false, "nluTextEnabled":false, "label":"File got", "maskType":"NONE", "itemType":"outputtext" }, { "uiType":"OutputText", "group":"DefaultText", "required":false, "nluTextEnabled":false, "label":"The conversation has ended. If you need help again, type hi.", "maskType":"NONE","itemType":"outputtext" } ], "completed":true, "score":1 } ### 画像/JPEG 添付ファイルを転送 {#bot-POST-integration__example_nnb_nwy_lqb} この例は、画像/jpeg 添付ファイルをアップロードするための要求/応答を示しています。 curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --header "token: BOT_TOKEN" \ --data "{ "requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId": "U94CSJLEN", "message": { "attachment": { "clientAttachmentId": "my-unique-identifier10", "contentType": "image/jpeg", "fileName": "MY TEST10.jpg", "url": "https://image.imagestock.com/image-photo/pink-butterfly-isolated-on-white-260nw-1218104047.jpg" } }, "userId": "U94CSJLEN", "emailId": "admin@example.com" }" --user "username":"password" VA から構成済み応答エンドポイントに送信される応答本文は次のとおりです。 { "requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c", "clientSessionId":"U94CSJLEN", "message":{ "attachment":{ "headers":{ "Authorization":"Basic amFzbWluZS53YWRod2FuaWE6VGVzdGluZ0AxMjM=" }, "clientAttachmentId":"my-unique-identifier10", "contentType":"image/jpeg", "fileName":"MY TEST10.jpg", "url":"https://image.imagestock.com/image-photo/pink-butterfly-isolated-on-white-260nw-1218104047.jpg" } }, "userId":"U94CSJLEN", "body":[ { "uiType":"OutputText", "group":"DefaultText", "required":false, "nluTextEnabled":false, "label":"File got", "maskType":"NONE", "itemType":"outputtext" }, { "uiType":"OutputText", "group":"DefaultText", "required":false, "nluTextEnabled":false, "label":"The conversation has ended. If you need help again, type hi.", "maskType":"NONE", "itemType":"outputtext" } ], "completed":true, "score":1 }