Prerequisites

• Ensure the required ServiceNow Connector has been created with the necessary permissions. Refer to the ServiceNow Access Requirements Doc for details.
• Ensure access to your tenant’s MyMoveworks portal, including the Moveworks Setup and HTTP Connectors apps.
• Verify that the Virtual Agent API plugin is installed in the ServiceNow instance.
  If the Virtual Agent API plugin is not available to install, your instance does not have Virtual Agent and this integration will not work. Use URL-based handoff to ServiceNow AWA instead.

• Verify that the Agent Chat plugin is installed.
• Verify that Advanced Work Assignment (AWA) is set up for chat: a queue on the Chat service channel for each team, an assignment rule and eligibility pool for each queue, agents with Chat capacity, and a presence state that includes Chat. Set each queue’s condition with the condition builder; a queue without a condition matches no chats.
• For testing, ensure access to the Service Operations Workspace module within ServiceNow and that at least one agent is available in the queue being tested.

Configuration Steps

Step 1: Generate API Key

Navigate to the HTTP Connectors App within your MyMoveworks portal.

1. Click on Credentials and click Create
2. Enter a Credential Name
3. Choose API Key

4. Click Publish and save the API Key

Step 2: Configure Service Account Access

The service account requires the following access to support Message Brokering for Live Agent Chat.

Table Access

Grant READ access to the following tables. Moveworks reads them to check agent availability and to find the chat interaction:

• awa_agent_presence_capacity
• awa_agent_presence
• awa_agent_capacity
• awa_agent_channel_availability
• interaction

Roles

Assign the following roles so Moveworks can transfer attachments between an agent and a user:

• virtual_agent_admin
• interaction_agent

Step 3: Configure Outbound Endpoint

Step 4: Create the Token and Message Auth

Next, verify the token.

1. Navigate to {snow_url}/token_verification_list.do and create a new record by clicking new on the top right.

2. Enter a name, for example Moveworks Live Agent Message Brokering, and a token value. Save the token; you enter it in Moveworks Setup in Step 8. One token covers every domain and queue on the connector.

Next, configure the message auth

3. Navigate to {snow_url}/message_auth_list.do and create a new record.

4. Add the token verification you created in the previous step under Inbound message verification.
5. Although Outbound message creation is not yet supported by VA API, add the same token verification here too; the field is required.
6. Enter any Name and Provider. Both are required.

Finally, add the above message auth to VA Bot to Bot Provider Application

7. Switch to the Virtual Agent API application scope and navigate to {snow_url}/sys_cs_provider_application_list.do. You should see VA Bot to Bot Provider Application if the VA API application was successfully installed.
8. Open this record and under Message auth, add the message auth you configured in the previous instruction.

Step 5: Enable File Attachments

To let users send file attachments to the agent, allowlist the ServiceNow domain.

1. Navigate to {snow_url}/sys_cs_provider_application_list.do, you should be in the VIRTUAL AGENT API application scope to be able to make changes here.
2. Click on the gear icon at the top right and add trusted media domains to the list of selected columns.

3. Double click on Trusted media domains and add service-now.com (no quotes) as pictured below and save.

Step 6: Update Service Portal URL

Next, update the Service Portal url for KB and Ticket links.

1. Navigate to sys_properties_list.do and update the com.glide.cs.url_redirect.default.portal system property with the correct service portal name (if using a service portal other than the default /sp)

2. Navigate to sys_cs_portal_url_mapping_list.do and update the link for KBs if you use a custom url.

Step 7: Show Agent Names and Avatars

The ServiceNow Agent names and avatars setting controls whether an agent’s name and profile picture are shared with Moveworks. When it is off, ServiceNow sends only the agent’s ID with each agent message, so users see agent replies with no name or picture.

1. In ServiceNow, navigate to Conversational Interfaces > Settings > Agent Chat > User Chat Settings.
2. Turn on Agent names and avatars.

To show the agent’s name and profile picture on agent messages, also select Enable Agent Impersonation in Moveworks Setup. See Agent Name and Photo.

Each agent also needs a profile photo in ServiceNow. Moveworks fetches the photo URL without signing in to confirm it is an image, so the photo must be reachable from the internet. When an agent has no photo, or the photo cannot be fetched, the AI Assistant shows the Moveworks stock agent image instead. To show your AI Assistant’s image in that case, edit the ServiceNow connector in Moveworks Setup (Core Platform > Connectors > Built-in Connectors, the same connector you update in Step 8) and turn on Hide the default live agent stock image.

If agent replies show no agent name or picture while Enable Agent Impersonation is on, this setting is off in ServiceNow.

Step 8: Moveworks Setup Settings

