Transférer les conversations à ServiceNow

Connectez l’agent virtuel ServiceNow à un agent Copilot Studio et configurez le transfert vers un agent humain dans ServiceNow. L’intégration utilise une fonction Azure pour relayer les activités Direct Line et un transformateur ServiceNow personnalisé pour détecter les événements de transfert.

Overview

L’intégration entre Copilot Studio et ServiceNow nécessite les étapes de configuration générales suivantes :

1. Déploie une fonction Azure en tant que relais vers Direct Line.

2. Configurez Bot Interconnect dans ServiceNow.

3. Associer des sujets entre un agent virtuel ServiceNow et Copilot Studio.

4. Étendre DirectLinePrimaryBotIntegrationInboundTransformer.

5. Configurer le transfert dans Copilot Studio.

Prerequisites

Avant de commencer, vérifiez que vous disposez des conditions préalables suivantes :

• Un compte ServiceNow actif avec ServiceNow Virtual Agent et ServiceNow Bot Interconnect activés. Vous devez disposer de ServiceNow Yokohama ou version ultérieure.
• Un agent Copilot Studio configuré sans authentification. Ce paramètre s’applique à la connexion utilisateur final ; le relais serveur-à-serveur utilise un secret Direct Line pour autoriser l’accès au canal.
• Accès administrateur à ServiceNow.

Créer une fonction Azure en tant que relais vers Direct Line

La fonction Azure agit comme un relais afin que ServiceNow Bot Interconnect puisse récupérer des activités, telles que des messages et des événements, à partir d’une conversation en cours avec un agent de Copilot Studio.

Exemple de demande envoyée par 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

Exemple de réponse de la fonction Azure

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

Créer et déployer la fonction

Vous pouvez créer et déployer la fonction Azure v3 décrite dans la documentation ServiceNow ou la fonction Azure v4 disponible dans le dépôt GitHub Copilot Studio.

Option 1 : Déployer la fonction Azure v3

Pour créer et déployer la fonction Azure v3, suivez les étapes décrites dans la documentation ServiceNow :

1. Créer une fonction JavaScript dans Microsoft Azure à l’aide de Visual Studio Code.

2. Déployez la fonction sur Azure et récupérez l’URL de la fonction à utiliser dans ServiceNow Bot Interconnect.

Option 2 : Déployer la fonction Azure v4

Vous pouvez également utiliser la fonction Azure v4 disponible dans le dépôt GitHub Copilot Studio :

1. Clonez le dépôt d’échantillons du Copilot Studio. Ouvrez le projet fourni sous contact-center/servicenow/DirectLineAzureFunction dans Visual Studio Code.

2. Suivez les instructions de configuration du projet. Créez une application de fonction dans Azure et déployez le projet relais fourni. Ne remplacez pas le relais par une nouvelle fonction HTTP générée par un modèle. En savoir plus dans Déployer les fichiers du projet.

3. Après le déploiement, copiez l’URL de la fonction HTTP relais pour l’utiliser dans ServiceNow Bot Interconnect. Utilisez le point de terminaison de la fonction, et non l’URL de base de l’application de fonction. En savoir plus dans Obtenez l’URL d’une fonction déclenchée HTTP dans Azure.

Configurer Bot Interconnect dans ServiceNow

1. Obtenez le secret Direct Line de votre agent.

2. Ajouter la clé secrète Direct Line à votre instance Virtual Agent Bot Interconnect.

Faire correspondre les rubriques entre ServiceNow Virtual Agent et Copilot Studio

1. Créez une rubrique d’interconnexion de bot d’agent virtuel de type enveloppe pour appeler des rubriques Copilot Studio.

Étendre DirectLinePrimaryBotIntegrationInboundTransformer

Le composant DirectLinePrimaryBotIntegrationInboundTransformer intégré n’analyse pas l’événement Copilot Studio handoff.initiate lorsque la conversation doit être transmise à un agent en direct.

La shouldConnectToAgent fonction dans DirectLinePrimaryBotIntegrationInboundTransformer toujours retourne false :

shouldConnectToAgent: function(response) {
    return false;
}

