Geef gesprekken over aan ServiceNow

Verbind ServiceNow Virtual Agent met een Copilot Studio-agent en configureer de overdracht aan een menselijke agent in ServiceNow. De integratie gebruikt een Azure-functie om Direct Line-activiteiten door te geven en een aangepaste ServiceNow-transformator om overdrachtsgebeurtenissen te detecteren.

Overview

Voor de integratie tussen Copilot Studio en ServiceNow zijn de volgende configuratiestappen op hoog niveau vereist:

1. Zet een Azure Function in als relais naar Direct Line.

2. Stel Bot Interconnect in ServiceNow in.

3. Onderwerpen koppelen tussen ServiceNow Virtual Agent en Copilot Studio.

4. Verleng DirectLinePrimaryBotIntegrationInboundTransformer.

5. Handoff configureren in Copilot Studio.

Prerequisites

Zorg ervoor dat u aan de volgende vereisten voldoet voordat u begint:

• Een actief ServiceNow-account met ServiceNow Virtual Agent en ServiceNow Bot Interconnect ingeschakeld. Je hebt ServiceNow Yokohama of hoger nodig.
• Een Copilot Studio-agent geconfigureerd met geen authenticatie. Deze instelling geldt voor het aanmelden van eindgebruikers; het server-to-server-relais gebruikt een Direct Line secret om kanaaltoegang te autoriseren.
• Beheerderstoegang tot ServiceNow.

Maak een Azure Function aan als relais naar Direct Line

De Azure-functie fungeert als een relais zodat ServiceNow Bot Interconnect activiteiten kan ophalen, zoals berichten en gebeurtenissen, uit een lopend gesprek met een Copilot Studio-agent.

Voorbeeldaanvraag verzonden door 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

Voorbeeldantwoord van de Azure-functie

{
    "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"
}

Maak de functie aan en rol deze uit

U kunt de v3 Azure-functie maken en implementeren die wordt beschreven in de ServiceNow-documentatie of de v4 Azure-functie die beschikbaar is in de GitHub-opslagplaats van Copilot Studio.

Optie 1: De Azure-functie v3 implementeren

Als u de Azure-functie v3 wilt maken en implementeren, volgt u de stappen die worden beschreven in de ServiceNow-documentatie:

1. Maak een JavaScript-functie in Microsoft Azure met behulp van Visual Studio Code.

2. Implementeer de functie in Azure en haal de functie-URL op voor gebruik in ServiceNow Bot Interconnect.

Optie 2: De v4 Azure-functie implementeren

U kunt ook de v4 Azure-functie gebruiken die beschikbaar is in de GitHub-opslagplaats van Copilot Studio:

1. Klon de Copilot Studio Samples-repository. Open het opgegeven project onder contact-center/servicenow/DirectLineAzureFunction in Visual Studio Code.

2. Volg de installatie-instructies van het project. Maak een Function App in Azure en deploy het meegeleverde relaisproject. Vervang de relay niet door een nieuwe door een sjabloon gegenereerde HTTP-functie. Lees meer in Deploy projectbestanden.

3. Na de implementatie kopieer je de URL van de relay-HTTP-functie voor gebruik in ServiceNow Bot Interconnect. Gebruik het functie-endpoint, niet de basis-URL van de functie-app. Lees meer in De URL van een door HTTP geactiveerde functie in Azure ophalen.

Bot Interconnect configureren in ServiceNow

1. Haal het direct line-geheim van uw agent op.

2. Voeg de geheime sleutel voor Direct Line toe aan uw Virtual Agent Bot Interconnect-exemplaar.

Onderwerpen afstemmen tussen ServiceNow Virtual Agent en Copilot Studio

1. Maak een Virtual Agent Bot Interconnect shell-topic aan om Copilot Studio-topics aan te roepen.

Uitbreiden DirectLinePrimaryBotIntegrationInboundTransformer

De ingebouwde DirectLinePrimaryBotIntegrationInboundTransformer code parseert de Copilot Studio-gebeurtenis handoff.initiate niet wanneer het gesprek moet worden overgedragen aan een live agent.

De shouldConnectToAgent functie in DirectLinePrimaryBotIntegrationInboundTransformer retourneert altijd onwaar:

shouldConnectToAgent: function(response) {
    return false;
}