The ServiceNow configuration is complete. In Moveworks Setup, configure these in order: Live Agent Handoff, Handoff Settings (it selects the Live Agent Handoff), Display Configurations (keyed by the Handoff Settings item), and the ServiceNow connector token. The Message Brokering page is optional; its defaults apply until you change them.

To route several teams to different queues on one ServiceNow instance, create one Live Agent Handoff and one Handoff Settings item per team, each with its own Metadata Domain. The Context Bender passes the domain to ServiceNow, and AWA routes on it.

Live Agent Handoff

Go to Ticketing Automation > Handoff > Live Agent Handoff and create an entry.

1. Handoff Identifier: a unique name, lowercase letters, digits, and underscores (for example snow_live_chat).

2. Configuration: select Agent Broker Handoff, then Snow Handoff Config.

3. Context Bender: the context variables sent to ServiceNow for queue routing. See Route Message Brokering Chats to ServiceNow Queues. A common starting point:

   {
     "language": "language OR null",
     "liveagent_optional_skills": "domain OR null"
   }

4. Show Agent Wait Time (optional): show users the estimated wait time ServiceNow returns.

5. App Inbound ID (optional, under Additional Controls): set only if Moveworks should use a provider application other than VA Bot to Bot, for example when ServiceNow Virtual Agent runs alongside Moveworks. See Message Brokering Settings.

6. Select Connector: the ServiceNow connector to use for live chat. Each Live Agent Handoff can use a different connector, for example ServiceNow for IT and Amazon Connect for HR.

7. Should File Ticket On Default (optional): file a ticket for every live agent request. The ticket is filed before Moveworks checks agent availability, so it is filed even when no agent is available.

8. Live Agent Session Timeout (optional): see Live Agent Session Timeout.

9. Set Enable Live Agent to true and save.

Handoff Settings

Go to Ticketing Automation > Handoff > Handoff Settings. If the team’s category (for example it or hr) doesn’t exist, add it under the categories on the same page. Then add an item for each team:

1. Item display key: a unique key for the menu item (for example it_live_chat). Display labels are keyed by this value.

2. Metadata Domain: the team’s domain, for example IT_DOMAIN or HR_DOMAIN. The Context Bender receives it without the suffix (IT, HR), and it sets the ticket domain.

3. Handoff Type: AGENT_HANDOFF. Under Deflection action, leave URL, email, and chat channel empty. You can select a form to collect more details before the chat starts; its fields are available to the Context Bender.

4. Live Agent Handoff: select the entry you created above. This field is required for AGENT_HANDOFF items; saving fails without it. Several items can select the same Live Agent Handoff.

5. Pretrigger Rule: when the item is offered. 1.0 shows it as a recommended option, 0.5 lists it under other help options, and 0 hides it. For example:

   IF (context.domain_candidates[0].domain == "IT_DOMAIN") THEN 1.0 ELSE 0.5

6. Category display keys: the categories the item appears in (for example it).

Display Configurations

Go to Chat Platforms > Display Configurations and, under Handoff, add entries keyed by the Item display key from Handoff Settings:

• handoff_category_names: the team name users see for a new category, keyed by category key, for example hr → HR.
• handoff_item_names: the option name users see, for example Live Chat.
• handoff_item_action_texts: the button label, for example Start agent chat. If the item has no action text, the button does not appear.

ServiceNow Connector

1. Go to Core Platform > Connectors > Built-in Connectors.
2. Edit the ServiceNow connector.
3. Enter the token from Step 4 in ServiceNow Virtual Agent API Token.
4. Click Save.

Validation

1. In ServiceNow, open Service Operations Workspace, find your inbox, and set yourself to Available. Your presence state must include the Chat channel.

   

2. In the AI Assistant (Teams, Slack, or web), start a conversation and click Get Help.

   

3. Under Which team is your request for?, choose the category from Handoff Settings (IT in this example).

   

4. Under What would you like to do?, choose the item name from Display Configurations (Live Chat in this example).

   

5. Fill out the Description and click Submit.

   

6. The chat request appears in your Service Operations Workspace inbox. Accept it to start the session.

7. Send a reply as the agent and confirm it appears in the AI Assistant. If it doesn’t, recheck Step 3.

8. In ServiceNow, open the chat’s interaction record and confirm its queue. Repeat with each team’s item.

Moveworks checks agent availability after the user submits. If no agent is available, the user sees “There are currently no agents available to handle your request” and is not added to a queue.

Troubleshoot “No Agents Available”

Next Steps

• To send different teams to different ServiceNow queues, see Route Message Brokering Chats to ServiceNow Queues.
• For every Message Brokering option, such as chat history, translation, attachments, and the session timeout, see Message Brokering Settings.