Hand off conversations to ServiceNow

Connect ServiceNow Virtual Agent to a Copilot Studio agent and configure handoff to a human agent in ServiceNow. The integration uses an Azure Function to relay Direct Line activities and a custom ServiceNow transformer to detect handoff events.

Overview

The integration between Copilot Studio and ServiceNow requires the following high-level configuration steps:

1. Deploy an Azure Function as a relay to Direct Line.

2. Configure Bot Interconnect in ServiceNow.

3. Map topics between ServiceNow Virtual Agent and Copilot Studio.

4. Extend DirectLinePrimaryBotIntegrationInboundTransformer.

5. Configure handoff in Copilot Studio.

Prerequisites

Before you begin, ensure you have the following prerequisites:

• An active ServiceNow account with ServiceNow Virtual Agent and ServiceNow Bot Interconnect turned on. You need ServiceNow Yokohama or later.
• A Copilot Studio agent configured with No authentication. This setting applies to end-user sign-in; the server-to-server relay uses a Direct Line secret to authorize channel access.
• Admin access to ServiceNow.

Create an Azure Function as a relay to Direct Line

The Azure Function acts as a relay so ServiceNow Bot Interconnect can retrieve activities, such as messages and events, from an ongoing conversation with a Copilot Studio agent.

Sample request sent by ServiceNow Bot Interconnect

GET /api/relayToDirectLine HTTP/1.1
Host: your-function-app.azurewebsites.net
Authorization: Bearer YOUR_DIRECT_LINE_SECRET_HERE
ConversationId: abc123def456-conversation-id
Watermark: 5
WaitTime: 3000

Sample response from the Azure Function

{
    "activities": [
        {
            "type": "message",
            "id": "0000001",
            "timestamp": "2025-07-13T13:46:43.6095506Z",
            "text": "Hello, I'm a Copilot Studio Agent.",
            "from": {
                "id": "bot-id",
                "name": "Copilot Studio Agent",
                "role": "bot"
            },
            "conversation": {
                "id": "wwjmISGzmd3FzMEAgotiJ-us"
            }
        },
        {
            "type": "message",
            "id": "0000002",
            "timestamp": "2025-07-13T13:46:45.0000000Z",
            "text": "speak to a live agent",
            "from": {
                "id": "user-id",
                "name": "User",
                "role": "user"
            },
            "conversation": {
                "id": "wwjmISGzmd3FzMEAgotiJ-us"
            }
        },
        {
            "type": "event",
            "id": "0000006",
            "timestamp": "2025-07-13T13:46:51.2854808Z",
            "name": "handoff.initiate",
            "value": {
                "va_LastPhrase": "speak to a live agent",
                "va_Topics": ["Escalate"]
            }
        }
    ],
    "watermark": "10"
}

Create and deploy the function

You can create and deploy either the v3 Azure Function described in the ServiceNow documentation or the v4 Azure Function available in the Copilot Studio GitHub repository.

Option 1: Deploy the v3 Azure Function

To create and deploy the v3 Azure Function, follow the steps outlined in the ServiceNow documentation:

1. Create a JavaScript function in Microsoft Azure using Visual Studio Code.

2. Deploy the function to Azure and retrieve the function URL for use in ServiceNow Bot Interconnect.

Option 2: Deploy the v4 Azure Function

Alternatively, you can use the v4 Azure Function available in the Copilot Studio GitHub repository:

1. Clone the Copilot Studio Samples repository. Open the provided project under contact-center/servicenow/DirectLineAzureFunction in Visual Studio Code.

2. Follow the project's setup instructions. Create a function app in Azure and deploy the provided relay project. Don't replace the relay with a new template-generated HTTP function. Learn more in Deploy project files.

3. After deployment, copy the relay HTTP function's URL for use in ServiceNow Bot Interconnect. Use the function endpoint, not the function app's base URL. Learn more in Get the URL of an HTTP triggered function in Azure.

Configure Bot Interconnect in ServiceNow

1. Obtain your agent's Direct Line secret.

2. Add the Direct Line secret key to your Virtual Agent Bot Interconnect instance.

Map topics between ServiceNow Virtual Agent and Copilot Studio

1. Create a Virtual Agent Bot Interconnect shell topic to call Copilot Studio topics.

Extend DirectLinePrimaryBotIntegrationInboundTransformer

The built-in DirectLinePrimaryBotIntegrationInboundTransformer doesn't parse the Copilot Studio handoff.initiate event when the conversation needs to be handed over to a live agent.

The shouldConnectToAgent function in DirectLinePrimaryBotIntegrationInboundTransformer always returns false:

shouldConnectToAgent: function(response) {
    return false;
}

To properly handle handoff events, create a custom transformer that extends the default transformer and detects the handoff.initiate event.

shouldConnectToAgent: function() {
        var response = this._response || {};
        var activities = response.activities || [];

        var handoffDetected = activities.some(function(activity) {
            return activity.type === "event" && activity.name === "handoff.initiate";
        });

        if (handoffDetected) {
            return true;
        }
        return false;
    }

