Eine von der Anwendung initiierte Unterhaltung beginnt, wenn eine externe App ein Ereignis an den Skill oder an den digitalen Assistenten sendet, zu dem sie gehört. Sie müssen einige Änderungen am Skill vornehmen, damit die Unterhaltung an der richtigen Stelle beginnt und die gewünschten Werte angezeigt werden.

Ein Ereignis, das von einer externen App gesendet wird, muss einen Payload-Typ enthalten, der das Ereignis für den Skill eindeutig identifiziert. In der Regel gibt der Payload-Typ an, welche Aktion der Skill ausführen soll, wie msgReminder oder cancelAppointment. Das Ereignis kann auch Parameter im zugehörigen JSON-Objekt variables enthalten, z.B. den Namen oder die Uhrzeit des Termins eines Patienten.

In Ihrem Skill müssen Sie sicherstellen, dass ein Startstatus im Dialogablauf für jedes Ereignis vorhanden ist (mehrere Ereignisse können denselben Startstatus aufweisen). Sie müssen außerdem Variablen auf Flow-Ebene hinzufügen, die gegebenenfalls die Parameterwerte enthalten. Danach müssen Sie den Payload-Typ des Ereignisses dem Startstatus zuordnen.

Führen Sie für jedes Ereignis die folgenden Schritte aus:

1. Wenn Ihre externe App ein variables-Objekt in der Nachrichten-Payload des Ereignisses übergibt, fügen Sie Variablen auf Ablaufebene hinzu, um die Werte der Objekteigenschaften zu speichern.

   Der Variablenname auf Flussebene muss mit dem Eigenschaftsnamen im Objekt variables übereinstimmen. Beispiel: Die externe App sendet einen Anforderungstext wie bei einem Terminerinnerungsereignis:

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

2. Stellen Sie sicher, dass der Dialogablauf einen Anfangsstatus für das Ereignis hat.

   Tipp:

   Wenn es sich bei der Messagingplattform um einen Nur-Text-Kanal handelt, ist es sinnvoll, die Benutzereingabe weniger fehleranfällig zu gestalten, indem Sie die automatische Nummerierung im Dialogablauf des Skills konfigurieren. Außerdem sollten Sie Text basierend auf der Messagingplattform ein- oder ausblenden. Siehe Nur-Text-Kanäle.

3. Um das Ereignis dem Startstatus zuzuordnen, klicken Sie auf Einstellungen , Ereignisse, + Zuordnung hinzufügen. Füllen Sie anschließend die folgenden Felder aus:

   • Payload-Typ: Ein Name, der das Ereignis eindeutig identifiziert. Die externe App muss diesen Namen verwenden, um die Nachricht an den entsprechenden Status weiterzuleiten.

     Verwenden Sie den Payload-Typ aus der externen App und nicht den eigentlichen Statusnamen, da der Payload-Typ eine Konstante ist. Der Name des Status kann sich dagegen ändern, wenn der Dialogablauf überarbeitet wird.

   • Statusname: Der Startstatus für das Ereignis im Dialogablauf.

   In diesem Screenshot wird der Payload-Typ msgReminder dem Status remindermessage im Dialogablauf zugeordnet.

   
   
   Beschreibung der Abbildung event-map.png
   

   Wenn Sie einem digitalen Assistenten einen Skill hinzufügen, werden die Ereignis-zu-Status-Zuordnungen des Skills automatisch zur Seite "Ereignisse" des digitalen Assistenten hinzugefügt. Sie können diese Seite aus der Seite Einstellungen des digitalen Assistenten aufrufen.

Wenn Ihr Skill erfordert, dass Benutzer sich bei Oracle Identity Cloud Service oder Oracle Access Manager authentifizieren, müssen Sie den Anwendungskanal, den Skill und die externe App so konfigurieren, dass der Skill die authentifizierte Benutzer-ID mit der Botbenutzer-ID verknüpfen kann.

