> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-ai-for-process-dev.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring the ServiceNow Agent - Utah and Higher Versions

The ServiceNow Agent integration allows you to hand off AI Agent conversations to live agents on ServiceNow. This guide covers configuration for **Utah**, **Vancouver**, and higher versions.

***

## Configuration Steps

* [Step 1: Retrieve the ServiceNow Instance URL](#step-1-retrieve-the-servicenow-instance-url)
* [Step 2: Enable the ServiceNow Agent](#step-2-enable-the-servicenow-agent)
* [Step 3: Install Required Plugins](#step-3-install-the-required-plugins)
* [Step 4: Assign Agent Roles to the Consumer Service Support Group](#step-4-assign-agent-roles-to-the-consumer-service-support-group)
* [Step 5: Update the Webhook Endpoint and Enable the Integration](#step-5-update-the-webhook-endpoint-and-enable-the-integration)
* [Step 6: Testing Configuration](#step-6-testing-configuration)

***

### Step 1: Retrieve the ServiceNow Instance URL

1. Log in to your ServiceNow account with admin credentials. The URL follows the format: `https://devXXX67.service-now.com`.
2. Copy the Instance URL for use in Step 2.

### Step 2: Enable the ServiceNow Agent

1. Log in to the Platform.

2. Select the AI Agent to configure.

3. Navigate to **App Settings > Integrations > Agent Transfer** and click **ServiceNow**.

4. On the **Configurations** tab, choose an authentication method:

   **Option 1: Basic Auth**

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img2.png" alt="Basic Auth" />

   1. Select **Agent Chat (Supported for Utah and higher versions)**.
   2. Select **Basic Auth**.
   3. Enter:

      | Field        | Description                                                        |
      | ------------ | ------------------------------------------------------------------ |
      | Instance URL | ServiceNow instance URL (e.g., `https://devXXX67.service-now.com`) |
      | User Name    | ServiceNow account username                                        |
      | Password     | ServiceNow account password                                        |
      | Queue ID     | Unique queue identification number                                 |
      | Webhook URL  | Web URL for custom application function callbacks                  |

   **Option 2: OAuth with Refresh Token**

   Follow [this ServiceNow documentation](https://support.servicenow.com/kb?id=kb_article_view\&sysparm_article=KB0778194) to generate a refresh token.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img3.png" alt="OAuth with Refresh Token" />

   1. Select **Agent Chat (Supported for Utah and higher versions)**.
   2. Select **OAuth with Refresh Token**.
   3. Enter:

      | Field         | Description                                       |
      | ------------- | ------------------------------------------------- |
      | Instance URL  | ServiceNow instance URL                           |
      | Client ID     | Client ID from your ServiceNow application        |
      | Client Secret | Client secret from your ServiceNow application    |
      | Refresh Token | Refresh token generated per the documentation     |
      | Webhook URL   | Web URL for custom application function callbacks |

5. Click **Authorize** to authenticate.

6. To make ServiceNow the default agent, enable **Default Agent System for all AI Agent channels**.

   <Note>This option is enabled only when multiple agents are configured.</Note>

7. Click **Configure** to map channels.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img4.png" alt="Customize channel mapping" />

8. Select channels to map to the ServiceNow agent.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img5.png" alt="Map channels with ServiceNow agent" />

9. Click **Done**, then **Save**.

10. Publish the app. See [Publishing your App](/ai-for-service/deployment/publishing-app).

### Step 3: Install the Required Plugins

1. Log in to the ServiceNow Developer instance with admin credentials.

2. Navigate to **System Definition > Plugins** from the left menu.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img6.png" alt="System Definition - Plugins" />

3. Search and install the following plugins:

   * **Omni-experience Standard Feature Set**

     <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img7.png" alt="Omni-experience Standard Feature Set" />

   * **Advanced Work Assignment**

     <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img8.png" alt="Advanced Work Assignment" />

   * **Customer Service Management**

     <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img9.png" alt="Customer Service Management" />

   * **Glide Virtual Agent**

     <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img10.png" alt="Glide Virtual Agent" />

   * **Virtual Agent API**

     <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img11.png" alt="Virtual Agent API" />

4. Verify all plugins are installed with required permissions.

### Step 4: Assign Agent Roles to the Consumer Service Support Group

1. Log in to the ServiceNow Developer instance with admin credentials.

2. Navigate to **Advanced Work Assignment > Management > Groups**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img12.png" alt="Groups" />

3. Select the **Consumer Service Support** group.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img13.png" alt="Group details" />

4. Select the **Roles** tab and click **Edit**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img14.png" alt="Navigate to Roles screen" />

5. Search for and assign the **awa\_agent** and **agent\_workspace\_user** roles to the Consumer Service Support group. Click **Save**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img15.png" alt="Assign roles" />

6. Go back to the group details screen, select **Group Members**, click **Edit**, and navigate to **Edit Members**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img16.png" alt="Edit members" />

7. Search for and assign the required user (e.g., `Abel Tuter`) to the Consumer Service Support group. Click **Save**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img17.png" alt="Assign user to group" />

8. Click **Update** on the group details screen.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img18.png" alt="Group details - Update" />

### Step 5: Update the Webhook Endpoint and Enable the Integration

1. Log in to the ServiceNow instance.

2. Navigate to **System Web Services > Outbound > REST messages**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img19.png" alt="REST messages" />

3. Select **VABot to Bot** from the list.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img20.png" alt="VABot to Bot" />

4. Copy the **Webhook URL** from the **Configuration** tab of the ServiceNow Agent page.

5. Paste it into the **EndPoint** field on the VABot to Bot edit screen.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img21.png" alt="Endpoint - Webhook URL" />

6. Scroll down, select **HTTP methods**, update the Webhook URL for **postMessage**, and click **Update**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img22.png" alt="HTTP Method - postMessage" />

7. Click **Save** to enable the integration.

### Step 6: Testing Configuration

1. Open the AI Agent with ServiceNow enabled.

2. Create an Agent Transfer Node task (e.g., `Platform Agent` task with a `UserAgent` node). See [Agent Transfer Node](/ai-for-service/automation/dialogs/node-types/agent-transfer-node).

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img23.png" alt="Agent Transfer Node task" />

3. Click **Talk to Bot** and enter **Help**.

4. Log in to ServiceNow, go to **Profile**, and select **Impersonate User**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img24.png" alt="Impersonate user" />

5. Select the username created (e.g., `Abel Tuter`).

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img25.png" alt="Enter username" />

6. Navigate to **Workspace Experience > Workspaces > Agent Workspace Home**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img26.png" alt="Agent Workspace Home" />

7. In the Agent Workspace, select **Inbox** and set **Status** to **Available**.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img27.png" alt="Status - Available" />

8. When the user initiates chat, the conversation transfers to the ServiceNow agent and the connection is established.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img28.png" alt="Connection established" />

***

## Additional Capabilities

### Pass User Information to ServiceNow

By default, users appear as Guest in ServiceNow. Use the `ServiceNowMetaData` object with `agentUtils.setMetaInfo` to pass user identity information.

**Steps:**

1. Configure Message Authentication for inbound communication in your ServiceNow instance — see [ServiceNow Message Authentication setup](https://docs.servicenow.com/bundle/vancouver-servicenow-platform/page/administer/virtual-agent/task/set-up-message-auth-va-api.html).
2. Before the agent transfer node, set meta info using a Script node:

   ```javascript  theme={null}
   let metaData = {
     "payloadFields": {
       "userId": context.entities.UserID,    // ServiceNow user ID (dynamic or static)
       "emailId": context.entities.UserEmail // ServiceNow user email (dynamic or static)
     },
     "headerFields": {
       "token": "Token_generated_in_ServiceNow_Instance"
     }
   }

   agentUtils.setMetaInfo("ServiceNowMetaData", JSON.stringify(metaData))
   ```

   The app can collect `UserID` and `UserEmail` via entity nodes.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img29.png" alt="Entity nodes for user info" />

   <Note>Context does not include user ID or email by default. Capture required details explicitly. If `ServiceNowMetaData` is not defined, values are not shared with ServiceNow.</Note>

### Route Messages to Agent Groups by `streamId`

The platform sends `streamId` as a context variable in the ServiceNow request payload. Use it to route work items to different agent groups via a Work Item Routing Condition.

**Steps:**

1. In **Conversational Interfaces Home**, create a new context variable named `streamId`.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img30.png" alt="New context variable streamId" />

2. Define a Work item routing condition in the Queue using the `streamId` context variable.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img31.png" alt="Work item routing condition" />

3. Configure the routing condition in every queue that handles these work items. If queue 1 has a `streamId` condition but queue 2 does not, both queues will qualify. Define the condition in all relevant queues.

Reference:

* [ServiceNow: Create a work item queue](https://docs.servicenow.com/bundle/tokyo-servicenow-platform/page/administer/advanced-work-assignment/task/awa-create-queue.html)

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img32.png" alt="Create a work item queue" />

* [ServiceNow: Virtual Agent Bot Integration API](https://developer.servicenow.com/dev.do#!/reference/api/tokyo/rest/bot-api)

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/configuring-the-servicenow-agent-utah-and-vancouver-img33.png" alt="Virtual Agent Bot Integration API" />

### Enable Attachment Sharing with Live Agents

1. Log in to ServiceNow with admin credentials.
2. Navigate to **System Properties > sys\_cs\_provider\_application.list > Configure > Form Layout**.
3. In the **Trusted Media Domains** field, enter the domain for sending and receiving attachments.

   <img src="https://mintlify.s3.us-west-1.amazonaws.com/koreai-ai-for-process-dev/ai-for-service/integrations/agents/images/sn-at.png" alt="Attachment Sharing" />

   <Note>This feature supports only Utah and Vancouver versions.</Note>

### Agent Transfer Status

The platform records agent transfer status in Debug Logs and Analytics, enabling tracking and troubleshooting of transfer-related issues.

### Failed Agent Transfer Notification

When a ServiceNow agent transfer fails due to agent unavailability, users see a default non-editable message:

*No agents are available to handle your request. Please try again later.*


Built with [Mintlify](https://mintlify.com).