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 2: Enable the ServiceNow Agent
• Step 3: Install Required Plugins
• Step 4: Assign Agent Roles to the Consumer Service Support Group
• Step 5: Update the Webhook Endpoint and Enable the Integration
• 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

   

   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 to generate a 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.

   This option is enabled only when multiple agents are configured.

7. Click Configure to map channels.

   

8. Select channels to map to the ServiceNow agent.

   

9. Click Done, then Save.

10. Publish the app. See 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.

   

3. Search and install the following plugins:

   • Omni-experience Standard Feature Set

     

   • Advanced Work Assignment

     

   • Customer Service Management

     

   • Glide Virtual Agent

     

   • 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.

   

3. Select the Consumer Service Support group.

   

4. Select the Roles tab and click Edit.

   

5. Search for and assign the awa_agent and agent_workspace_user roles to the Consumer Service Support group. Click Save.

   

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

   

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

   

8. Click Update on the group details screen.

   

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.

   

3. Select VABot to Bot from the list.

   

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.

   

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

   

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.

   

3. Click Talk to Bot and enter Help.

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

   

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

   

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

   

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

   

8. When the user initiates chat, the conversation transfers to the ServiceNow agent and the connection is 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.

2. Before the agent transfer node, set meta info using a Script node:

   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.

   
   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.

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.

   

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

   

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

  

• ServiceNow: 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.

   
   This feature supports only Utah and Vancouver versions.

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.