---
sourceDocument: オーストラリアの対話型インターフェース
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/conversational-interfaces

 Release :

    - australia

ft:locale :

    - ja-JP

ft:publication_title :

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

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# 一般的なエラー

# 仮想エージェント APIの一般的なエラー {#ariaid-title1}

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

このセクションでは、 仮想エージェント API でよくあるエラーとその解決方法について説明します。

## 仮想エージェント API 構造の検証 {#virtual-agent-common-errors__section_r4n_y1z_m3c}

**要求構造:**  
仮想エージェント API では、次の JSON 構造が必要です。

    {
      "requestId": "any-unique-request-id",
      "clientSessionId": "any-unique-session-id",
      "userId": "any-unique-user-id",
      "emailId": "user@example.com",
      "action": "",
      "message": {
        "text": "User message text",
        "typed": true
      },
      "contextVariables": {},
      "history": [
        {
          "isBotMessage": true,
          "value": "How can I help you?",
          "displayName": "Bot",
          "type": "text"
        }
      ],
      "clientVariables": {
        "id": "va-bot-12345",
        "timestamp": "1687527831786"
      }
    }

{#virtual-agent-common-errors__table_okj_mjz_m3c__entry__3}

| フィールド | 必須 | 説明 |
|-|-|-|
| `requestId` | いいえ | 応答で返されるパススルー変数 |
| `clientSessionId` | いいえ | パススルーセッション識別子 |
| `userId` | はい | 一意のユーザー識別子 (必須) |
| `emailId` | いいえ\* | リンク用のユーザーメール (\*ユーザーのリンクには必須) |
| `アクション` | いいえ | オプションのアクションパラメーター |
| `message.text` | はい | ユーザーメッセージコンテンツ (必須) |
| `message.typed` | いいえ | 検索テキストの場合は `true`、値を選択する場合は `false` |
| `contextVariables` | いいえ | オプションのコンテキストデータ |
| `履歴` | いいえ | ボットの会話履歴 (最初の要求のみ) |
| `clientVariables` | いいえ | パススルークライアント変数 |
[表 : 1. フィールド定義]

{#virtual-agent-common-errors__table_okj_mjz_m3c}  
注:  
要求では userId と message.text のみが必須フィールドです。

## ファイルアップロードの問題 {#virtual-agent-common-errors__section_ggr_ybz_m3c}

仮想エージェント API は、同期と非同期などの 2 つのファイルアップロードモードをサポートしています。

**ファイルのアップロード要求構造:**  

    {
        "userId": "{{user_id}}",
        "message": {
            "attachment": {
                    "clientAttachmentId": "{{request_id}}",
                    "contentType": "video/mp4",
                    "fileName": "sample.mp4",
                    "url": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4",
                    "headers": {
                        "header 1": "value 1"
                    }
                },
            "text": "along with text",
            "typed": true
        }
    }

{#virtual-agent-common-errors__table_l44_hsz_m3c__entry__3}

| フィールド | 必須 | 説明 |
|-|-|-|
| `contentType` | はい | MIME タイプ ( `ビデオ/mp4`、 `画像/png` など) |
| `fileName` | はい | 拡張子付きのファイルの名前 |
| `url` | はい | ファイルをダウンロードするためのアクセス可能な URL |
| `clientAttachmentId` | いいえ | トラッキングのための一意の識別子 |
| `ヘッダー` | いいえ | ファイルダウンロード用の認証ヘッダー |
[表 : 2. フィールド定義]

{#virtual-agent-common-errors__table_l44_hsz_m3c}  
**同期モードでのファイルアップロード:**  
同期モードでファイルをアップロードするには、次の手順に従います。

1. メディア API を使用してファイルをアップロードします。詳細については、「[CCCIF Media Resource API](https://www.servicenow.com/docs/access?context=cccif-api&version=australia&pubname=australia-api-reference&ft:locale=en-US)」を参照してください。  
   メディア API は URL を返します。応答の例:

       {
         "result": {
           "mediaUrl": "<instance>/api/now/v1/cs/media/JOBBfkqSq6kDiFzxyinvHhke73O4TZ0j",
           "name": "image.png",
           "state": "available",
           "attachmentId": "e8671b9193209210a755b8e86cba104b"
         }
       }

2. 仮想エージェント API要求でメディア URL を使用します。JSON の例:

       {
         "userId": "user123",
         "message": {
           "attachment": {
             "contentType": "image/png",
             "fileName": "image.png",
             "url": "<instance>/api/now/v1/cs/media/JOBBfkqSq6kDiFzxyinvHhke73O4TZ0j"
           },
           "text": "Here is the image",
           "typed": true
         }
       }

{#virtual-agent-common-errors__ol_pbz_svz_m3c}  
**非同期モードでのファイルアップロード:**  
非同期モードでファイルをアップロードするには、次の 2 つの方法があります。

1. 仮想エージェント API要求でファイル URL を使用します。
   * 直接ファイル URL:

         {
           "userId": "user123",
           "message": {
             "attachment": {
               "contentType": "application/pdf",
               "fileName": "report.pdf",
               "url": "https://publicserver.com/files/report.pdf"
             },
             "text": "Document attached",
             "typed": true
           }
         }

   * 保護されたファイルの URL:

         {
           "userId": "user123",
           "message": {
             "attachment": {
               "contentType": "application/pdf",
               "fileName": "confidential.pdf",
               "url": "https://secureserver.com/files/confidential.pdf",
               "headers": {
                 "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                 "X-Custom-Header": "custom-value"
               }
             },
             "text": "Secure document attached",
             "typed": true
           }
         }

   {#virtual-agent-common-errors__ul_sln_jb1_n3c}
2. メディア API の使用 (同期モードで継続)。
{#virtual-agent-common-errors__ol_lwv_jzz_m3c}

## ユーザーリンクの問題 {#virtual-agent-common-errors__section_qry_grx_d3c}

仮想エージェント API は、すぐに利用可能な自動ユーザーリンクのみをサポートします。仮想エージェント APIでは、手動リンクはデフォルトで有効になっていません。  
**ユーザーリンクの前提条件:**

1. メッセージ認証は必須です。
   * `sys_cs_provider_application`でメッセージ認証がないと、ユーザーのリンクは機能しません。
   * メッセージ認証を適切に構成する必要があります。(認証のセクションを参照してください)。
   {#virtual-agent-common-errors__ul_w4q_qc1_n3c}
2. 必須の要求フィールド。
   * `userId` が存在し、一意である必要があります。
   * `emailId` が存在し、有効である必要があります。
   {#virtual-agent-common-errors__ul_t1h_fd1_n3c}
{#virtual-agent-common-errors__ol_a1g_pc1_n3c}  
**ユーザーレコード要件:**  
`emailId` は、以下の条件をすべて満たす`sys_user`レコードと一致する必要があります。

* `sys_user`テーブルにレコードが存在します。
* \[メール\] フィールドが完全に一致します。
* ユーザーはアクティブです。(`active=true`)
* ユーザーはロックアウトされていません。(`locked_out=false`)
* これらの条件に一致するユーザーレコードは 1 つだけです。

{#virtual-agent-common-errors__ul_j44_sd1_n3c}  
注:  
複数のユーザーが同じメールを持っている場合、リンクは失敗します。  
**自動リンク構成:**

1. プロバイダー構成を確認します。
   * `sys_cs_provider`テーブルに移動し、「**VA ボット間プロバイダー」**レコードを開きます。
   * {#virtual-agent-common-errors__table_s5q_ck1_n3c__entry__2}

     | フィールド | 予想値 |
     |-|-|
     | `automatic_link_enabled` | `true` |
     | `automatic_link_action` | `sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account` |
     | `link_account_enabled` | `true` |
     [表 : 3. 必須設定]

     {#virtual-agent-common-errors__table_s5q_ck1_n3c}
   {#virtual-agent-common-errors__ul_q4g_xj1_n3c}
2. プロバイダーユーザーマップを確認します。
   * `provider_user_map`テーブルに移動します。
   * フィルター基準: `active=false` AND `channel_user_id={userId from request}`。
   * 問題: `active=false` のレコードが存在する場合、ユーザーを自動的にリンクすることはできません。
   * 解決策:アドミニストレーターは、非アクティブなレコードを手動で削除し、リンク要求を再試行する必要があります。
   {#virtual-agent-common-errors__ul_mdx_dj1_n3c}
3. カスタマイズを確認します。
   * `sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account` スクリプトを実行してカスタマイズを確認します。
   * 一般的なカスタマイズの問題を確認します。
     * 自動リンクを防止するロジック
     * 追加の検証チェック
     * 変更されたフィールドマッピング
     {#virtual-agent-common-errors__ul_brc_bj1_n3c}
   {#virtual-agent-common-errors__ul_vt2_y31_n3c}
{#virtual-agent-common-errors__ol_lrk_4h1_n3c}  
**ユーザーリンクのトラブルシューティングチェックリスト:**  
* 構成：
  * メッセージ認証が存在し、アクティブです。
  * `userId` が要求に存在します。
  * `emailId` が要求に存在します。
  * `automatic_link_enabled = true`
  * `automatic_link_action` 正しいスクリプトを示しています。
  * `link_account_enabled = true`
  {#virtual-agent-common-errors__ul_xsz_gh1_n3c}
* ユーザーレコード:
  * ユーザーが `sys_user` に存在します。
  * メールが完全に一致します (大文字と小文字を区別)。
  * ユーザーはアクティブです。
  * ユーザーはロックアウトされていません。
  * 1 人のユーザーのみがメールと一致します。
  {#virtual-agent-common-errors__ul_q5g_231_n3c}
* プロバイダーユーザーマップ:
  * この `userId` に非アクティブなレコードはありません。
  * 重複するマッピングがないか確認します。
  {#virtual-agent-common-errors__ul_dt4_k31_n3c}
* カスタマイズ:
  * 自動リンクスクリプトの変更を確認します。
  * カスタマイズされている場合は、OOB スクリプトを使用してテストします。
  {#virtual-agent-common-errors__ul_wls_l31_n3c}
{#virtual-agent-common-errors__ul_xwb_d31_n3c}