Une conversation lancée par l'application commence lorsqu'une application externe envoie un événement à la brique ou à l'assistant numérique auquel elle appartient. Vous devez apporter quelques modifications à votre brique pour que la conversation commence au bon endroit et affiche les valeurs souhaitées.

Un événement envoyé à partir d'une application externe doit inclure un type de charge utile, qui identifie de manière unique l'événement auprès de la brique. En général, le type de charge utile indique ce que la brique est censée faire, par exemple msgReminder ou cancelAppointment. L'événement peut également inclure des paramètres dans son objet JSON variables, comme le nom d'un patient ou une heure de rendez-vous.

Dans votre brique, vous devez vous assurer qu'il existe un état de démarrage dans le flux de dialogue pour chaque événement (plusieurs événements peuvent avoir le même état de démarrage). Vous devez également ajouter des variables de niveau flux pour conserver les valeurs de paramètre, le cas échéant. Vous devez ensuite mettre en correspondance le type de charge utile de l'événement avec l'état de démarrage.

Pour chaque événement, procédez comme suit :

1. Si l'application externe transmet un objet variables dans la charge utile du message de l'événement, ajoutez des variables de niveau flux qui contiendront les valeurs des propriétés de l'objet.

   Le nom de la variable de niveau flux doit correspondre au nom de la propriété dans l'objet variables. Par exemple, si l'application externe envoie un corps de demande tel que le suivant 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. Vérifiez que le flux de dialogue comporte l'état de démarrage de l'événement.

   Conseil :

   Si la plate-forme de messagerie est de type texte uniquement, veillez à ce que la saisie utilisateur soit moins sujette aux erreurs en configurant la numérotation automatique dans le flux de dialogue de la brique. Vous pouvez également afficher ou masquer du texte selon la plate-forme de messagerie. Reportez-vous à Canaux avec du texte uniquement.

3. Pour mettre l'événement en correspondance avec l'état de démarrage, cliquez sur Paramètres , puis sur Evénements et sur + Ajouter une correspondance. Remplissez ensuite les champs suivants :

   • Type de charge utile : nom qui identifie de manière unique l'événement. L'application externe doit utiliser ce nom pour diriger le message vers l'état applicable.

     Utilisez le type de charge utile de l'application externe à la place du nom réel de l'état car le type de charge utile est une constante, tandis que le nom de l'état peut changer si la définition du flux de dialogue est révisée.

   • Nom d'état : état de démarrage de l'événement dans le flux de dialogue.

   Dans cette capture d'écran, le type de charge utile msgReminder correspond à l'état remindermessage dans le flux de dialogue.

   
   
   Description de l'image event-map.png
   

   Lorsque vous ajoutez une brique à un assistant numérique, les mises en correspondance d'événements et d'état de cette brique sont automatiquement ajoutés à la page Evénements de l'assistant numérique. Vous pouvez accéder à cette page à partir de la page Paramètres de l'assistant numérique.

Si votre brique exige 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 brique et l'application externe de sorte que la brique puisse associer l'ID utilisateur authentifié à l'ID utilisateur de bot.

Pour que les événements envoyés à une brique authentifiée par l'utilisateur fonctionnent, l'utilisateur doit s'être déjà connecté au fournisseur d'identités à partir de la brique. Par exemple, supposons que Deva utilise une brique pour créer une note de frais. Pour qu'elle puisse effectuer une tâche dans la brique, celle-ci l'invite à se connecter. La brique associe ensuite son ID utilisateur authentifié à son ID utilisateur pour la plate-forme de messagerie et les paramètres de plate-forme de messagerie qui sont mis en mémoire cache dans le profil de l'utilisateur.

Une fois la note de frais terminée, elle demande à recevoir une notification lorsque les dépenses seront approuvées. Elle utilise une application externe pour envoyer l'événement de notification à la même brique. Pour que l'application envoie l'événement à une brique 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. En fonction de l'ID utilisateur authentifié, la brique peut consulter l'ID utilisateur de la plate-forme et les informations issues du profil mis en cache, obtenues lors de la connexion initiale de Deva.

Si Deva ne s'est jamais connectée à partir de la brique, si son authentification a expiré ou si 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 Configuration de la brique, vous devez effectuer les étapes suivantes afin de configurer les conversations lancées par l'application pour les briques authentifiées par l'utilisateur :

1. Si votre brique a déjà activé l'authentification utilisateur, accédez à Paramètres > Services d'authentification, ouvrez le service et assurez-vous que l'option Durée de conservation du jeton d'actualisation est définie sur 14 jours, ce qui correspond à la durée d'expiration de la mémoire cache du profil utilisateur. Ces valeurs doivent être synchronisées.

