Une conversation lancée par une application commence lorsqu'une application externe envoie un événement à la compétence ou à l'assistant numérique dont elle fait partie. Certaines modifications doivent être apportées à votre compétence pour que la conversation commence au bon endroit et affiche les valeurs voulues.

Un événement envoyé à partir d'une application externe doit inclure un type de données utiles, qui identifie de manière unique l'événement pour la compétence. En général, le type de données utiles indique ce que la compétence doit faire, par exemple msgReminder ou cancelAppointment. L'objet JSON variables de l'événement peut également comporter des paramètres, tels que le nom d'un patient ou une heure de rendez-vous.

Dans votre compétence, vous devez vous assurer que le flux de dialogue comporte un état de début pour chaque événement (plusieurs événements peuvent avoir le même état de début). Vous devez également ajouter des variables de niveau flux contenant les valeurs des paramètres, si elles sont définies. Vous devez ensuite mapper le type de données utiles de l'événement à l'état de début.

Pour chaque événement, procédez de la façon suivante :

1. Si votre application externe transmet un objet variables dans les données utiles du message, ajoutez des variables de niveau flux pour contenir les valeurs des propriétés de l'objet.

   Le nom de la variable de niveau flux doit correspondre à celui de l'objet variables. Par exemple, supposons que l'application externe envoie un corps de demande comme ce qui suit pour un événement de rappel de rendez-vous :

   {
       "userId": "16035550100",
       "messagePayload": {
           "type": "application",
           "payloadType": "msgReminder",
           "channelName": "AppointmentUserChannel",
           "variables": {
           	"patientName": "Joe Doe",
           	"appointmentTime": "5:00 pm"
           }
       }
   }

2. Assurez-vous que le flux de dialogue a un état de début pour l'événement.

   Conseil :

   Si la plate-forme de messagerie est de type texte seul, envisagez de réduire au maximum les erreurs d'entrée utilisateur en configurant la numérotation automatique dans le flux de dialogue de la compétence. Envisagez également d'afficher ou de masquer le texte en fonction de la plate-forme de messagerie. Voir Canaux textuels.