Bei Ereignissen, die an einen vom Benutzer authentifizierten Skill gesendet werden, muss der Benutzer sich bereits vom Skill beim Identitätsprovider angemeldet haben. Beispiel: Angenommen, Deva verwendet einen Skill, um eine Spesenabrechnung zu erstellen. Bevor sie eine Aktion im Skill ausführen kann, wird sie aufgefordert, sich anzumelden. Der Skill verknüpft dann ihre authentifizierte Benutzer-ID mit ihrer Benutzer-ID für die Messagingplattform und die Messagingplattformparameter, die im Profil des Benutzers gecacht sind.

Nach Abschluss der Abrechnung bittet sie um Benachrichtigung, wenn die Spesen genehmigt sind. Ihr Unternehmen verwendet eine externe App, um das Benachrichtigungsereignis an denselben Skill zu senden. Damit die App das Ereignis an einen vom Benutzer authentifizierten Skill senden kann, muss die authentifizierte Benutzer-ID von Deva anstelle der Benutzer-ID der Messagingplattform gesendet werden. Anhand der authentifizierten Benutzer-ID kann der Skill die Benutzer-ID der Plattform und die Informationen aus dem gecachten Profil suchen, die er abgerufen hat, als sie Deva sich ursprünglich angemeldet hat.

Wenn Deva sich nie aus dem Skill angemeldet hat, ihre Authentifizierung abgelaufen ist oder der Profilcache abgelaufen ist, reagiert Digital Assistant mit einem 500-Fehler auf die Ereignisanforderung.

Neben den Schritten unter Skill konfigurieren müssen Sie die folgenden Schritte ausführen, um von Anwendungen initiierte Unterhaltungen für vom Benutzer authentifizierte Skills zu konfigurieren:

1. Wenn Ihr Skill die Benutzerauthentifizierung bereits aktiviert hat, gehen Sie zu Einstellungen > Authentifizierungsservices, öffnen Sie den Service, und stellen Sie sicher, dass Aktualisierungstoken-Aufbewahrungszeitraum auf 14 Tage gesetzt ist, entsprechend der Ablaufdauer des Benutzerprofilcaches. Diese Werte müssen synchronisiert werden.

2. Wenn der Skill die Benutzerauthentifizierung noch nicht aktiviert hat, führen Sie die folgenden Schritte aus:

   1. Stellen Sie sicher, dass ein Administrator die Schritte unter Identitätsproviderregistrierung ausgeführt hat.

   2. Erstellen Sie einen Authentifizierungsservice für den Identitätsprovider, wie unter Authentifizierungsservices beschrieben.

   3. Stellen Sie sicher, dass der Aktualisierungstoken-Aufbewahrungszeitraum des Authentifizierungsservice auf 14 Tage gesetzt ist, entsprechend der Ablaufdauer des Benutzerprofilcaches. Diese Werte müssen synchronisiert werden.

   4. Um Benutzern die Anmeldung über den Skill zu ermöglichen, fügen Sie dem Dialogablauf einen Status für die Accountlinkkomponente OAuth 2.0 hinzu, wie unter OAuth 2.0-Accountlink beschrieben.

3. Wenn Sie den Anwendungskanal erstellen, setzen Sie Authentifizierte Benutzer-ID verwenden auf "Ein". Wenn der Kanal bereits erstellt wurde, öffnen Sie ihn, und setzen Sie ihn auf "Ein".

Denken Sie daran, im Anforderungsbody, den die externe App an den Digital Assistant sendet, die Eigenschaft userId auf die authentifizierte Benutzer-ID zu setzen, wie unter Externe App konfigurieren beschrieben.

Damit von Anwendungen initiierte Unterhaltungen funktionieren, müssen Sie einen Benutzerkanal erstellen, um den Skill mit Ihrem Messagingplattformaccount zu verknüpfen. In diesen Themen werden die Schritte beschrieben, mit denen Sie einen Benutzerkanal für die spezifische Plattform erstellen.

• Twilio/SMS
• Slack
• Microsoft Teams

Hinweis: Wenn Sie einen Skill in der Liste Weiterleiten an des Kanals auswählen, werden alle an diesen Kanal gesendeten externen App-Nachrichten an den ausgewählten Skill weitergeleitet. Wenn Sie jedoch einen digitalen Assistenten auswählen, müssen Sie den Zielskill in der Nachrichten-Payload der externen App angeben.