2. Si votre brique n'a pas encore activé l'authentification utilisateur, procédez comme suit :

   1. Assurez-vous qu'un administrateur a effectué les étapes décrites dans Inscription de 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 l'option Durée de conservation du jeton d'actualisation du service d'authentification est définie sur 14 jours, ce qui correspond à la durée d'expiration de la mémoire cache du profil utilisateur. Ces valeurs doivent être synchronisées.

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

3. Lorsque vous créez le canal d'application, activez l'option Utiliser l'ID utilisateur authentifié. Sinon, s'il a déjà été créé, ouvrez le canal et activez l'option.

Dans le corps du texte que votre application externe envoie à Digital Assistant, n'oubliez pas de définir la propriété userId sur l'ID utilisateur authentifié, tel que décrit dans Configuration de l'application externe.

Pour que les conversations lancées par l'application fonctionnent, vous devez créer un canal utilisateur afin de lier la brique à votre compte de plate-forme de messagerie. Reportez-vous à ces rubriques afin de connaître la procédure de création d'un canal utilisateur pour la plate-forme spécifique.

• Twilio/SMS
• Slack
• Microsoft Teams

Si vous sélectionnez une brique dans la liste Acheminer vers du canal, tous les messages d'application externe envoyés à ce canal sont acheminés vers la brique sélectionnée. Toutefois, si vous sélectionnez un assistant numérique, vous devrez spécifier la brique cible dans la charge utile de message de l'application externe.

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

1. Dans la barre de navigation de gauche, cliquez sur Canaux, puis sur Applications et sur + Configuration de l'application.

2. Entrez un nom et, éventuellement, une description.

3. (Facultatif) Tous les messages d'erreur relatifs au canal sont consignés dans le fichier journal du serveur. Si vous voulez également que Digital Assistant envoie ces messages d'erreur à un service Web externe, saisissez l'URL du service Web dans le champ URL d'application sortante.

   Si une erreur se produit, comme un problème de lancement d'une conversation via le canal utilisateur, Digital Assistant envoie un message d'erreur sous forme d'objet JSON avec les propriétés botId, sessionId et message.

4. (Facultatif) Si la brique cible requiert une authentification à l'aide du composant Lien de compte OAuth 2.0 et si votre application externe envoie l'ID utilisateur authentifié à la place de l'ID utilisateur de la plate-forme de messagerie, activez l'option 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é. L'utilisateur doit s'être connecté via la brique afin que la recherche aboutisse. Pour plus d'informations, reportez-vous à Configuration d'une brique authentifiée par l'utilisateur.

5. Cliquez sur Créer.

6. Activez l'option Application activée.

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

   • Elle envoie des messages en envoyant une demande POST à l'URL entrante.
   • Elle utilise la clé secrète pour authentifier ses demandes POST.

Si votre brique prend en charge les conversations lancées par l'application et si vous l'ajoutez à un assistant numérique, vous devrez peut-être ajuster ces paramètres de configuration sur la page Paramètres de l'assistant numérique :

• Invite d'interruption : cette invite s'affiche lors de l'interruption d'un flux pour démarrer un nouveau flux.
• Activer la numérotation automatique sur les actions de postback : il est recommandé de s'assurer que ce paramètre a la valeur true pour tous les canaux de texte uniquement, de sorte que l'entrée utilisateur soit moins sujette aux erreurs. Par défaut, ce paramètre est défini sur 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. Voici les actions que l'application doit effectuer pour préparer et envoyer la demande.

