仮想エージェント APIの一般的なエラー

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

仮想エージェント API 構造の検証

要求構造:

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

{
  "requestId": "any-unique-request-id",
  "clientSessionId": "any-unique-session-id",
  "userId": "any-unique-user-id",
  "emailId": "[e-mail]",
  "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"
  }
}

表 : 1. フィールド定義

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

注:

要求では userId と message.text のみが必須フィールドです。

ファイルアップロードの問題

仮想エージェント 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
    }
}

表 : 2. フィールド定義

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

同期モードでのファイルアップロード:

同期モードでファイルをアップロードするには、次の手順に従います。

1. メディア API を使用してファイルをアップロードします。詳細については、「CCCIF Media Resource API」を参照してください。
   メディア 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
     }
   }

非同期モードでのファイルアップロード:

非同期モードでファイルをアップロードするには、次の 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
       }
     }

2. メディア API の使用 (同期モードで継続)。

ユーザーリンクの問題

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

ユーザーリンクの前提条件:

1. メッセージ認証は必須です。
   • sys_cs_provider_applicationでメッセージ認証がないと、ユーザーのリンクは機能しません。
   • メッセージ認証を適切に構成する必要があります。(認証のセクションを参照してください)。
2. 必須の要求フィールド。
   • userId が存在し、一意である必要があります。
   • emailId が存在し、有効である必要があります。

ユーザーレコード要件:

emailId は、以下の条件をすべて満たすsys_userレコードと一致する必要があります。

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

注:

複数のユーザーが同じメールを持っている場合、リンクは失敗します。

自動リンク構成:

1. プロバイダー構成を確認します。
   • sys_cs_providerテーブルに移動し、「VA ボット間プロバイダー」レコードを開きます。

   • 表 : 3. 必須設定

     フィールド	予想値
     automatic_link_enabled	true
     automatic_link_action	sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account
     link_account_enabled	true

2. プロバイダーユーザーマップを確認します。
   • provider_user_mapテーブルに移動します。
   • フィルター基準: active=false AND channel_user_id={userId from request}。
   • 問題: active=false のレコードが存在する場合、ユーザーを自動的にリンクすることはできません。
   • 解決策:アドミニストレーターは、非アクティブなレコードを手動で削除し、リンク要求を再試行する必要があります。
3. カスタマイズを確認します。
   • sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account スクリプトを実行してカスタマイズを確認します。
   • 一般的なカスタマイズの問題を確認します。
     • 自動リンクを防止するロジック
     • 追加の検証チェック
     • 変更されたフィールドマッピング

ユーザーリンクのトラブルシューティングチェックリスト:

• 構成：
  • メッセージ認証が存在し、アクティブです。
  • userId が要求に存在します。
  • emailId が要求に存在します。
  • automatic_link_enabled = true
  • automatic_link_action 正しいスクリプトを示しています。
  • link_account_enabled = true
• ユーザーレコード:
  • ユーザーが sys_user に存在します。
  • メールが完全に一致します (大文字と小文字を区別)。
  • ユーザーはアクティブです。
  • ユーザーはロックアウトされていません。
  • 1 人のユーザーのみがメールと一致します。
• プロバイダーユーザーマップ:
  • この userId に非アクティブなレコードはありません。
  • 重複するマッピングがないか確認します。
• カスタマイズ:
  • 自動リンクスクリプトの変更を確認します。
  • カスタマイズされている場合は、OOB スクリプトを使用してテストします。