Optional Lab: Live Agent Handoff

Key Concepts

Live Agent Message Brokering allows Moveworks to act as a bridge between end users in their chat platform (Slack, Teams, etc.) and live agents in ServiceNow’s Service Operations Workspace. When the AI Assistant can’t resolve a user’s issue, it hands the conversation to a human agent.

• Message Brokering vs. Deep Link: Message brokering keeps the conversation in the user’s chat platform (Slack or Teams). The deep link approach sends users to a ServiceNow portal instead.
• Virtual Agent API: Moveworks uses ServiceNow’s Virtual Agent Bot-to-Bot API (/api/sn_va_as_service/bot/integration) to initiate conversations and relay messages between users and agents.
• Agent Availability: Moveworks checks the awa_agent_presence_capacity table to determine if agents are available before offering the handoff option.
• AWA Routing: Interactions must be routed through Advanced Work Assignment (AWA) queues. Without a properly configured queue, assignment rule, and eligibility pool, interactions will immediately close.

🛠️ 1: Walkthrough

1.1: Verify ServiceNow Prerequisites

Verify Virtual Agent API Plugin

1. In your ServiceNow instance, navigate to System Applications > All Available Applications > All

2. Search for Virtual Agent API and confirm it is installed

3. Search for Agent Chat plugin and confirm it is installed

Verify Update Set Configurations

Run the following script in Scripts - Background to confirm the update sets were applied correctly:

(function() {
    gs.print('=== Verifying VA API Config ===');
    var rest = new GlideRecord('sys_rest_message');
    rest.addQuery('name', 'VA Bot to Bot');
    rest.query();
    if (rest.next()) {
        gs.print('VA Bot to Bot endpoint: ' + rest.rest_endpoint);
    } else {
        gs.print('ERROR: VA Bot to Bot REST message not found');
    }
    var post = new GlideRecord('sys_rest_message_fn');
    post.addQuery('rest_message', rest.sys_id);
    post.addQuery('http_method', 'POST');
    post.query();
    if (post.next()) {
        gs.print('POST endpoint: ' + post.rest_endpoint);
    } else {
        gs.print('ERROR: POST method not found');
    }
    gs.print('\n=== Verifying AWA Config ===');
    var q = new GlideRecord('awa_queue');
    q.addQuery('name', 'Moveworks Labs Live Agent Chat Queue');
    q.query();
    if (q.next()) {
        gs.print('Queue: ' + q.name + ' | active=' + q.active + ' | channel=' + q.service_channel.getDisplayValue());
    } else {
        gs.print('Chat queue not found');
    }
    var ar = new GlideRecord('awa_assignment_rule');
    ar.addQuery('name', 'Chat - Most Capacity');
    ar.query();
    if (ar.next()) {
        gs.print('Assignment Rule: ' + ar.name + ' | active=' + ar.active);
    } else {
        gs.print('Assignment rule not found');
    }
    var ep = new GlideRecord('awa_eligibility_pool');
    ep.addQuery('display_name', 'Agent Chat Group : Chat - Most Capacity');
    ep.query();
    if (ep.next()) {
        gs.print('Eligibility Pool: ' + ep.display_name);
    } else {
        gs.print('ERROR: Eligibility pool not found');
    }
    gs.print('\n=== Verification Complete ===');
})();

Expected Output:

*** Script: === Verifying VA API Config ===
*** Script: VA Bot to Bot endpoint: https://api.moveworks.ai
*** Script: POST endpoint: https://api.moveworks.ai/rest/LiveAgentService/SnowSendMessageToUser
*** Script: 
=== Verifying AWA Config ===
*** Script: Queue: Moveworks Labs Live Agent Chat Queue | active=true | channel=Chat
*** Script: Assignment Rule: Chat - Most Capacity | active=undefined
*** Script: Eligibility Pool: Agent Chat Group : Chat - Most Capacity
*** Script: 
=== Verification Complete ===

1.2: Generate an API Key

1. In My Moveworks, open HTTP Connectors from the waffle menu.

2. Click Credentials, then Create.

3. Enter a Credential Name (for example, ServiceNow Live Agent API Key).

4. Choose API Key.

5. Click Publish and save the API key.

1.3: Set the Auth Profile Password in ServiceNow

The update set creates the auth profile but cannot transport the password. You must enter the API key you just generated.

1. In your ServiceNow instance, navigate to Outbound > REST Message

2. Click into VA Bot to Bot

3. Open the POST method record called postMessage (listed under HTTP Methods)

4. Go to the Authentication tab and open the auth profile Moveworks Live Agent Auth (click the “i” icon and select open record)

5. Enter the API key from Section 1.2 as the Password

6. Click Update

1.4: Set the Token Verification Password in ServiceNow

The update set creates the token verification record but cannot transport the password. You must set it manually.

1. Navigate to https://[your-instance].service-now.com/token_verification_list.do

2. Open the record named Moveworks Live Agent Message Brokering - IT

3. Set a secure password in Token. Save it; you need it in Section 1.7.

4. Click Update

1.5: Configure Live Agent Handoff

1. In Moveworks Setup, navigate to Handoff > Live Agent Handoff

2. Click Create to add a new configuration

3. Set Configuration to Agent Broker Handoff

4. Open the Live Agent Handoff dropdown and set the Handoff Identifier (e.g., agent_broker_instance_1)

5. Configure the Snow Handoff Config Context Bender with the following default payload:

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

