仮想エージェントボット統合 API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間:75分
  • 仮想エージェントボット統合 API は、ユーザーがチャットインターフェイスまたはボットエコシステムをServiceNow 仮想エージェントライブエージェントと統合できるようにするエンドポイントを提供します。

    この API は、 仮想エージェント で提供される会話型カスタムチャット統合フレームワークに基づいて構築され、 sn_va_as_service 名前空間で動作します。

    仮想エージェント ボット統合 API のインストールと構成の詳細については、「Using Virtual Agent with a live agent」を参照してください。

    VA ボット統合:POST /sn_va_as_service/bot/integration

    指定されたメッセージ、添付ファイル、または 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

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    なし
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文のパラメーター
    名前 説明
    action VA が実行する必要があるアクション。
    有効な値:
    • AGENT:会話を VA から ライブエージェント に切り替えます。
    • CREATE_CONVERSATION:チャットインタラクションを作成します。
    • END_CONVERSATION:チャットの会話を終了します。このアクションを使用する場合は、message.text パラメーターを空にする必要があります。
    • FAULT_CONVERSATION:会話に欠陥があります。FAULT_CONVERSATION アクションを設定するときは、 cause パラメーターの説明を入力します。
    • SEND_HISTORY:チャット履歴のみを更新します。チャット履歴は、 history パラメーターで指定した標準のメッセージ処理を使用して送信することもできます。
    • SET_USER_TIMEZONE:ユーザーのタイムゾーンを timezone パラメーターで指定されたタイムゾーンに設定します。同じパラメーターを使用してリセットするまで、このタイムゾーンは有効です。
    • START_CONVERSATION:チャット会話を開始します。
    • START_CREATED_CONVERSATION: CREATE_CONVERSATIONを使用して開始されたチャット会話を開始します。
    • SWITCH: intent.id パラメーターまたは topic.name パラメーターで指定された内容に一致するトピックに会話を切り替えます。
      注:
      トピックの切り替えには、インテントディスカバリーがプライマリボットで発生した場合にのみ、 SWITCH アクションを使用します。ServiceNow® VA で Intent Discovery が行われる場合は、message.text パラメーターを使用します。
    • TYPING/VIEWING:ライブエージェントに入力インジケーターを表示します。最初に TYPING を送信し、ユーザーが入力を終えたら VIEWING を送信します。
    • UPDATE_MESSAGES:このアクションはライブエージェントの会話中に使用され、エージェントチャットパネルに反映されるライブエージェントから受信したメッセージについて、サードパーティチャット統合用の 2 つのメッセージ更新機能を提供します。
      • サードパーティからのメッセージを送信した後の最新のメッセージ配信ステータス。
      • エージェントチャットパネルのテキストが更新されました。

      サードパーティチャット統合は、エンドユーザーに送信する前にメッセージのテキスト部分を更新できます。このアクションを呼び出してエージェントチャットパネルのテキストを更新し、更新されたテキストを「更新済み」タグ付きでエージェントに表示できるようにします。

      このアクションは、 message.status パラメーターと message.id パラメーターとともに使用します。

      このオプションは、プロバイダーアプリケーションに関連付けられた名前third_party_chatカスタムアダプタプロパティが true に設定されている場合にのみ有効です。これは、チャネルの同期/非同期の性質に関係なく、同期アクションです。

    • null またはパラメーターが渡されない:メッセージを ServiceNow VA に送信します。
    サードパーティチャット統合は、エンドユーザーに送信する前に、ライブエージェントからトリガーされたテキストメッセージを更新できます。このアクションを呼び出してエージェントチャットパネルのテキストを更新し、更新されたテキストを「更新済み」タグ付きでエージェントに表示できるようにします。

    データタイプ:文字列

    デフォルト:Null

    ボットツーボット 会話がプライマリボットとセカンダリボット間など、ボット間であるかどうかを示すフラグ。
    可能な値:
    • true:ボット間の会話。
    • false:スタンドアロン ServiceNow ボットの会話。

    データタイプ:ブーリアン

    デフォルト:true

    原因 チャット会話の障害の原因 ( EXTERNAL_FAILUREなど)。このプロパティは、 action プロパティが FAULT_CONVERSATION に設定されている場合にのみ使用されます。

    データタイプ:文字列

    clientSessionId エンドユーザーが ServiceNow ボット またはサポートされているサードパーティのチャットアプリケーションとの通信に使用しているアプリケーション/サービスの一意のクライアントセッション識別子。
    • この ID は、特定のユーザーの会話に関する要求/応答のセットを識別するのに役立ちます。
    • このパラメーターの形式は、実装者が決定します。
    • この値は、[カスタムアダプタプロパティ] フォームの [third_party_chat] フィールドの値が true の場合にのみ更新されます。

    テーブル:インタラクション [interaction]

    データタイプ:文字列

    デフォルト:Null

    clientVariables 応答で返送されるパススルー JSON 形式の名前と値のペア。これらの値はエンドポイントでは処理されませんが、特定の顧客情報を会話に添付しておくために使用できます。

    データタイプ: オブジェクト

    デフォルト:Null

    contextVariables ユーザーに関する追加情報を提供する JSON 形式の名前と値のペア。会話エクスペリエンスをカスタマイズするには、この情報を入力します。コンテキスト変数の詳細については、「 チャットコンテキスト変数の定義と公開」を参照してください。
    例:
    "contextVariables": {
      "requester_session_language": "es", 
      "deviceTimeZone": "America/Los_Angeles"
      "live_agent_only": "true",
      "liveagent_deviceType": "test_device_type"
      "topic": "7c3c819073a3101066c7e9344ef6a7e4" 
    } 

    データタイプ: オブジェクト

    デフォルト:Null

    emailId アカウントのリンクを有効にする場合に必要です。有効にしない場合は、すべてのユーザーがゲストユーザーと見なされます。チャットクライアントのエンドユーザー (ボットがやり取りしているユーザー) のメールアドレス。アカウントのリンクの詳細については、「 ServiceNow ユーザーアカウントを仮想エージェント会話のメッセージングアプリケーションにリンクする」を参照してください。

    データタイプ:文字列

    履歴 ユーザーによる最初の要求から始まる、プライマリボットとユーザーの会話の履歴。

    データタイプ: オブジェクト

    "history": {
      "displayName": "String",
      "isBotMessage": Boolean,
      "timestamp": "String",
      "type": "String",
      "value": "String"
    }
    history.displayName メッセージの送信先のユーザーの名前。プライマリボットの場合は、 ボットを渡します。

    データタイプ:文字列

    history.isBotMessage メッセージがプライマリボットによって送信されたかどうかを示すフラグ。
    有効な値:
    • true:メッセージはプライマリボットによって送信されました。
    • false:メッセージはユーザーによって送信されました。

    データタイプ:ブーリアン

    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

    データタイプ:文字列

    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 - 最初は、ライブエージェントからサードパーティのチャット統合に配信されたメッセージに対して単一のチェックマークが表示されます。このステータスは、メッセージがサードパーティのチャット統合からエンドユーザーに正常に配信された場合に使用する必要があります。成功すると、エージェントチャットパネルに二重チェックマークが表示されます。

    データタイプ:文字列

    message.text attachmentパラメーターが指定されていない場合は必須です。メッセージテキスト。
    • メッセージの言語は contextVariables パラメーターで渡す必要があります。
    • action プロパティの値が END_CONVERSATION の場合は空である必要があります。
    • アクションプロパティの値が UPDATE_MESSAGES の場合、エージェントチャットパネルに反映されるように更新されたテキストである必要があります。

    データタイプ:文字列

    最大長:無制限

    message.typed 必須です。メッセージが入力されたか、またはオプションの選択 (選択済み) であったかどうかを示すフラグ。
    有効な値:
    • true:メッセージはユーザーによって入力されました。
    • false:メッセージはオプションの選択でした。

    データタイプ:ブーリアン

    requestId 必須です。この要求の一意の英数字識別子。この識別子の形式は、実装者によって決定されます。

    データタイプ:文字列

    サイレントメッセージ サイレントメッセージかどうかを示すフラグ。サイレントメッセージとは、応答を必要としないメッセージです。
    有効な値:
    • true:サイレントメッセージ。応答メッセージは想定されていません。
    • false:通常のメッセージ、応答メッセージが必要です。
    注:
    silentMessage = true の要求が送信された場合、後続のすべてのボットメッセージは、silentMessage = false を渡してサイレントモードをオフにする要求が送信されるまで抑制されたままになります。

    データタイプ:ブーリアン

    デフォルト値:false

    timestamp チャットクライアントのエンドユーザーからメッセージが送信されたときの Unix エポック時間。

    データタイプ:数値

    単位:ミリ秒

    デフォルト:現在時刻

    タイムゾーン チャットクライアントのエンドユーザーの GMT タイムゾーン。
    例:
    "timezone":"Asia/Kolkata"

    使用可能なタイムゾーン値のリストについては、「 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones」を参照してください。

    データタイプ:文字列

    デフォルト: 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 必須です。一意のユーザー識別子。これは、ボットとやり取りしているエンドユーザーの識別子です。

    データタイプ:文字列

    ヘッダー

    次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    トークン トークンベースの認証を使用する場合は必須です。基本認証または OAuth 認証のオプション。このエンドポイントにトークン認証が設定されている場合に使用する認証トークン。

    データタイプ:文字列

    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    ステータスコード 200 を受信しても応答がない場合は、次の点を確認してください。
    • 要求が静的、JWT、またはハッシュベースのトークン検証で失敗しているかどうか (通常は 仮想エージェントのワーカースレッドで発生します)。
    • 要求本文の形式が正しいかどうか。間違っていると、変換は正しく行われません。
    • 要求本体に一部の必須パラメーターが欠落しているかどうか。ServiceNow インスタンスのシステムログで例外とエラーを追跡できます。
    • 応答を受信するために REST メッセージで定義されたサイトが運用可能かどうか。ログで検出できます。
    • 応答を投稿する場所を定義する REST メッセージが正しく設定されていることを確認します。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    401 権限がありません。ユーザー認証情報が正しくないか、渡されていません。
    405 メソッドが無効です。機能が無効になっています。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

    応答本文のパラメーター

    エンドポイント呼び出しのステータス。これは、最初のコール要求が受信されたときに応答として送信されます。要求はまだ処理されていません。

    名前 説明
    エラー 検出されたエラーの説明。エラーが発生した場合にのみ返されます。

    データタイプ: オブジェクト

    "error": {
      "detail": "String",
      "message": "String"
    }
    error.detail 発生したエラーの詳細。

    データタイプ:文字列

    error.message エラーメッセージがスローされました。

    データタイプ:文字列

    status エンドポイント呼び出しのステータス。
    有効な値:
    • 失敗
    • 成功

    データタイプ:文字列

    VA 応答本文パラメーター

    VA から構成された応答エンドポイントに送信される応答本文。

    名前 説明
    エージェントチャット 会話が ServiceNow ライブエージェントに接続されているかどうかを示すフラグ。
    可能な値:
    • true:チャットメッセージはライブエージェントから送信されています。
    • false:チャットメッセージはボットから送信されており、このパラメーターは応答で返されません。

    データタイプ:ブーリアン

    本文 応答メッセージ本文の要素を説明するオブジェクトのリスト。

    データタイプ:オブジェクトのアレイ

    "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

    例:

    入力インジケーターが有効になっているときに、 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:仮想エージェントによって送信されます。

    データタイプ:ブーリアン

    body.data カード内のデータを定義する JSON 文字列。

    データタイプ:文字列

    body.group 本文要素が属するリッチコントロールグループ。送信変換スクリプトを記述することで、これらのデフォルトコントロールをさらに変換できます。これらのスクリプトの詳細については、「 仮想エージェントアクションスクリプト」を参照してください。
    可能な値:
    • デフォルト出力カード
    • デフォルト日付
    • DefaultGroupedPartsOutputControl
    • デフォルト HTML
    • デフォルト出力イメージ
    • デフォルト出力リンク
    • デフォルトテキスト
    • デフォルトピッカー

    データタイプ:文字列

    body.header リンクヘッダー。

    データタイプ:文字列

    body.height HTML 要素の高さです。

    データタイプ:数値

    単位:ピクセル

    body.itemType 本文要素のタイプ。
    可能な値:(大文字と小文字を区別)
    • デフォルトテキスト
      • ファイル
      • イメージ
      • 入力テキスト
      • 出力テキスト
    • デフォルトピッカー
      • 画像:アイテムがカルーセルに表示されます。
      • リスト:アイテムはドロップダウンスタイルのリストに表示されます。

    データタイプ:文字列

    body.label 関連付けられた要素に表示するラベル。

    データタイプ:文字列

    body.maskType 関連データの機密性。
    可能な値:
    • なし:関連データは一般的な性質のものであり、セキュリティで保護する必要はありません。
    • セキュア:関連データは機密性のものであり、安全に処理する必要があります。

    データタイプ:文字列

    body.maxCount uiTypeFileUpload の場合にのみ返されます。一度にアップロードできる添付ファイルの最大数。

    データタイプ:数値 (整数)

    body.maxSize uiTypeFileUpload の場合にのみ返されます。アップロードできる添付ファイルの最大サイズ。

    データタイプ:数値 (整数)

    単位:メガバイト

    body.message actionTypeStartSpinner の場合にのみ返されます。ユーザーに表示するメッセージ。

    データタイプ:文字列

    body.messageId サポートされているサードパーティのチャットアプリケーションに ServiceNow 仮想エージェント から送信されたメッセージの一意の識別子。

    テーブル:会話メッセージ [sys_cs_message]

    データタイプ:文字列

    body.multiSelect ユーザーが複数のオプションを選択できるかどうかを示すフラグ。
    可能な値:
    • true:複数選択。
    • false:単一の選択。

    データタイプ:ブーリアン

    body.nluTextEnabled ユーザーチャットクライアントが自然言語理解 (NLU) テキストメッセージを受信できるかどうかを示すフラグ。
    可能な値:
    • true:NLU メッセージを受信できます。
    • false:NLU メッセージを受信できません。

    データタイプ:ブーリアン

    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:無効

    データタイプ:ブーリアン

    body.options.label 関連付けられた body.options.value パラメーターに表示するラベル。

    データタイプ:文字列

    body.options.renderStyle 関連する要素をレンダリングするときに使用するスタイル。

    可能な値:data

    データタイプ:文字列

    body.options.value 関連付けられた body.options.label パラメーターに表示する値。

    データタイプ:文字列

    body.promptMsg ピッカーコントロールで表示するプロンプトメッセージ。

    データタイプ:文字列

    body.required エンドユーザーが本文要素のクエリに応答する必要があるかどうかを示すフラグ。
    可能な値:
    • true:必須
    • false:オプション

    データタイプ:ブーリアン

    body.spinnerType actionTypeStartSpinner の場合にのみ返されます。チャットユーザーに表示されるスピナーのタイプ。

    可能な値:

    wait_time: ライブエージェントに転送されるまでの遅延時間を示すメッセージ。

    データタイプ:文字列

    body.style 本文要素のスタイル。
    可能な値:
    • ボタン
    • カルーセル
    • リスト
    • null

    データタイプ:文字列

    body.templateName 関連するカードの表示に使用するテンプレートの名前。

    データタイプ:文字列

    body.type DefaultOutputLink に対してのみ返されます。返されるデータのタイプ。

    可能な値:link

    データタイプ:文字列

    body.uiType 本文要素のタイプ。可能な値は、 body.group パラメーターの値によって異なります。これらの値は、仮想エージェントデザイナーで定義されたコントロールにマップされます。詳細については、「 仮想エージェントデザイナーの概要」を参照してください。
    可能な値:
    • アクションメッセージ
    • デフォルト出力カード

      出力カード

    • デフォルト日付
      • 日付
      • DateTime
      • 時刻
    • DefaultGroupedPartsOutputControl

      GroupedPartsOutputControl

    • デフォルト HTML

      出力 HTML

    • デフォルト出力イメージ

      出力イメージ

    • デフォルト出力リンク

      OutputLink

    • デフォルトテキスト
      • InputText
      • 出力テキスト
      • ファイルのアップロード
    • デフォルトピッカー
      • ピッカー
      • TopicPickerControl
      • ブーリアン

    データタイプ:文字列

    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

    データタイプ:文字列

    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:コントロールを維持します。

    データタイプ:ブーリアン

    デフォルト値:false

    userId ボットとやり取りしているエンドユーザーの識別子。

    データタイプ:文字列

    会話を開始するSTART_CONVERSATIONアクションを使用して会話を開始します

    次の例は、 START_CONVERSATION アクションを使用して 仮想エージェントとの会話を開始する方法を示しています。この呼び出しにより、ユーザーは挨拶トピックに誘導されます。

    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 
    } 

    チャットインタラクションの作成

    次の例は、 CREATE_CONVERSATION アクションを使用してチャットインタラクションを作成する方法を示しています。

    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アクションを使用して開始された会話を開始

    次の例は、 CREATE_CONVERSATION アクションを使用して開始されたチャット会話を開始する方法を示しています。

    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 
    } 

    を使用した会話の不具合

    次の例は、 FAULT_CONVERSATION アクションを使用し、 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
    }

    エージェントチャットパネルのメッセージを更新する

    UPDATE_MESSAGESアクションは、ライブエージェントの会話中に使用され、サードパーティのチャット統合からのメッセージの更新をエージェントチャットパネルに反映するために使用されます。このアクションはメッセージのリストを受け入れることができ、すべてのメッセージの更新を 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

    チャット履歴のみを更新

    次の例は、 SEND_HISTORY アクションを使用してチャット履歴のみを更新する方法を示しています。

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

    発言を使用してライブエージェントに会話を転送する

    次の例は、message.text パラメーターでエージェントを発言として渡すことで、挨拶トピックをバイパスして会話をライブエージェント転送する方法を示しています。可能な発言値は、sys_cs_contextual_actionテーブルで定義されます。コンテキストアクションの詳細については、「 カスタムチャット統合のコンテキストアクション」を参照してください。

    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
    }

    ユーザーの選択に基づいてライブエージェントサポートに会話を転送する

    次の例は、以前のインタラクションからのユーザーの選択に基づいて会話をライブエージェントサポートに転送する方法を示しています。

    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
    }

    アクションパラメーターを設定して 仮想エージェント 会話を終了します

    次の例は、action パラメーターを END_CONVERSATION に設定して仮想エージェント会話を終了する方法を示しています。

    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
    }

    アクションパラメーターを設定して ライブエージェント 会話を終了します

    次の例は、action パラメーターを END_CONVERSATION に設定してライブエージェント会話を終了する方法を示しています。

    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テーブルで定義されたコマンドを発言として使用して会話を終了する

    次の例は、前の例のように actionEND_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 アクションパラメーターを使用して進行中の会話を変更します

    次の例は、 SWITCH 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) 信頼スコアを取得する

    次の例は、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" 
    }

    特定のキューのライブエージェントに会話を転送する

    次の例は、特定のキューのライブエージェントに会話を転送する方法を示しています。最初に、特定の条件を使用してキューを設定する必要があります。次に、これらの条件を要求本文の contextVariables として渡します。この例では、 AGENT アクションパラメーターを使用します。作業項目キューの作成の詳細については、「 作業項目キューの作成」を参照してください。

    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 添付ファイルの転送

    この例では、公開アプリケーション/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 添付ファイルの転送

    この例は、ビデオ/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 添付ファイルを転送

    この例は、画像/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
    }