Sie müssen einen Anwendungskanal erstellen, damit die externe App Nachrichten an Digital Assistant senden kann. Nachdem Sie den Kanal erstellt haben, weist Digital Assistant einen Secret Key zu. Sie müssen diesen Secret Key in Ihrer externen App verwenden.

1. Klicken Sie in der linken Navigationsleiste auf Kanäle, Anwendungen, + Anwendungskonfiguration.

2. Geben Sie einen Namen und optional eine Beschreibung ein.

3. (Optional) Alle zum Kanal gehörenden Fehlermeldungen werden in der Serverlogdatei protokolliert. Wenn Sie möchten, dass Digital Assistant diese Fehlermeldungen auch an einen externen Webservice sendet, geben Sie die URL des Webservice in das Feld URL der ausgehenden Anwendung ein.

   Wenn ein Fehler auftritt, wie beispielsweise ein Problem beim Initiieren einer Unterhaltung über den Benutzerkanal, sendet Digital Assistant eine Fehlermeldung als JSON-Objekt mit den Eigenschaften botId, sessionId und message.

4. (Optional) Wenn der gezielte Skill eine Authentifizierung mit der Komponente "Accountlink" der Version OAuth 2.0 erforderlich ist und Ihre externe App die authentifizierte Benutzer-ID anstelle der Benutzer-ID der Messagingplattform sendet, aktivieren Sie Authentifizierte Benutzer-ID verwenden.

   Wenn diese Option aktiviert ist, sucht Digital Assistant nach der Benutzer-ID der Messagingplattform für die angegebene authentifizierte Benutzer-ID. Beachten Sie, dass sich der Benutzer über den Skill angemeldet haben muss, damit die Suche erfolgreich abgeschlossen werden kann. Weitere Informationen finden Sie unter Vom Benutzer authentifizierten Skill konfigurieren.

5. Klicken Sie auf Erstellen.

6. Aktivieren Sie das Steuerelement Anwendung aktiviert.

7. Notieren Sie den Secret Key und die eingehende URL. Diese werden von der externen App verwendet.

   • Sie sendet Nachrichten, indem eine POST-Anforderung an die eingehende URL gesendet wird.
   • Sie verwendet den Secret Key zur Authentifizierung ihrer POST-Anforderungen.

Wenn Ihr Skill von Anwendungen initiierte Unterhaltungen unterstützt und Sie ihn einem digitalen Assistenten hinzufügen, sollten Sie diese Konfigurationsparameter auf der Einstellungsseite des digitalen Assistenten anpassen:

• Unterbrechungsaufforderung: Diese Aufforderung wird angezeigt, wenn ein Ablauf unterbrochen wird, um einen neuen Ablauf zu starten.
• Automatische Nummerierung bei Postback-Aktionen aktivieren: Es empfiehlt sich, diese Einstellung für alle Nur-Text-Kanäle auf true zu setzen, damit die Benutzereingabe weniger fehleranfällig ist. Standardmäßig ist diese Einstellung für alle Twilio-Kanäle true: ${(system.channelType=='twilio')?then('true','false')}

Die externe App initiiert ein Ereignis, indem eine POST-Anforderung an die eingehende URL eines Anwendungskanals gesendet wird. Im Folgenden werden die Aktionen aufgeführt, die die App ausführen muss, um die Anforderung vorzubereiten und zu senden.