• Incluez ces propriétés dans le corps de la demande (vous trouverez des exemples ci-dessous) :

  • userId : il doit s'agir de l'un des ID suivants :

    • ID utilisateur Microsoft Bot : ID utilisateur de bot pour le canal Microsoft Bot. Cet ID est propre à chaque canal Microsoft Bot. La brique enregistre cette valeur dans la variable profile.msBotUserId.

    • ID utilisateur Slack : ID de membre de l'utilisateur Slack. La brique enregistre cette valeur dans system.message.channelConversation.userId.

    • ID de canal Twilio/SMS : numéro de téléphone mobile de l'utilisateur. Il doit s'agir de l'un des numéros associés au numéro de téléphone du compte Twilio indiqué dans la configuration des canaux utilisateur de Digital Assistant. La brique enregistre cette valeur dans la variable profile.firstName.

    • ID utilisateur généré par le système : si vous testez votre brique à partir de l'aperçu, il doit s'agir de l'ID utilisateur généré par le système pour la session dans l'aperçu. Reportez-vous à Test des conversations lancées par l'application à partir de l'aperçu.

    • ID utilisateur authentifié : si l'option Utiliser l'ID utilisateur authentifié est activée pour le canal d'application associé, ce paramètre doit correspondre à l'ID utilisateur authentifié. L'utilisateur ayant cet ID utilisateur authentifié doit déjà être connecté à la brique cible via le composant Lien de compte OAuth 2.0. Reportez-vous à Configuration d'une brique authentifiée par l'utilisateur.

  • messagePayload : cet objet contient les éléments suivants :

    • type : définissez cette option sur application.

    • payloadType : nom de l'événement (type de charge utile) mis en correspondance avec l'état de démarrage souhaité dans le flux de dialogue. Reportez-vous à Configuration de la brique.

    • skillName et version : (facultatif) Si le canal utilisateur de la plate-forme de messagerie achemine les données vers un assistant numérique, vous devez inclure les options skillName et version de la brique pour que l'assistant numérique reconnaisse la brique et la version auxquelles l'événement doit être envoyé.

    • channelName : nom du canal utilisateur de la plate-forme de messagerie configuré pour la brique ou l'assistant numérique.

      Si vous testez votre brique à l'aide de l'aperçu, vous devez définir channelName sur le nom du canal système. Reportez-vous à Test des conversations lancées par l'application à partir de l'aperçu.

    • 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 remplies avec les valeurs transmises à partir de 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 Utiliser l'ID utilisateur authentifié est activée pour le canal utilisateur.

    Objet channelProperties MS Teams

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

    • botName : il s'agit du descripteur de bot que vous avez indiqué lors de la création de l'inscription de canal de bot comme décrit dans Etape 1 : création d'un bot. 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 de service du bot. Cette valeur est enregistrée dans la variable profile.serviceUrl.

    Lorsque l'utilisateur de Microsoft Teams a une conversation avec la brique, Digital Assistant capture et stocke ces valeurs dans le cache du profil. Si la charge utile de demande d'un événement n'inclut pas l'objet channelProperties, la brique utilisera les valeurs du cache de profils, si disponible (le cache expire au bout de 14 jours). La brique utilise les valeurs de profil mises en cache uniquement si elles ne se trouvent pas dans le corps de la demande.

    Lorsque le flux de dialogue envoie une demande de notification au back-end, par exemple via un composant personnalisé, il doit transmettre ces valeurs de profil au back-end. L'application externe peut alors utiliser ces valeurs dans l'objet channelProperties si le cache de profils a expiré. Voici un fragment de code de composant personnalisé qui obtient les valeurs à renvoyer au back-end.

        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 ces propriétés dans l'objet channelProperties :

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

    • channel : ID du canal dans l'espace de travail. Il s'agit du canal de l'utilisateur. Cette valeur est enregistrée dans la variable profile.channel.

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

  Voici des exemples des différentes plates-formes de messagerie pour les briques qui n'utilisent pas des ID d'utilisateur authentifié.

  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 acheminé vers un assistant numérique. Lorsque le canal achemine vers un assistant numérique, vous devez inclure le nom et la version de la brique.

  {
      "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 pour une brique authentifiée par l'utilisateur (autrement dit, avec l'option Utiliser l'ID utilisateur authentifié activée pour le canal d'application associé). Cet exemple s'applique à MS Teams, à Slack et à Twilio . Pour MS Teams et Slack, n'incluez pas l'objet channelProperties en cas d'acheminement vers une brique 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 un 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 l'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 apparaître comme suit :

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

Vous aurez besoin du nom de canal système et de l'ID utilisateur de l'aperçu pour envoyer les messages de votre application externe à l'aperçu. Lorsqu'une application externe envoie un message au canal système, Oracle Digital Assistant achemine le message vers l'aperçu ayant l'ID utilisateur indiqué.

1. Pour obtenir le nom du canal système, dans la barre de navigation de gauche, cliquez sur Canaux, puis sur Système et consultez le nom.

   Il s'agit de System_Bot_Test ou de System_Global_Test.

2. Pour obtenir l'ID utilisateur de l'aperçu, ouvrez la brique et cliquez sur Aperçu .

3. Ouvrez la surveillance réseau en sélectionnant Développeur Web dans le menu du navigateur, puis en cliquant sur Réseau.

4. Sélectionnez XHR pour afficher uniquement les demandes REST.

5. Saisissez un message dans l'aperçu.

6. Une fois que la brique a généré un texte, accédez à la surveillance réseau, puis consultez l'onglet Réponse.

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

7. Entrez userId dans le champ Propriétés de filtre pour afficher la valeur de userId.

8. Laissez l'aperçu actif et ne cliquez pas sur Réinitialiser.

   Si vous réinitialisez ou fermez l'aperçu, l'ID utilisateur change.

Après avoir obtenu le nom du canal système et l'ID utilisateur du système, vous pouvez envoyer des messages à partir de votre application externe vers l'aperçu de la brique.

Pour utiliser l'aperçu à la place du service de messagerie, définissez userId sur l'ID utilisateur de l'aperçu et channelName sur le nom du canal système, comme indiqué ici :

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