---
sourceDocument: Brazil Conversational Interfaces
sourceDocumentLink: https://www.servicenow.com/docs/r/conversational-interfaces

 Release :

    - brazil

ft:locale :

    - en-US

ft:publication_title :

    - Brazil Conversational Interfaces

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# Common errors

# Common errors in Virtual Agent API {#ariaid-title1}

Release version: Brazil  
Updated September 10, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read  
This section describes some common errors in Virtual Agent API and how they can be resolved.

## Virtual Agent API structure validation {#virtual-agent-common-errors__section_r4n_y1z_m3c}

**Request structure:**  
Virtual Agent API expects the following JSON structure:

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

| Field | Required | Description |
|-|-|-|
| `requestId` | No | Pass-through variable returned in responses |
| `clientSessionId` | No | Pass-through session identifier |
| `userId` | Yes | Unique user identifier (mandatory) |
| `emailId` | No\* | User email for linking (\*required for user linking) |
| `action` | No | Optional action parameter |
| `message.text` | Yes | User message content (mandatory) |
| `message.typed` | No | `true` for search text, `false` for value selection |
| `contextVariables` | No | Optional context data |
| `history` | No | Bot conversation history (first request only) |
| `clientVariables` | No | Pass-through client variables |
[Table 1. Field definitions]

{#virtual-agent-common-errors__table_okj_mjz_m3c}  
Note:  
Only userId and message.text are mandatory fields in the request.

## File upload issues {#virtual-agent-common-errors__section_ggr_ybz_m3c}

Virtual Agent API supports two file upload modes, such as Synchronous and Asynchronous.

**File upload request structure:**  

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

| Field | Required | Description |
|-|-|-|
| `contentType` | Yes | MIME type (e.g., `video/mp4`, `image/png`) |
| `fileName` | Yes | Name of the file with extension |
| `url` | Yes | Accessible URL to download the file |
| `clientAttachmentId` | No | Unique identifier for tracking |
| `headers` | No | Authentication headers for file download |
[Table 2. Field definitions]

{#virtual-agent-common-errors__table_l44_hsz_m3c}  
**File upload in synchronous mode:**  
To upload a file in synchronous mode, follow the below steps:

1. Upload the file by using Media API. For more information, see [CCCIF Media Resource API](https://www.servicenow.com/docs/access?context=cccif-api&version=brazil&pubname=brazil-api-reference&ft:locale=en-US).  
   Media API returns a url. An example of the response is:

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

2. Use the media url in Virtual Agent API request. A JSON example is:

       {
         "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}  
**File upload in asynchronous mode:**  
You can upload a file in asynchronous mode in two ways:

1. Use the file url in the Virtual Agent API request.
   * Direct file url:

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

   * Protected file 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. Using the Media API (as followed in synchronous mode).
{#virtual-agent-common-errors__ol_lwv_jzz_m3c}

## User linking issues {#virtual-agent-common-errors__section_qry_grx_d3c}

Virtual Agent API supports automatic user linking only out-of-the-box. Manual linking is not enabled by default in Virtual Agent API.  
**Prerequisites for user linking:**

1. Message Auth is mandatory.
   * Without message auth in `sys_cs_provider_application`, user linking doesn't work.
   * You must configure Message auth properly. (See the authentication section.)
   {#virtual-agent-common-errors__ul_w4q_qc1_n3c}
2. Required request fields.
   * `userId` must be present and unique.
   * `emailId` must be present and valid.
   {#virtual-agent-common-errors__ul_t1h_fd1_n3c}
{#virtual-agent-common-errors__ol_a1g_pc1_n3c}  
**User record requirements:**  
The `emailId` must match a `sys_user` record that meets all of the below conditions:

* Record exists in the `sys_user` table.
* Email field matches exactly.
* User is active. (`active=true`)
* User is not locked out. (`locked_out=false`)
* Only one user record matches these conditions.

{#virtual-agent-common-errors__ul_j44_sd1_n3c}  
Note:  
If multiple users have the same email, linking fails.  
**Auto linking configuration:**

1. Verify the provider configuration.
   * Navigate to the `sys_cs_provider` table and open the **"VA Bot to Bot Provider"** record.
   * {#virtual-agent-common-errors__table_s5q_ck1_n3c__entry__2}

     | Field | Expected Value |
     |-|-|
     | `automatic_link_enabled` | `true` |
     | `automatic_link_action` | `sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account` |
     | `link_account_enabled` | `true` |
     [Table 3. Required setting]

     {#virtual-agent-common-errors__table_s5q_ck1_n3c}
   {#virtual-agent-common-errors__ul_q4g_xj1_n3c}
2. Check the provider user map.
   * Navigate to the `provider_user_map` table.
   * Filter by: `active=false` AND `channel_user_id={userId from request}`.
   * Issue: If record exists with `active=false`, the user cannot be linked automatically.
   * Solution: Admin must manually delete the inactive record and retry the linking request.
   {#virtual-agent-common-errors__ul_mdx_dj1_n3c}
3. Check for customizations.
   * Review customizations by running the `sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account` script.
   * Check for the common customization issues:
     * Logic preventing automatic linking
     * Additional validation checks
     * Modified field mappings
     {#virtual-agent-common-errors__ul_brc_bj1_n3c}
   {#virtual-agent-common-errors__ul_vt2_y31_n3c}
{#virtual-agent-common-errors__ol_lrk_4h1_n3c}  
**User linking troubleshooting checklist:**  
* Configuration:
  * Message auth exists and is active.
  * `userId` is present in request.
  * `emailId` is present in request.
  * `automatic_link_enabled = true`
  * `automatic_link_action` points to correct script.
  * `link_account_enabled = true`
  {#virtual-agent-common-errors__ul_xsz_gh1_n3c}
* User record:
  * User exists in `sys_user`.
  * Email matches exactly (case-sensitive).
  * User is active.
  * User is not locked out.
  * Only one user matches the email.
  {#virtual-agent-common-errors__ul_q5g_231_n3c}
* Provider user map:
  * No inactive records for this `userId`.
  * Check for duplicate mappings.
  {#virtual-agent-common-errors__ul_dt4_k31_n3c}
* Customizations:
  * Review auto-link script for modifications.
  * Test with OOB script if customized.
  {#virtual-agent-common-errors__ul_wls_l31_n3c}
{#virtual-agent-common-errors__ul_xwb_d31_n3c}