6. Set the Integration ID to snow (the connector from Lab #3)

7. Set Enable Live Agent to TRUE

8. Click Run and enter your email to confirm the rule evaluates to TRUE for you.

1.6: Configure Smart Handoff

1. Navigate to Handoff > Handoff Settings
2. Expand Setup items for categories, then add a new Item Display Key with the following values (you may need to scroll to the bottom and click Add +)

3. Navigate to Display Configurations > Handoff
4. Scroll down within the Handoff configurations and ensure the Item display key (agent_broker_instance_1) is set under Map of actions for handoff items
5. Set the Value field to a user-friendly name (for example, Live Chat). Users see this name when they choose the handoff option. If the values are already set, continue to the next section.

1.7: Add the Token to the ServiceNow Connector

1. In Moveworks Setup, navigate to Connectors > Built-in Connectors

2. Find the snow connector and click Edit

3. Add the token password from Section 1.4 to the ServiceNow Virtual Agent API Token field

4. Click Save

1.8: Set Up Your Agent in ServiceNow

Run this script in Scripts - Background to configure the live agent user. Set userName to the ServiceNow user ID of the agent:

(function() {
    var userName = 'moveworks.admin';  // <-- Set your agent's user ID here
    var user = new GlideRecord('sys_user');
    user.addQuery('user_name', userName);
    user.query();
    if (!user.next()) { gs.print('User not found: ' + userName); return; }
    gs.print('Setting up agent: ' + user.getDisplayValue() + ' (' + userName + ')');
    // Add to Agent Chat Group
    var grp = new GlideRecord('sys_user_group');
    grp.addQuery('name', 'Agent Chat Group');
    grp.query();
    if (!grp.next()) { gs.print('ERROR: Agent Chat Group not found'); return; }
    var gm = new GlideRecord('sys_user_grmember');
    gm.addQuery('group', grp.sys_id);
    gm.addQuery('user', user.sys_id);
    gm.query();
    if (!gm.next()) {
        gm.newRecord();
        gm.group = grp.sys_id;
        gm.user = user.sys_id;
        gm.insert();
        gs.print('  Added to Agent Chat Group');
    } else {
        gs.print('  Already in Agent Chat Group');
    }
    // Grant awa_agent role
    var role = new GlideRecord('sys_user_role');
    role.addQuery('name', 'awa_agent');
    role.query();
    if (role.next()) {
        var hr = new GlideRecord('sys_user_has_role');
        hr.addQuery('user', user.sys_id);
        hr.addQuery('role', role.sys_id);
        hr.query();
        if (!hr.next()) {
            hr.newRecord();
            hr.user = user.sys_id;
            hr.role = role.sys_id;
            hr.insert();
            gs.print('  Granted awa_agent role');
        } else {
            gs.print('  Already has awa_agent role');
        }
    }
    // Create agent presence
    var ap = new GlideRecord('awa_agent_presence');
    ap.addQuery('agent', user.sys_id);
    ap.query();
    if (!ap.next()) {
        ap.newRecord();
        ap.agent = user.sys_id;
        var ps = new GlideRecord('awa_presence_state');
        ps.addQuery('name', 'Available');
        ps.query();
        if (ps.next()) ap.current_presence_state = ps.sys_id;
        ap.insert();
        gs.print('  Created agent presence (Available)');
    } else {
        gs.print('  Agent presence exists | state=' + ap.current_presence_state.getDisplayValue());
    }
    // Create Chat capacity
    var ch = new GlideRecord('awa_service_channel');
    ch.addQuery('name', 'Chat');
    ch.query();
    if (ch.next()) {
        var ac = new GlideRecord('awa_agent_capacity');
        ac.addQuery('user', user.sys_id);
        ac.addQuery('channel', ch.sys_id);
        ac.query();
        if (!ac.next()) {
            ac.newRecord();
            ac.user = user.sys_id;
            ac.channel = ch.sys_id;
            ac.applied_max_capacity = 4;
            ac.insert();
            gs.print('  Created Chat capacity (max=4)');
        } else {
            gs.print('  Chat capacity exists');
        }
        // Create Chat availability
        var aca = new GlideRecord('awa_agent_channel_availability');
        aca.addQuery('agent', user.sys_id);
        aca.addQuery('service_channel', ch.sys_id);
        aca.query();
        if (!aca.next()) {
            aca.newRecord();
            aca.agent = user.sys_id;
            aca.service_channel = ch.sys_id;
            aca.available = true;
            aca.insert();
            gs.print('  Created Chat availability (available=true)');
        } else {
            gs.print('  Chat availability exists');
        }
    }
    gs.print('\nDone! Set your status to Available in Service Operations Workspace.');
})();

Expected Output:

Impersonate your agent user (shown here as moveworks.admin).

After running the script, open Service Operations Workspace in ServiceNow and set your status to Available.

✅ 2: Verification & Testing

2.1: Test the Handoff

1. Open your AI Assistant

2. Start a conversation and click Get Help

3. Select Start agent chat

4. Verify the description and click Submit

5. The live agent session starts. Check Service Operations Workspace for the incoming chat.

2.2: Troubleshooting

🪞 3: Reflecting on This Configuration

Through this lab, you’ve learned the following:

• How to configure Moveworks Live Agent Handoff to broker chat sessions between users and ServiceNow agents
• How to connect Moveworks and ServiceNow using the Virtual Agent Bot-to-Bot API with proper authentication (API key + token verification)
• How to configure Smart Handoff rules to control when the live agent option appears based on domain context
• How to verify agent availability and troubleshoot common issues like missing AWA queue configuration, closed interactions, and authentication mismatches
• How the end-to-end flow works: availability check → interaction creation → AWA routing → agent assignment → message brokering

⚙️ 4: Configuration Details