3. Pour mapper l'événement à l'état de début, cliquez sur Settings (Paramètres) , sur Events (Événements), puis sur + Add Mapping (Ajouter un mappage). Entrez une valeur dans les champs suivants :

   • Payload type (Type de données utiles) : Nom identifiant l'événement de manière unique. L'application externe doit utiliser ce nom pour diriger le message vers l'état applicable.

     Vous utilisez le type de données utiles de l'application externe plutôt que le nom d'état réel car il est constant, tandis que le nom de l'état peut changer si le flux de dialogue est révisé.

   • State name (Nom d'état) : État de début de l'événement dans le flux de dialogue.

   Dans cette capture d'écran, le type de données utiles msgReminder est mappé à l'état remindermessage dans le flux de dialogue.

   
   
   Description de l'illustration event-map.png
   

   Lorsque vous ajoutez une compétence à un assistant numérique, les mappages entre événements et état de la compétence sont ajoutés automatiquement dans la page des événements de l'assistant numérique. Vous accédez à cette page depuis la page Settings de l'assistant numérique.

Si votre compétence requiert que les utilisateurs s'authentifient auprès d'Oracle Identity Cloud Service ou d'Oracle Access Manager, vous devez configurer le canal d'application, la compétence et l'application externe pour autoriser la compétence à associer l'ID utilisateur authentifié à l'ID utilisateur du robot.

Pour les événements qui sont envoyés à une compétence authentifiée par l'utilisateur, celui-ci doit être connecté au fournisseur d'identités à partir de la compétence. Par exemple, imaginons que Deva utilise une compétence pour créer un rapport de frais. Avant qu'elle puisse travaille dans la compétence, celle-ci l'invite à se connecter. La compétence associe ensuite son ID utilisateur authentifié à son ID utilisateur pour la plate-forme de messagerie et auxparamètres de la plate-forme de messagerie qui sont en mémoire cache dans le profil de l'utilisateur.

Une fois son rapport terminé, elle demande à être informée lorsque les frais sont approuvés. Son entreprise utilise une application externe pour envoyer l'événement d'avis à la même compétence. Pour que l'application envoie l'événement à une compétence authentifiée par l'utilisateur, elle doit envoyer l'ID utilisateur authentifié de Deva, au lieu de l'ID utilisateur de la plate-forme de messagerie. Avec l'ID utilisateur authentifié, la compétence peut rechercher l'ID utilisateur de la plate-forme et les informations du profil en mémoire cache obtenus lors de la connexion initiale de Deva.

Si Deva ne s'est jamais connectée à partir de la compétence, que son authentification a expiré ou que la mémoire cache du profil a expiré, Digital Assistant répond à la demande d'événement avec une erreur 500.

En plus des étapes décrites dans Configurer la compétence, vous devez exécuter la procédure suivante pour configurer les conversations lancées par une application pour les compétences authentifiées par l'utilisateur :

1. Si votre compétence a déjà activé l'authentification de l'utilisateur, allez à Settings > Authentication Services (Paramètres > Services d'authentification), ouvrez le service et assurez-vous que la valeur de Refresh Token Retention Period (Période de conservation du jeton d'actualisation) est réglée à 14 jours, ce qui correspond à la durée d'expiration du cache du profil d'utilisateur. Ces valeurs doivent être synchronisées.

2. Si votre compétence n'a pas encore activé l'authentification de l'utilisateur, exécutez les étapes suivantes :

   1. Assurez-vous qu'un administrateur a effectué les étapes décrites dans Enregistrement au niveau du fournisseur d'identités.

   2. Créez un service d'authentification pour le fournisseur d'identités, comme décrit dans Services d'authentification.

   3. Assurez-vous que la valeur de Refresh Token Retention Period (Période de conservation du jeton d'actualisation) du service d'authentification est réglée à 14 jours, ce qui correspond à la durée d'expiration de la mémoire cache du profil d'utilisateur. Ces valeurs doivent être synchronisées.

   4. Pour permettre aux utilisateurs de se connecter à partir de la compétence, ajoutez un état pour le composant de lien de compte OAuth 2.0 au flux de dialogue, comme décrit dans OAuth 2.0 Account Link.

3. Lorsque vous créez le canal d'application, activez l'option Use Authenticated User ID (Utiliser l'ID utilisateur authentifié). Ou, s'il a déjà été créé, ouvrez le canal et activez-le.

Dans le corps de la demande envoyée par l'application externe à Digital Assistant, n'oubliez pas de régler la propriété userId à l'ID utilisateur authentifié, comme décrit dans Configurer l'application externe.

Pour que les conversations lancées par une application fonctionnent, vous devez créer un canal d'utilisateur pour lier la compétence à votre compte de plate-forme de messagerie. Reportez-vous aux rubriques ci-dessous pour connaître les étapes de création d'un canal d'utilisateur pour la plate-forme spécifique.

• Twilio/SMS
• Slack
• Microsoft Teams

Notez que si vous sélectionnez une compétence dans la liste Route to (Acheminer vers) du canal, tous les messages de l'application externe envoyés à ce canal sont envoyés à la compétence. Si vous sélectionnez un assistant numérique, vous devez spécifier la compétence cible dans les données utiles des messages de l'application externe.

Vous devez créer un canal d'application pour permettre à l'application externe d'envoyer des messages à Digital Assistant. Une fois le canal créé, Digital Assistant affecte une clé secrète. Vous devez utiliser cette clé secrète dans votre application externe.

1. Dans la barre de navigation gauche, cliquez sur Channels (Canaux), sur Applications, puis sur + Application Configuration (Configuration de l'application).

2. Entrez un nom et, facultativement, une description.

3. (Facultatif) Tous les messages d'erreur liés aux canaux sont consignés dans le fichier journal du serveur. Si vous voulez que Digital Assistant envoie ces messages d'erreur à un service Web externe, entrez l'URL de ce dernier dans le champ Outbound Application URL (URL de l'application de sortie).

   Si une erreur se produit, comme un problème de lancement d'une conversation au moyen du canal d'utilisateur, Digital Assistant envoie un message d'erreur en tant qu'objet JSON avec les propriétés botId, sessionId et message.

4. (Facultatif) Si la compétence ciblée nécessite une authentification à l'aide du composant OAuth 2.0 Account Link (Lien de compte) et que votre application externe envoie l'ID utilisateur authentifié au lieu de l'ID utilisateur de la plate-forme de messagerie, activez l'option Use Authenticate User ID (Utiliser l'ID utilisateur authentifié).

   Lorsque cette option est activée, Digital Assistant recherche l'ID utilisateur de la plate-forme de messagerie pour l'ID utilisateur authentifié spécifié. Notez que l'utilisateur doit avoir ouvert une session depuis la compétence pour que la consultation réussisse. Pour plus de détails, voir Configurer une compétence authentifiée par l'utilisateur.

5. Cliquez sur Create (Créer).

6. Sélectionnez l'option Application Enabled (Application activée).

7. Notez la clé secrète et l'URL entrante. Elles seront utilisées par l'application externe.

   • Celle-ci transmet les messages en envoyant une demande POST à l'URL entrante.
   • Elle utilise la clé secrète pour authentifier ses demandes POST.

Si votre compétence prend en charge les conversations lancée par une application et que vous l'ajoutez à un assistant numérique, vous devez ajuster ces paramètres de configuration dans la page des paramètres de l'assistant numérique :

• Interrupt Prompt (Invite d'interruption) : Cette invite s'affiche lors de l'interruption d'un flux pour en démarrer un nouveau.
• Enable Auto Numbering on Postback Actions (Activer la numérotation automatique pour les actions de republication) : Il est préférable que ce paramètre soit réglé à true pour tous les canaux textuels, afin de limiter les erreurs d'entrée utilisateur. Par défaut, ce paramètre est réglé à true pour tous les canaux Twilio : ${(system.channelType=='twilio')?then('true','false')}

L'application externe lance un événement en envoyant une demande POST à l'URL entrante d'un canal d'application. Les opérations que l'application doit effectuer pour préparer et envoyer la demande sont décrites ci-dessous.

• Inclure les propriétés suivantes dans le corps de la demande (des exemples suivent) :

  • userId : Ce doit être l'un des ID suivants :

    • Microsoft Bot User ID (ID utilisateur Microsoft Bot) : ID utilisateur de robot pour le canal Microsoft Bot. Cet ID est propre à chaque canal Microsoft Bot. La compétence enregistre cette valeur dans la variable profile.msBotUserId.

    • Slack User ID (ID utilisateur Slack) : ID membre de l'utilisateur Slack. La compétence enregistre cette valeur dans system.message.channelConversation.userId.

    • Twilio/SMS Channel ID (ID canal Twilio/SMS) : Numéro de téléphone cellulaire de l'utilisateur. Ce doit être un des numéros de téléphone associés au numéro de téléphone du compte Twilio indiqué dans la configuration du canal d'utilisateur de Digital Assistant. La compétence enregistre cette valeur dans la variable profile.firstName.

    • System-Generated User ID (ID utilisateur généré par le système) : Si vous testez votre compétence à partir de Preview (Prévisualiser), il doit s'agir de l'ID généré par le système pour la session dans Preview (Prévisualiser). Voir Test des conversations lancées par une application à partir de la prévisualisation.

    • Authenticated User ID (ID utilisateur authentifié) : Si l'option Authenticated User ID (ID utilisateur authentifié) est activée pour le canal d'application associé, cet ID doit être celui de l'utilisateur authentifié. L'utilisateur de cet ID authentifié doit déjà être connecté à la compétence cible au moyen du composant de lien de compte OAuth 2.0. Voir Configurer une compétence authentifiée par l'utilisateur.

  • messagePayload : Cet objet contient :

    • type : Réglez à application.

    • payloadType : Nom de l'événement (type de données utiles) mappé à l'état de début voulu dans le flux de dialogue. Voir Configurer la compétence.

    • skillName et version : (Facultatif) Si le canal d'utilisateur de la plate-forme de messagerie effectue un routage vers un assistant numérique, vous devez inclure les propriétés skillName et version de la compétence pour que l'assistant numérique sache à quelle compétence et à quelle version envoyer l'événement.

    • channelName : Nom du canal d'utilisateur de la plate-forme de messagerie configuré pour la compétence ou l'assistant numérique.

      Si vous testez votre compétence à partir de Preview (Prévisualisation), vous devez régler channelName au nom du canal système. Voir Test des conversations lancées par une application à partir de la prévisualisation.

    • variables : (Facultatif) paires clé-valeur à transmettre aux variables du flux de dialogue. Si les variables de flux correspondantes sont définies dans le flux de dialogue, elles sont alimentées avec les valeurs transmises par cet objet.

  • channelProperties : Cet objet est destiné à MS Teams et Slack. Vous n'avez pas besoin d'inclure cet objet dans le corps de la demande si l'option Use Authenticated User ID (Utiliser l'ID utilisateur authentifié) est activée pour le canal d'utilisateur.

    Objet channelProperties MS Teams

    Cet objet est obligatoire si l'utilisateur n'a pas interagi avec la conversation pendant 14 jours. Ses propriétés sont les suivantes :

    • botName : Descripteur du robot spécifié lorsque vous avez créé l'enregistrement de canal de robot, comme décrit dans Étape 1 : Créer un robot. Cette valeur est enregistrée dans la variable profile.botName.

    • tenantId : ID du locataire Microsoft Teams. Cette valeur est enregistrée dans la variable profile.tenantId.

    • serviceUrl : URL du service du robot. Cette valeur est enregistrée dans la variable profile.serviceUrl.

    Lorsque l'utilisateur Microsoft Teams converse avec la compétence, Digital Assistant capture et stocke ces valeurs dans la mémoire cache du profil. Si les données utiles d'une demande d'événement n'incluent pas l'objet channelProperties, la compétence utilise les valeurs de la mémoire cache du profil, si elles sont disponibles (la mémoire cache expire au bout de 14 jours). La compétence utilise les valeurs de profil en mémoire cache uniquement si elles ne se trouvent pas dans le corps de la demande.

    Lorsque le flux de dialogue envoie une demande d'avis au système dorsal, par exemple au moyen d'un composant personnalisé, il doit transmettre ces valeurs de profil au système dorsal. L'application externe peut alors utiliser ces valeurs dans l'objet channelProperties si la mémoire cache du profil a expiré. Voici un extrait de code de composant personnalisé qui obtient les valeurs à renvoyer au système dorsal.

        let serviceUrl = conversation.variable('profile.serviceUrl') ?
            conversation.variable('profile.serviceUrl') : "";
        let tenantId = conversation.variable('profile.tenantId') ? 
            conversation.variable('profile.tenantId') : "";
        let botName = conversation.variable('profile.botName') ?
            conversation.variable('profile.botName') : "";
        let msBotUserId = conversation.variable('profile.msBotUserId') ?       
            conversation.variable('profile.msBotUserId') : "";

    Objet channelProperties Slack

    Pour Slack, incluez les propriétés suivantes dans l'objet channelProperties :

    • teamId : ID espace de travail Slack. Cette valeur est enregistrée dans la variable profile.team_id.

    • channel : ID du canal dans l'espace de travail. Autrement dit, le canal de l'utilisateur. Cette valeur est enregistrée dans la variable profile.channel.

    Vous pouvez obtenir l'ID équipe et le canal à partir de l'URL Web de Slack. Par exemple, si l'URL est https://app.slack.com/client/ABCDEFG/HIJKLMNOP, l'ID équipe est ABCDEFG et le canal, HIJKLMNOP.

  Voici des exemples concernant les différentes plates-formes de messagerie pour les compétences qui n'utilisent pas les ID utilisateurs authentifiés :

  Exemple Slack :

  { 
      "userId": "ABCDE712A3",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "teamId": "ABCDEFG",
              "channel":"HIJKLMNOP" 
          } 
      }
  }

  Exemple MS Teams :

  { 
      "userId": "12:1A2B3C3d....",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "tenantId": "ab12c34d-e56...",
              "botName":"my-bot",
              "serviceUrl":"https://example.com/path/"
          } 
      }
  }

  Exemple Twilio :

  { 
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  Cet exemple montre comment envoyer un événement à un canal qui est acheminé vers un assistant numérique. Lorsque le canal effectue le routage vers un assistant numérique, vous devez inclure le nom et la version de la compétence.

  {
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "skillName": "myBot",
          "version": "1.0",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  Voici un exemple concernant une compétence authentifiée par l'utilisateur (l'option Use Authenticated User ID (Utiliser l'ID utilisateur authentifié) est activé pour le canal d'application associé). Cet exemple s'applique à MS Teams, Slack et Twilio . Notez que pour MS Teams et Slack, vous n'incluez pas l'objet channelProperties lorsque vous effectuez l'acheminement vers une compétence authentifiée par l'utilisateur.

  {
      "userId": "first.last@example.com",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

• Pour authentifier la demande, ajoutez un en-tête X-Hub-Signature avec le hachage SHA256 du corps à l'aide de la clé secrète du canal d'application. Par exemple :

  X-Hub-Signature: sha256={{HMAC SHA-256 signature of body}}

  La section Utiliser Postman en tant qu'application externe du tutoriel Envoyer des rappels à l'aide de conversations lancées par une application présente un exemple de définition de cet en-tête.

• Envoyez la demande POST à l'URL entrante du canal d'application. Elle doit ressembler à ceci :

  POST https://<host>:<port>/connectors/v2/listeners/application/channels/4E09-42F7-ECB7A7F18F62

Vous aurez besoin du nom du canal de système et de l'ID utilisateur de la prévisualisation pour envoyer les messages de votre application externe à la prévisualisation. Lorsqu'une application externe envoie un message au canal de système, Oracle Digital Assistant achemine le message à la prévisualisation dont l'ID utilisateur est spécifié.

1. Pour obtenir le nom du canal de système, cliquez sur Channels, puis sur System et regardez le nom.

   Le nom sera System_Bot_Test ou System_Global_Test.

2. Pour obtenir l'ID utilisateur de la prévisualisation, ouvrez la compétence et cliquez sur Preview (Prévisualiser) .

3. Ouvrez le moniteur réseau en sélectionnant d'abord Web Developer (Développeur Web) dans le menu du navigateur, puis cliquez sur Network (Réseau).

4. Sélectionnez XHR pour n'afficher que les demandes REST.

5. Entrez un message dans la prévisualisation.

6. Lorsque la compétence génère du texte, accédez au moniteur réseau et consultez l'onglet Response (Réponse).

   Sélectionnez chaque réponse jusqu'à ce que vous en trouviez une contenant des données utiles messagePayload.

7. Entrez userId dans le champ Filter Properties (Propriétés de filtrage) pour afficher la valeur pour userId.

8. Laissez la prévisualisation active et ne cliquez pas sur Reset (Réinitialiser).

   Si vous réinitialisez ou fermez la prévisualisation, l'ID utilisateur change.

Après avoir reçu le nom du canal de système et l'ID utilisateur du système, vous pouvez envoyer des messages depuis votre application externe à la prévisualisation de la compétence.

Pour utiliser la prévisualisation plutôt que le service de messagerie, réglez userId à l'ID utilisateur de celle-ci et channelName au nom du canal de système, comme ci-après :

{
    "userId": "7319408",
    "messagePayload": {
        "type": "application",
        "payloadType": "msgReminder",
        "channelName": "System_Global_Test",
        "variables": {
        	"patientName": "Joe Doe",
        	"appointmentTime": "5:00 pm"
        }
    }
}