Fonctionnalités prises en charge dans API Agent virtuel
Vous pouvez utiliser pour API Agent virtuel intégrer un grand nombre des fonctionnalités disponibles dans Agent virtuel votre Messagerie instantanée d'agent environnement de messagerie instantanée. La prise en charge des fonctionnalités varie en fonction de votre ServiceNow version et du numéro de version de l’application de l’App Store du API Agent virtuel.
Pour plus d’informations sur les modèles de demande et de réponse pour Agent virtuel l’API, ainsi que des exemples de cas d’utilisation courants, consultez API d’intégration de bot Agent virtuel.
Version 4.3.0
Prise en charge de la messagerie instantanée premium dans l’API Agent virtuelVersion 4.1.1
- Lorsque la réponse synthétisée est activée par Now Assist l’expérience, API Agent virtuel envoie la réponse avec les citations au bot principal. Les citations sont incluses dans le citations paramètre avec des liens de citation séparés.
- Voici un exemple de JSON pour une réponse synthétisée avec des citations et des liens de citation :
{ "clientSessionId": "va_api_conv_16875", "score": 1, "interactionId": "0dce3e37ffe1f610f71affffffffff8a", "requestId": "1765195564288", "streamActive": false, "streamState": "END", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "feedback": { "messageId": "dcde7a7739e1f610beed69f9e5960355", "feedbackEnabled": true }, "maskType": "NONE", "citations": [ { "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33", "sysId": "24d9243187032100deddb882a2e3ec33", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "What is Spam?", "index": 0, "source": "internal", "category": "kb", "citationLabel": "What is Spam?", "table": "kb_knowledge", "citationRef": "[1]" }, { "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2", "sysId": "0b48fd75474321009db4b5b08b9a71c2", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "How to Deal with Spam", "index": 1, "source": "internal", "category": "kb", "citationLabel": "How to Deal with Spam", "table": "kb_knowledge", "citationRef": "[2]" }, { "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d", "sysId": "3020c9b1474321009db4b5b08b9a712d", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "What are phishing scams and how can I avoid them?\n\t\t", "index": 2, "source": "internal", "category": "kb", "citationLabel": "What are phishing scams and how can I avoid them?\n\t\t", "table": "kb_knowledge", "citationRef": "[3]" } ], "streamId": "4fcef677ffe1f610f71affffffffffee", "uiType": "OutputText", "messageId": "dcde7a7739e1f610beed69f9e5960355", "relatedList": [], "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, quack health products, pornographic site ads, offers for bulk emailing services, chain letters, and pirated software. Most reputable marketers do not use spam for advertising. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes.\n- Use judgment when unsubscribing or responding to unfamiliar sources \u200b[1]\u200b\u200b[2]\u200b.\n\nPhishing scams, a dangerous form of spam, attempt to trick you into revealing personal information by pretending to be legitimate organizations. Always verify requests for sensitive information and avoid clicking suspicious links \u200b[3]\u200b.\n\n[1] [What is Spam?](http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)\n[3] [What are phishing scams and how can I avoid them?\n\t\t](http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d)", "group": "DefaultText" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } } - Pour plus d'informations, consultez Activer la réponse synthétisée dans API Agent virtuel.
- API Agent virtuel Prend en charge la réponse agentique par l’expérience Now Assist . Lorsque la réponse agentique est activée dans API Agent virtuel, les messages de sortie sont affichés à l’utilisateur comme étant en cours de chargement ou de traitement.
- API Agent virtuel Envoie un message au bot primaire via un nouveau DynamicLoader paramètre.
- Voici un exemple de JSON pour la réponse agentique :
{ "clientSessionId": "va_api_conv_16875", "score": 1, "interactionId": "0dce3e37ffe1f610f71affffffffff8a", "requestId": "1765195564288", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "progressMessages": [ { "message": "Searched for relevant documents and actions", "status": "COMPLETED" }, { "message": "Generated the response", "status": "COMPLETED" } ], "actionType": "DynamicLoader", "defaultHeader": "View AI Steps", "uiType": "ActionMsg", "parentMessageId": "87cef677ffe1f610f71affffffffff4d", "header": "View AI Steps", "messageId": "87cef677ffe1f610f71affffffffff4d", "shouldUpdateParentMessage": true } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } }
- API Agent virtuel prend en charge la diffusion des réponses via l’expérience Now Assist . Pour en savoir plus, consultez Activer l’expérience Now Assist dans API Agent virtuel. Remarque :Le bot principal doit transmettre les réponses de diffusion en continu à l’utilisateur final. Pour plus d'informations, consultez Réponses de diffusion de messagerie instantanée.
- API Agent virtuel Prend en charge les états suivants pour la diffusion des réponses :
- DÉMARRER
{ "clientSessionId": "va_api_conv_16875", "requestId": "1762864530268", "streamActive": true, "streamState": "START", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "streamId": "cb928c9f53097e10f71a6dc230e5e639", "uiType": "StreamStart", "streamSequence": 1, "value": "Looking into your request" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } } - EN COURS
{ "clientSessionId": "va_api_conv_16875", "requestId": "1762864530268", "streamActive": true, "streamState": "INPROGRESS", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "streamId": "cb928c9f53097e10f71a6dc230e5e639", "uiType": "StreamChunk", "streamSequence": 2, "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } } - FIN
{ "clientSessionId": "va_api_conv_16875", "score": 1, "interactionId": "d592c89f53097e10f71a6dc230e5e68c", "requestId": "1762864530268", "streamActive": false, "streamState": "END", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "feedback": { "messageId": "6f92cc9f34097e108001c582b67b2a1f", "feedbackEnabled": true }, "maskType": "NONE", "citations": [ { "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33", "sysId": "24d9243187032100deddb882a2e3ec33", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "What is Spam?", "index": 0, "source": "internal", "category": "kb", "citationLabel": "What is Spam?", "table": "kb_knowledge", "citationRef": "[1]" }, { "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2", "sysId": "0b48fd75474321009db4b5b08b9a71c2", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "How to Deal with Spam", "index": 1, "source": "internal", "category": "kb", "citationLabel": "How to Deal with Spam", "table": "kb_knowledge", "citationRef": "[2]" } ], "streamId": "cb928c9f53097e10f71a6dc230e5e639", "uiType": "OutputText", "messageId": "6f92cc9f34097e108001c582b67b2a1f", "relatedList": [], "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, \"get rich quick\" offers, quack health products, ads for pornographic sites, offers for bulk emailing services, chain letters, and pirated software. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online or with companies.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes \u200b[1]\u200b\u200b[2]\u200b.\n\n[1] [What is Spam?](http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)", "group": "DefaultText" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } }
- DÉMARRER
- Activez la diffusion entrante API Agent virtuel via la configuration suivante :
- Assurez-vous que l’option Autoriser la diffusion des réponses est sélectionnée dans Now Assist .Agent virtuel Pour en savoir plus, consultez Activer des fonctionnalités supplémentaires de messagerie instantanée.
- Accédez à Tout et saisissez sys_now_assist_channel_config.list dans le filtre de navigation.
- Dans la table Configuration du Now Assist canal [now_assist_channel_config], définissez la valeur du champ Prêt pour la diffusion sur vrai pour l’appareil bot à bot.
Figure 1. Table de configurations de canaux Now Assist
- API Agent virtuel est maintenant configuré pour utiliser l’étape Studio de workflow REST au lieu du message REST précédent ServiceNow AI Platform .
- Pour en savoir plus, consultez Configurer l’authentification sortante et REST de la réponse de sortie pour l’API Agent virtuel (v4.1 ou supérieure).
Version 4.0.0
- API Agent virtuel Met à jour le texte du message et l’état de remise des messages entre l’agent actif et le bot principal.
-
API Agent virtuel envoie l’ID d’interaction et l’ID de message (ID de l’agent pour les conversations avec l’agent actif) en réponse au bot primaire.
L’enregistrement d’interaction stocke le clientSessionId paramètre envoyé par l’application de messagerie instantanée tierce prise en charge (ou le bot principal) pour chacune de ses conversations avec l’utilisateur final. Pour en savoir plus, consultez Configurer l’enregistrement d’interaction pour stocker clientSessionId dans API Agent virtuel.
- L’historique de discussion de la conversation du bot principal avec l’utilisateur final inclut l’horodatage des messages individuels. Les agents en direct peuvent désormais voir cet historique de discussion dans des messages individuels ou dans un seul bloc. Pour en savoir plus, consultez Configurer pour prendre en charge l’historique de messagerie instantanée dans API Agent virtuel. Vous pouvez personnaliser l’interface de la Messagerie instantanée d’agent en définissant un logo pour le bot primaire qui apparaît dans l’historique de messagerie instantanée. Pour plus d'informations, consultez Logo de définition pour le bot primaire dans API Agent virtuel.
Version 3.0.x
- Lorsque le bot principal transfère une messagerie instantanée à un agent actif, API Agent virtuel envoie l’ID de l’agent, en plus du nom et de l’avatar de l’agent, au bot principal.
- API Agent virtuel Envoie l’historique de messagerie instantanée du bot primaire à l’agent actif n’importe où dans la demande au cours d’une conversation en cours. Ce comportement est contrôlé par la propriété système suivante : allow_storing_history_in_ongoing-conversation. Définissez la valeur de la propriété sur vrai pour envoyer l’historique de la messagerie instantanée n’importe où dans la demande.
- L’enregistrement d’interaction contient la transcription de l’historique de la messagerie instantanée ainsi que l’horodatage des messages individuels.
- Now AssistAPI Agent virtuel offre des compétences d’IA générative sur plusieurs canaux de fournisseurs.
- Pour plus d'informations, consultez Activer l’expérience Now Assist dans API Agent virtuel.
- API Agent virtuel active la configuration de plusieurs applications de fournisseurs pour prendre en charge les cas d’utilisation où plusieurs bots primaires les utilisent API Agent virtuel et vous devez les distinguer.
- Pour plus d'informations, consultez Configurer plusieurs applications de fournisseurs.
- API Agent virtuel Prend en charge la transformation des charges utiles des demandes et des réponses dans le sens API Agent virtuel inverse. Ceci est utile dans les cas où le bot primaire a un modèle de réponse commun à tous les bots secondaires.
- Pour plus d'informations, consultez Demande de transformation API Agent virtuel et réponse.
- API Agent virtuel prend en charge les chargements de fichiers d’une taille maximale de 1 Go à partir d’une URL privée. Le bot principal doit transmettre l’ID d’utilisateur, l’ID d’application du fournisseur facultatif et le nom du fichier. Respectez les directives suivantes :
- L’ID d’application du fournisseur est facultatif.
- L’ID d’utilisateur et l’ID d’application du fournisseur doivent être envoyés avant le nom du fichier dans la charge utile.
- Un rôle doit être indiqué dans la glide.attachment.role propriété pour l’utilisateur final. Pour plus d’informations, voir Exiger un rôle pour joindre des fichiers.
- L’authentification de base ou OAuth est prise en charge, mais pas l’authentification de message.
- Exemple de charge utile du message du bot primaire :
curl -X POST \ https://instance.service-now.com/api/now/v1/cccif/media/upload \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H 'content-type: multipart/form-data; \ -F user_id=xxxxxx \ -F provider_application_id=optionalId \ -F 'file=@SomeFile.png' - API Agent virtuel envoie l’exemple JSON suivant :
{ "result": { "mediaUrl": "http://123.456.7.8:8080//api/now/v1/cs/media/string", "name":"imagefile.png", "state":"pending", "attachmentId":"abcdefghijklmno12345" } }
- Un message silencieux est un message qui ne nécessite pas de réponse. Si Agent virtuel vous recevez une demande avec silentMessage=true, tous les messages suivants du bot sont supprimés jusqu’à ce que vous Agent virtuel receviez une demande de désactivation du mode silencieux (silentMessage=false).
- Exemple de charge utile du message du bot primaire :
{ "token": "BOT_TOKEN", "botToBot": true, "clientSessionId": "884502214730301027f83ee4070f589a", "clientVariables": {}, "requestId": "48450221d23030107300b7756770bc9b", "silentMessage": "true", "timestamp": 1623916324820, "timezone": "GMT", "userId": "abel.tuter", "emailId": "abel.tuter@example.com" }Remarque :Si silentMessage=true, les notifications ne sont pas remises.
- En plus de transmettre des messages à un ServiceNow® Agent virtuel bot secondaire, le bot principal ou le client de messagerie instantanée peut transmettre des messages à un agent via Messagerie instantanée d'agent. Utilisez le action paramètre transmis dans le corps de la demande pour spécifier comment le contenu doit être traité.
- API Agent virtuel prend en charge les types de messages d’action suivants :
Tableau 1. Types de messages d’action pris en charge Valeur actionType Description ChatSubHeader Message sortant indiquant que l’un des événements suivants s’est produit : - Échec de la traduction dynamique.
- Le pilote automatique de l’agent actif a été lancé et terminé.
StartSpinner Message sortant qui démarre un spinner lorsqu’un message est en attente en raison de processus asynchrones, tels que Recherche IA ou le filtre de vulgarité. EndSpinner Message sortant qui arrête le spinner qui a été envoyé précédemment. Message StartTypingIndicatorActionMsg Message sortant indiquant qu’un utilisateur ou un agent a commencé à saisir du texte (après qu’un agent a accepté la conversation instantanée). EndTypingIndicatorActionMsg Message sortant indiquant qu’un utilisateur ou un agent a arrêté de saisir. SubscribeToSupportQueue (File d’attente d’abonnement) Indique que la conversation est définie sur la file d’attente de support. S’abonner à ChatPresence Message sortant indiquant qu’une conversation avec un agent actif a commencé. SwitchToLiveAgent Message sortant indiquant qu’un agent actif a accepté la conversation. SwitchToVirtualAgent Message sortant indiquant que la session de l’agent actif est terminée et que la conversation est renvoyée à Agent virtuel. Changer de conversation Message sortant indiquant qu’une notification a été envoyée. Cette opération crée une nouvelle conversation, puis Agent virtuel bascule vers la nouvelle conversation. Système Message sortant indiquant l’un des éléments suivants : - Un agent actif est entré dans le chat.
- L’agent actif ou l’utilisateur a fermé la messagerie instantanée.
- La conversation avec un agent actif a expiré.
- API Agent virtuel peut être transféré à un agent actif de façon synchrone. Lorsqu’un utilisateur ou un agent termine une conversation, le transfert vers Agent virtuel s’effectue également de manière synchrone. Certains messages système et messages de temps d’attente sont également envoyés de manière synchrone.
- Pour utiliser le transfert synchrone vers un agent actif, tenez compte des instructions suivantes :
- Configurez le point de terminaison de Agent virtuel réponse. Messagerie instantanée d'agent Les messages seront remis au point de terminaison que vous spécifiez.
- Vous devez désactiver manuellement les notifications pour l’instance.
- Si vous utilisez le transfert synchrone vers un agent actif, API Agent virtuel envoie l’indicateur de saisie s’il est activé :
{ "uiType": "ActionMsg", "actionType": "StartTypingIndicator", } - Les rubriques qui utilisent les fonctionnalités suivantes ne sont pas prises en charge en mode synchrone : téléchargement de fichiers, bloc Utilitaire d’action de rubriques et pause.
- Pour désactiver ces fonctionnalités et activer la prise en charge synchrone, reportez-vous à la section Activer la prise en charge synchrone dans API Agent virtuel.
- Le changement de rubrique peut échouer pour l’une des raisons suivantes :
- La demande inclut à la fois le nom de la rubrique et l’ID de la rubrique (mot clé Découverte de rubriques) ou le nom de l’intention de rubrique et l’ID de l’intention de rubrique (découverte de rubriques NLU). Spécifiez l’un ou l’autre.
- La demande inclut une rubrique ou un nom d’intention ou un ID non valide.
- Le nom ou l’ID de la rubrique/intention est valide, mais Agent virtuel ne peut pas l’exécuter car il est inactif ou n’appartient pas à une rubrique. Par exemple, si le nom ou l’ID fait référence à un bloc de rubriques ou à un actif de contrôle personnalisé.
- La rubrique demandée est déjà en cours d’exécution.
- La rubrique demandée est valide, mais une condition de sécurité empêche d’y accéder. Par exemple, la rubrique peut ne pas être autorisée à s’exécuter dans le canal ou une autre condition de contrôle d’accès peut s’appliquer.
- Si le changement de rubrique échoue, répond de la manière suivante, API Agent virtuel que vous l’utilisiez de manière synchrone ou asynchrone :
- En cas d’échec du changement de rubrique, la conversation est fermée avec un message indiquant que la conversation ne peut pas continuer. La conversation ne restera plus à l’état ouvert.
- La demande précédente est marquée comme traitée afin qu’une nouvelle demande puisse être effectuée sans attendre le délai d’expiration.
- La raison de la défaillance est consignée dans la table de journal système ().
- API Agent virtuel les réponses incluent des paramètres tels que Prendre le contrôle et Score NLU. Ces paramètres sont traités lors de la préparation de la réponse.
- À partir de la version 3.9.0, vous pouvez exclure les paramètres Prendre le contrôle et/ou Score NLU de la API Agent virtuel réponse pour améliorer le temps de réponse.
- Pour exclure les paramètres Prendre le contrôle et Score NLU de la API Agent virtuel réponse, procédez comme suit :
- Accédez à la .
- enable_take_control Rechercher et send_nlu_score propriétés.
- Définissez la valeur de enable_take_control la propriété sur faux pour exclure le paramètre Prendre le contrôle et send_nlu_score la propriété sur faux pour exclure le calcul du score NLU lors du traitement de la réponse. Ces propriétés sont définies sur vrai par défaut.
- Si une conversation est incomplète en raison d’une erreur, Agent virtuel le bot principal peut demander de prendre le contrôle. Si le takeControl marqueur est true, Agent virtuel (en tant que bot secondaire) fermera automatiquement la conversation. Si le bot principal souhaite démarrer une conversation, il peut envoyer le message d’action suivant :
« salut »/START_CONVERSATION. - Vous pouvez demander au bot primaire de prendre le contrôle dans les situations suivantes :
- Délai d’inactivité : l’état d’interaction est Fermé et abandonné. Le motif de l’état est Aucune activité.
- Problèmes techniques : L’état d’interaction est Fermé et abandonné. La raison de l’état est Problèmes de bot.
- Entrée utilisateur non valide : l’état d’interaction est Fermé et abandonné. Le motif de l’état est Entrée utilisateur non valide.
- Pour demander au bot principal de prendre le contrôle, envoyez le takeControl marqueur dans le corps de la charge utile au bot principal avec une valeur de true.
- Exemple de charge utile du message :
{ "requestId": "xxxx-xxxx-xxxx-xxxx", "clientSessionId": "xxx-xxx-xxx-xxx", "message": { "text":"invalid3", "typed":true } "body":[{ "uiType":"OutputText", "group":"DefaultText", "value":"Sorry, I didn't get that. Could you help me by answering this?" }, { "uiType":"Boolean", "group":"DefaultPicker", "required":true, "nluTextEnabled": false, "label":"Choose a value", "options":[ {"label":"Yes"}, {"label":"No"} ] }], "takeControl":true, "score":0 }