Als u handoff-gebeurtenissen goed wilt afhandelen, maakt u een aangepaste transformator waarmee de standaardtransformatie wordt uitgebreid en de handoff.initiate gebeurtenis wordt gedetecteerd.

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;
    }

De aangepaste transformator maken

1. Schakel in ServiceNow over naar het toepassingsbereik Bot Interconnect .

   1. Selecteer het wereldbolpictogram in de rechterbovenhoek.

   2. Selecteer Bot Interconnect in de lijst met toepassingen.

2. Maak een nieuw script Include.

   1. Ga naar Systeemdefinitie>Script Includes.

   2. Klik op Nieuw.

   3. Configureer de volgende instellingen:

   • Naam: CustomDirectLineInboundTransformer
   • API-naam: sn_va_bot_ic.CustomDirectLineInboundTransformer (automatisch gegenereerd)
   • Toepassing: Bot Interconnect (automatisch geselecteerd)
   • Toegankelijk vanaf: Dit toepassingsbereik is alleen toegankelijk
   • Actief: Geselecteerd

3. Vervang de standaardscriptinhoud door de aangepaste transformatieprogrammacode uit de opslagplaats Copilot Studio Samples.

4. Selecteer Verzenden om de scriptopname op te slaan.

De Bot Interconnect-configuratie bijwerken

1. Ga naar Workflow Studio.

   1. Ga in ServiceNow naar Workflow Studio.

   2. Zoek onder Acties, Direct Line Primary Bot Integration Inbound Transformer.

2. Wijzig de actie van de transformator.

   1. Open de actie Direct Line Primary Bot Integration Inbound Transformer.

   2. Maak in de scripteditor commentaar op de standaardtransformatie en vervang deze door een aanroep naar uw aangepaste transformator.

   (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. Sla de wijzigingen op in de actie en publiceer deze.

Handoff configureren

Om overdracht aan een menselijke agent in ServiceNow te configureren, voeg je een Transfer conversation-node toe aan het Escalate-onderwerp van je agent.

1. Open uw agent in Copilot Studio en ga naar Topics>System>Escalate.

2. Selecteer + (knooppunt toevoegen) >Onderwerpbeheer>Gesprek overdragen.

3. Sla je onderwerp op en publiceer je agent.

Het gespreksknooppunt Overdragen verzendt een handoff.initiate gebeurtenis die door de aangepaste transformator van ServiceNow wordt gedetecteerd en verwerkt.

Voorbeeld van YAML-bestand voor escalerend onderwerp

U kunt ook de volgende YAML-configuratie importeren voor een volledig escalerend onderwerp met overdrachtsmogelijkheden:

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

Als er fouten optreden in de chatwidget ServiceNow Virtual Agent, volgt u deze stappen voor probleemoplossing:

Azure Function-logboeken controleren

1. Controleer of uw Azure-functie correct werkt en geen fouten retourneert.

2. Realtimelogboeken weergeven met behulp van streaminglogboeken van Azure Functions.

3. Controleer Application Insights op gedetailleerde telemetrie- en foutgegevens.

Zet ServiceNow debugging aan

Gebruik de ingebouwde hulpprogramma's voor foutopsporing van ServiceNow om de uitvoeringsstroom te traceren:

1. Zet Script Tracer in ServiceNow in.

2. Herhaal de actie die de fout veroorzaakt.

3. Controleer de traceringslogboeken om te bepalen waar het probleem zich voordoet.

Copilot Studio-aanroepen bewaken

Zorg ervoor dat uw Copilot Studio-agent correct wordt aangeroepen:

1. Verbind uw Copilot Studio-agent met Application Insights.

2. Controleer de telemetrie om te bevestigen dat de agent aanvragen ontvangt van ServiceNow.

3. Controleer op fouten of onverwacht gedrag bij de uitvoering van de agent.

Veelvoorkomende problemen en oplossingen

• Handoff wordt niet geactiveerd: controleer of de aangepaste transformator actief is en of het gespreksknooppunt overdragen juist is geconfigureerd.
• Verificatiefouten: zorg ervoor dat het Direct Line-geheim juist is geconfigureerd in ServiceNow. Koppel de referentierecord in ServiceNow met een verbindingsrecord.
• Functietime-out: controleer of er een time-out optreedt voor de Azure-functie en verhoog de time-outinstellingen indien nodig.