• Nehmen Sie diese Eigenschaften in den Anforderungsbody auf (Beispiele folgen):

  • userId: Dies muss eine der folgenden IDs sein:

    • Microsoft-Botbenutzer-ID: Die Botbenutzer-ID für den Microsoft-Botkanal. Diese ID ist für jeden Microsoft-Botkanal spezifisch. Der Skill speichert diesen Wert in der Variable profile.msBotUserId.

    • Slack-Benutzer-ID: Die Mitglieds-ID des Slack-Benutzers. Der Skill speichert diesen Wert in system.message.channelConversation.userId.

    • Twilio-/SMS-Kanal-ID: Die Mobiltelefonnummer des Benutzers. Dies muss eine der Nummern sein, die mit der Telefonnummer des Twilio-Accounts verknüpft sind, die in der Konfiguration des Benutzerkanals in Digital Assistant angegeben ist. Der Skill speichert diesen Wert in der Variable profile.firstName.

    • Vom System generierte Benutzer-ID: Wenn Sie Ihren Skill in der Vorschau testen, muss dieser Wert die vom System generierte Benutzer-ID für die Session in der Vorschau sein. Siehe Von Anwendungen initiierte Unterhaltungen in der Vorschau testen.

    • Authentifizierte Benutzer-ID: Wenn im zugehörigen Anwendungskanal die Einstellung Authentifizierte Benutzer-ID verwenden aktiviert ist, muss dies die authentifizierte Benutzer-ID sein. Der Benutzer mit dieser authentifizierten Benutzer-ID muss bereits über die Komponente "Accountlink" der Version OAuth 2.0 beim Zielskill angemeldet sein. Siehe Vom Benutzer authentifizierten Skill konfigurieren.

  • messagePayload: Dieses Objekt enthält:

    • type: Setzen Sie diesen Wert auf application.

    • payloadType: Der Name des Ereignisses (Payload-Typ), das dem gewünschten Startstatus im Dialogablauf zugeordnet ist. Siehe Skill konfigurieren.

    • skillName und version: (Optional) Wenn der Benutzerkanal der Messagingplattform Ereignisse an einen digitalen Assistenten weiterleitet, müssen Sie die Werte skillName und version des Skills einschließen, damit der digitale Assistent weiß, an welchen Skill und welche Version das Ereignis gesendet werden soll.

    • channelName: Der Name des Benutzerkanals der Messagingplattform, der für den Skill oder den digitalen Assistenten konfiguriert ist.

      Wenn Sie Ihren Skill über die Vorschau testen, müssen Sie channelName auf den Namen des Systemkanals setzen. Siehe Von Anwendungen initiierte Unterhaltungen in der Vorschau testen.

    • variables: (Optional) Schlüsselwertpaare, die an die Variablen des Dialogablaufs übergeben werden. Wenn die entsprechenden Flussvariablen im Dialogablauf definiert sind, werden sie mit den Werten aufgefüllt, die von diesem Objekt übergeben werden.

  • channelProperties: Dieses Objekt ist für MS Teams und Slack bestimmt. Sie müssen dieses Objekt nicht in den Anforderungsbody aufnehmen, wenn Authentifizierte Benutzer-ID verwenden für den Benutzerkanal aktiviert ist.

    MS Teams-Objekt channelProperties

    Dieses Objekt ist erforderlich, wenn der Benutzer in den letzten 14 Tagen nicht mit der Unterhaltung interagiert hat. Eigenschaften:

    • botName: Das Bot-Handle, das Sie beim Erstellen der Registrierung des Botkanals angegeben haben, wie unter Schritt 1: Bot erstellen beschrieben. Dieser Wert wird in der Variable profile.botName gespeichert.

    • tenantId: Die ID des Microsoft Teams-Mandanten. Dieser Wert wird in der Variable profile.tenantId gespeichert.

    • serviceUrl: Die Service-URL für den Bot. Dieser Wert wird in der Variable profile.serviceUrl gespeichert.

    Wenn der Microsoft Teams-Benutzer mit dem Skill kommuniziert, erfasst und speichert Digital Assistant diese Werte im Profilcache. Wenn die Anforderungs-Payload eines Ereignisses das Objekt channelProperties nicht enthält, verwendet der Skill die Werte aus dem Profilcache, sofern verfügbar (der Cache läuft nach 14 Tagen ab). Der Skill verwendet die gecachten Profilwerte nur, wenn sie im Anforderungsbody fehlen.

    Wenn der Dialogablauf eine Benachrichtigungsanforderung an das Backend sendet, wie durch eine benutzerdefinierte Komponente, sollten diese Profilwerte an das Backend übergeben werden. Die externe App kann diese Werte dann im Objekt channelProperties verwenden, falls der Profilcache abgelaufen ist. Im Folgenden finden Sie ein Snippet des benutzerdefinierten Komponentencodes, der die an das Backend zu sendenden Werte abruft.

        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') : "";

    Slack-Objekt channelProperties

    Nehmen Sie für Slack die folgenden Eigenschaften in das Objekt channelProperties auf:

    • teamId: ID für Slack-Workspace. Dieser Wert wird in der Variable profile.team_id gespeichert.

    • channel: ID des Kanals im Workspace. Das heißt, der Kanal des Benutzers. Dieser Wert wird in der Variable profile.channel gespeichert.

    Sie können die Team-ID und den Kanal aus der Slack-Web-URL abrufen. Beispiel: Wenn die URL https://app.slack.com/client/ABCDEFG/HIJKLMNOP lautet, ist die Team-ID ABCDEFG und der Kanal HIJKLMNOP.

  Beispiele für die verschiedenen Messagingplattformen für Skills, die keine authentifizierten Benutzer-IDs verwenden:

  Slack-Beispiel:

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

  MS Teams-Beispiel:

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

  Twilio-Beispiel:

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

  Dieses Beispiel zeigt, wie ein Ereignis an einen Kanal gesendet wird, der an einen digitalen Assistenten weitergeleitet wird. Wenn der Kanal an einen digitalen Assistenten weitergeleitet wird, müssen Sie den Namen und die Version des Skills angeben.

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

  Im Folgenden finden Sie ein Beispiel für einen vom Benutzer authentifizierten Skill (d.h. für den zugehörigen Anwendungskanal ist Authentifizierte Benutzer-ID verwenden aktiviert). Dieses Beispiel gilt für MS Teams, Slack und Twilio. Beachten Sie, dass Sie für MS Teams und Slack das Objekt channelProperties nicht einschließen, wenn Sie zu einem vom Benutzer authentifizierten Skill weiterleiten.

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