Create the custom transformer

1. In ServiceNow, switch to the Bot Interconnect application scope.

   1. Select the globe icon in the upper right corner.

   2. Select Bot Interconnect from the application list.

2. Create a new Script Include.

   1. Go to System Definition > Script Includes.

   2. Select New.

   3. Configure the following settings:

   • Name: CustomDirectLineInboundTransformer
   • API Name: sn_va_bot_ic.CustomDirectLineInboundTransformer (autogenerated)
   • Application: Bot Interconnect (autoselected)
   • Accessible from: This application scope only
   • Active: Selected

3. Replace the default script content with the custom transformer code from the Copilot Studio Samples repository.

4. Select Submit to save the Script Include.

Update the Bot Interconnect configuration

1. Go to Workflow Studio.

   1. In ServiceNow, go to Workflow Studio.

   2. Under Actions, find Direct Line Primary Bot Integration Inbound Transformer.

2. Change the transformer action.

   1. Open the Direct Line Primary Bot Integration Inbound Transformer action.

   2. In the script editor, comment out the default transformer and replace it with a call to your custom transformer.

   (function execute(inputs, outputs) {
      var clientVariables = JSON.parse(inputs['client_variables']);
      var response = JSON.parse(inputs['response']);
      //set client variables
      response.clientVariables = clientVariables;
   
      //var transformedResponse = new sn_va_bot_ic.DirectLinePrimaryBotIntegrationInboundTransformer(response).transformResponse();
      var transformedResponse = new sn_va_bot_ic.CustomDirectLineInboundTransformer(response).transformResponse();
   
      outputs['transformed_response'] = transformedResponse;
    })(inputs, outputs);
   

3. Save the changes to the action and publish.

Configure handoff

To configure handoff to a human agent in ServiceNow, add a Transfer conversation node to your agent's Escalate topic.

1. In Copilot Studio, open your agent and go to Topics > System > Escalate.

2. Select + (Add node) > Topic management > Transfer conversation.

3. Save your topic and publish your agent.

The Transfer conversation node sends a handoff.initiate event that ServiceNow's custom transformer detects and processes.

Sample Escalate topic YAML

You can also import the following YAML configuration for a complete Escalate topic with transfer capabilities:

kind: AdaptiveDialog
startBehavior: CancelOtherTopics
beginDialog:
  kind: OnEscalate
  id: main
  intent:
    displayName: Escalate
    includeInOnSelectIntent: false
    triggerQueries:
      - Talk to agent
      - Talk to a person
      - Talk to someone
      - Call back
      - Call customer service
      - Call me please
      - Call support
      - Call technical support
      - Can an agent call me
      - Can I call
      - Can I get in touch with someone else
      - Can I get real agent support
      - Can I get transferred to a person to call
      - Can I have a call in number Or can I be called
      - Can I have a representative call me
      - Can I schedule a call
      - Can I speak to a representative
      - Can I talk to a human
      - Can I talk to a human assistant
      - Can someone call me
      - Chat with a human
      - Chat with a representative
      - Chat with agent
      - Chat with someone please
      - Connect me to a live agent
      - Connect me to a person
      - Could some one contact me by phone
      - Customer agent
      - Customer representative
      - Customer service
      - I need a manager to contact me
      - I need customer service
      - I need help from a person
      - I need to speak with a live agent
      - I need to talk to a specialist please
      - I want to talk to customer service
      - I want to proceed with live support
      - I want to speak with a consultant
      - I want to speak with a live tech
      - I would like to speak with an associate
      - I would like to talk to a technician
      - Talk with tech support member

  actions:
    - kind: TransferConversationV2
      id: transferConversationV2_3JXrI7
      transferType:
        kind: TransferToAgent
        messageToAgent:
        context:
          kind: AutomaticTransferContext

Troubleshooting

If you encounter errors in the ServiceNow Virtual Agent chat widget, follow these troubleshooting steps:

Check Azure Function logs

1. Verify that your Azure Function is working correctly and isn't returning errors.

2. View real-time logs by using Azure Functions streaming logs.

3. Check Application Insights for detailed telemetry and error information.

Turn on ServiceNow debugging

Use ServiceNow's built-in debugging tools to trace the execution flow:

1. Turn on Script Tracer in ServiceNow.

2. Repeat the action that's causing the error.

3. Review the trace logs to identify where the problem occurs.

Monitor Copilot Studio invocations

Ensure your Copilot Studio agent is invoked correctly:

1. Connect your Copilot Studio agent to Application Insights.

2. Monitor the telemetry to confirm the agent is receiving requests from ServiceNow.

3. Check for any errors or unexpected behavior in the agent's execution.

Common problems and solutions

• Handoff doesn't trigger: Verify the custom transformer is active and the Transfer conversation node is properly configured.
• Authentication errors: Ensure the Direct Line secret is correctly configured in ServiceNow. Specifically, link the credential record in ServiceNow with a connection record.
• Function timeout: Check if the Azure Function is timing out and increase the timeout settings if necessary.