Configuring the ServiceNow Agent – Tokyo and Lower Versions

The ServiceNow Agent integration allows you to hand off AI Agent conversations to live agents on ServiceNow. This guide covers configuration for Tokyo and lower versions.

---

Configuration Steps

• Step 1: Retrieve the ServiceNow Instance URL
• Step 2: Create a New Queue
• Step 3: Enable the ServiceNow Agent
• Step 4: Switch to UI16 Theme
• Step 5: Install Required Plugins
• Step 6: Create a User with agent_admin Role
• Step 7: Create a Group and Add the User
• Step 8: Define the Host URL in the REST Message
• Step 9: Define Outbound REST Message Requests
• Step 10: Define Outbound REST Business Rules
• Step 11: Testing Configuration

---

Step 1: Retrieve the ServiceNow Instance URL

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

Step 2: Create a New Queue

1. Log in to your ServiceNow account.

2. Navigate to Connect > Support Administration > Queues and click New.

   

3. Enter the queue Name and select Consumer Service Support in the Assignment group field.

   

4. In the Chat Queue Entries section, click New and assign a user.

   

5. Click Submit to save the queue entry, then Submit again to save the queue.

6. Copy the Queue ID.

   

Step 3: 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 Connect Support (Supported for Tokyo and lower 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	Queue ID from Step 2
      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 Connect Support (Supported for Tokyo and lower 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 app 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 4: Switch to UI16 Theme

1. Log in to ServiceNow with admin credentials.

2. Navigate to System Properties and click New.

   

3. Enter the property glide.ui.polaris.on_off_user_pref_enabled, set type to true|false, and click Submit.

   
   This property allows toggling between “Next experience and UI16” and classic experience.

4. Click the System Admin profile and select Preferences.

   

5. Enable Turn off Next experience.

   

6. The view switches to UI16 theme.

   

Step 5: 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 for and install the Consumer Service Portal plugin.

   

4. After installation, the Connect support menu item appears in the left navigation.

   

Step 6: Create a User with agent_admin Role

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

2. Navigate to User Administration > Users > New.

   

3. Fill in the user details and click Submit.

   

4. Select the Roles tab and click Edit.

   

5. Search for and add the agent_admin role to the user.

   

6. Click Save.

Step 7: Create a Group and Add the User

1. Navigate to User Administration > Groups.

   

2. Click New.

   

3. Fill in the group details and click Submit.

   

4. Edit the group, scroll to the Group Members tab, and click Edit.

   

5. Select the agent from Step 6 and add them to the group.

   

6. Click Save.

Step 8: Define the Host URL in the REST Message

1. Log in to your ServiceNow account.

2. Navigate to System Web Services > Outbound > REST Messages from the left menu.

3. Click New to create a new REST Message.

   

4. Copy the Webhook URL from the Platform AI Agent configuration page and paste it into the Endpoint URL field.

   

5. Click Save.

Step 9: Define Outbound REST Message Requests

1. Navigate to System Web Services > Outbound > REST Messages.

2. Select the REST Message for Platform agent integrations (e.g., Platform – Agent Integrations).

   

3. Enter the API details including the endpoint URL (Callback URL from the Configurations page) and HTTP method.

   This endpoint is how ServiceNow sends agent messages to the user.

4. Click the HTTP Request tab and select Add New Row.

   

5. Add:

   • HTTP Header: Content-Type: application/json
   • Method: POST — paste the Webhook URL in the Endpoint field.
   

6. Click Update.

Step 10: Define Outbound REST Business Rules

1. Navigate to System Definition > Business Rules.

2. Click New.

   

3. Enter the following details:

   • Name: Enter a name.
   • Table: Select live_message.
   • Enable Active and Advanced checkboxes.
   • In the When to run tab: set When to after and select Insert.
   • Add Filter conditions: execute if created by is not AI Agent_interface.
   

4. On the Advanced tab, add the following code and click Submit:

   var request;
   request = new sn_ws.RESTMessageV2('Platform - Agent Integrations', 'Platform - Agent Integrations');
   request.setRequestBody("{\"group\":\""+current.group+"\","formatted_message\":\""+GlideStringUtil.escapeForHomePage(current.formatted_message)+"\","sys_created_by\":\""+current.sys_created_by+"\",\"last_message\":\""+current.last_message+"\","sys_id\":\""+current.sys_id+"\"}");
   request.setRequestHeader("Content-Type", "application/json");
   var response = request.execute();
   
   This code is optional. Use it if you encounter issues during execution. This business rule executes the API configured in the REST Message.

Step 11: Testing Configuration

1. Open the AI Agent with ServiceNow enabled.

2. Create an Agent Transfer Node task (e.g., Platform Agent 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

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