• Um die Anforderung zu authentifizieren, fügen Sie einen X-Hub-Signature-Header mit einem SHA256-Hashwert für den Body mit dem Secret Key des Anwendungskanals hinzu. Beispiel:

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

  Im Abschnitt Postman als externe Anwendung verwenden im Tutorial Erinnerungen mit von Anwendungen initiierten Unterhaltungen senden wird ein Beispiel für das Festlegen dieses Headers gezeigt.

• Senden Sie die POST-Anforderung an die eingehende URL des Anwendungskanals. Dies sollte in etwa wie folgt aussehen:

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

Sie benötigen den Systemkanalnamen und die Benutzer-ID der Vorschau, um die Nachrichten der externen App an die Vorschau zu senden. Wenn eine externe App eine Nachricht an den Systemkanal sendet, leitet Oracle Digital Assistant die Nachricht an die Vorschau mit der angegebenen Benutzer-ID weiter.

1. Um den Namen des Systemkanals abzurufen, klicken Sie in der linken Navigationsleiste auf Kanäle, System, und prüfen Sie den Namen.

   Der Name ist entweder System_Bot_Test oder System_Global_Test.

2. Um die Benutzer-ID der Vorschau abzurufen, öffnen Sie den Skill, und klicken Sie auf Vorschau .

3. Öffnen Sie den Netzwerkmonitor, indem Sie zunächst Web Developer im Browsermenü auswählen und dann auf Netzwerk klicken.

4. Wählen Sie XHR aus, um nur REST-Anforderungen anzuzeigen.

5. Geben Sie eine Nachricht in die Vorschau ein.

6. Gehen Sie zum Netzwerkmonitor, nachdem der Skill etwas Text ausgegeben hat, und prüfen Sie die Registerkarte Antwort.

   Gehen Sie die Antworten durch, bis Sie eine Antwort finden, die messagePayload enthält.

7. Geben Sie userId im Feld Filtereigenschaften ein, um den Wert für userId anzuzeigen.

8. Lassen Sie die Vorschau aktiv, und klicken Sie nicht auf Zurücksetzen.

   Wenn Sie die Vorschau zurücksetzen oder schließen, ändert sich die Benutzer-ID.

Nachdem Sie den Namen des Systemkanals und die Benutzer-ID des Systems abgerufen haben, können Sie Nachrichten von Ihrer externen App an die Skillvorschau senden.

Um die Vorschau anstelle des Messagingservice zu verwenden, setzen Sie userId auf die Benutzer-ID der Vorschau, und setzen Sie channelName auf den Namen des Systemkanals, wie hier dargestellt:

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