Pour gérer correctement les événements de transfert, créez un transformateur personnalisé qui étend le transformateur par défaut et détecte l’événement handoff.initiate .

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

Créer le transformateur personnalisé

1. Dans ServiceNow, basculez vers l’étendue de l’application Bot Interconnect .

   1. Sélectionnez l’icône de globe dans le coin supérieur droit.

   2. Sélectionnez Bot Interconnect dans la liste des applications.

2. Créez un script Inclure.

   1. Accédez à Définition du système>Scripts inclus.

   2. Cliquez sur Nouveau.

   3. Configurez les paramètres suivants :

   • Nom : CustomDirectLineInboundTransformer
   • Nom de l’API : sn_va_bot_ic.CustomDirectLineInboundTransformer (généré automatiquement)
   • Application : Bot Interconnect (sélectionné automatiquement)
   • Accessible à partir de : cette étendue d’application uniquement
   • Actif: Sélectionné

3. Remplacez le contenu de script par défaut par le code du transformateur personnalisé à partir du référentiel d’exemples Copilot Studio.

4. Sélectionnez Envoyer pour enregistrer le script Include.

Mettre à jour la configuration de Bot Interconnect

1. Accédez à Workflow Studio.

   1. Dans ServiceNow, accédez à Workflow Studio.

   2. Sous Actions, recherchez Direct Line Primary Bot Integration Inbound Transformer.

2. Modifiez l’action du transformateur.

   1. Ouvrez l’action Direct Line Primary Bot Integration Inbound Transformer.

   2. Dans l’éditeur de script, commentez le transformateur par défaut et remplacez-le par un appel à votre transformateur personnalisé.

   (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. Enregistrez les modifications apportées à l’action et publiez.

Configurer le transfert

Pour configurer le transfert vers un agent humain dans ServiceNow, ajoutez un nœud Transférer la conversation à la rubrique Escalader de votre assistant.

1. Dans Copilot Studio, ouvrez votre agent et accédez à Topics>System>Escalate.

2. Sélectionnez + (Ajouter un nœud) >Gestion des rubriques>Transférer la conversation.

3. Enregistrez votre rubrique et publiez votre assistant.

Le nœud de conversation de transfert envoie un handoff.initiate événement que le transformateur personnalisé de ServiceNow détecte et traite.

Exemple de rubrique d’escalade YAML

Vous pouvez également importer la configuration YAML suivante pour une rubrique d’escalade complète avec des fonctionnalités de transfert :

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

Si vous rencontrez des erreurs dans le widget de conversation de l’agent virtuel ServiceNow, procédez comme suit :

Vérifier les journaux de la fonction Azure

1. Vérifiez que votre fonction Azure fonctionne correctement et ne retourne pas d’erreurs.

2. Affichez les journaux en temps réel à l’aide des journaux de streaming de Azure Functions.

3. Consultez Application Insights pour obtenir des informations détaillées sur la télémétrie et les erreurs.

Activez le débogage ServiceNow

Utilisez les outils de débogage intégrés de ServiceNow pour suivre le flux d’exécution :

1. Activez Script Tracer dans ServiceNow.

2. Répétez l’action à l’origine de l’erreur.

3. Passez en revue les journaux de suivi pour identifier l’endroit où se produit le problème.

Surveiller les appels de Copilot Studio

Assurez-vous que votre agent Copilot Studio est bien invoqué :

1. Connectez votre agent Copilot Studio à Application Insights.

2. Surveillez les données de télémétrie pour confirmer que l’agent reçoit des demandes de ServiceNow.

3. Vérifiez les erreurs ou les comportements inattendus dans l’exécution de l’agent.

Problèmes courants et solutions

• Le transfert ne se déclenche pas : vérifiez que le transformateur personnalisé est actif et que le nœud de conversation Transfert est correctement configuré.
• Erreurs d’authentification : vérifiez que le secret Direct Line est correctement configuré dans ServiceNow. Plus précisément, liez l’enregistrement d’informations d’identification dans ServiceNow avec un enregistrement de connexion.
• Délai d’expiration de la fonction : vérifiez si la fonction Azure expire et augmentez les paramètres de délai d’expiration si nécessaire.