Una conversazione avviata dall'applicazione inizia quando un'applicazione esterna invia un evento allo skill o all'assistente digitale a cui appartiene. È necessario apportare alcune modifiche alle proprie abilità in modo che la conversazione inizi nel posto giusto e visualizzi i valori desiderati.

Un evento inviato da un'applicazione esterna deve includere un tipo di payload che identifica in modo univoco l'evento per lo skill. In genere, il tipo di payload indica l'azione prevista per lo skill, ad esempio msgReminder o cancelAppointment. L'evento può inoltre includere parametri nel relativo oggetto JSON variables, ad esempio il nome di un paziente o l'ora di un appuntamento.

Nella propria abilità, è necessario assicurarsi che nel flusso della finestra di dialogo sia presente uno stato iniziale per ogni evento (gli eventi multipli possono avere lo stesso stato iniziale). È inoltre necessario aggiungere variabili a livello di flusso per contenere i valori dei parametri, se presenti. È quindi necessario mappare il tipo di payload dell'evento allo stato iniziale.

Per ogni evento, effettuare le operazioni riportate di seguito.

1. Se l'applicazione esterna passerà un oggetto variables nel payload dei messaggi dell'evento, aggiungere variabili a livello di flusso per contenere i valori delle proprietà dell'oggetto.

   Il nome della variabile a livello di flusso deve corrispondere al nome della proprietà nell'oggetto variables. Si supponga, ad esempio, che l'applicazione esterna invii un corpo di richiesta come questo per un evento di promemoria appuntamento:

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

2. Assicurarsi che il flusso della finestra di dialogo abbia uno stato iniziale per l'evento.

   Suggerimento

   Se la piattaforma di messaggistica è di solo testo, considerare la possibilità di rendere l'input utente meno soggetto a errori configurando la numerazione automatica nel flusso della finestra di dialogo dello skill. Considera anche di mostrare o nascondere il testo in base alla piattaforma di messaggistica. Vedere Canali di solo testo.

3. Per mappare l'evento allo stato iniziale, fare clic su Impostazioni , fare clic su Eventi e quindi su + Aggiungi mapping. Immettere quindi questi campi:

   • Tipo di payload: nome che identifica in modo univoco l'evento. L'applicazione esterna deve utilizzare questo nome per indirizzare il messaggio allo stato applicabile.

     Il tipo di payload viene utilizzato dall'applicazione esterna anziché dal nome di stato effettivo perché il tipo di payload è una costante, mentre il nome dello stato potrebbe cambiare se il flusso della finestra di dialogo viene rivisto.

   • Nome stato: lo stato iniziale dell'evento nel flusso della finestra di dialogo.

   In questo screenshot il tipo di payload msgReminder viene mappato allo stato remindermessage nel flusso della finestra di dialogo.

   
   
   Descrizione dell'immagine evento-map.png
   

   Quando si aggiunge uno skill a un assistente digitale, i mapping tra eventi e stati dello skill vengono aggiunti automaticamente alla pagina Eventi dell'assistente digitale. È possibile accedere a questa pagina dalla pagina Impostazioni dell'assistente digitale.

Se la competenza richiede agli utenti di eseguire l'autenticazione con Oracle Identity Cloud Service o Oracle Access Manager, è necessario configurare il canale dell'applicazione, la competenza e l'applicazione esterna per abilitare la competenza per associare l'ID utente autenticato all'ID utente bot.

Affinché gli eventi inviati a uno skill autenticato dall'utente funzionino, l'utente deve aver già effettuato l'accesso al provider di identità dallo skill. Si supponga, ad esempio, che Deva stia utilizzando uno skill per creare una nota spese. Prima di poter fare qualsiasi cosa nell'abilità, l'abilità le chiede di accedere. Lo skill associa quindi il proprio ID utente autenticato al proprio ID utente per la piattaforma di messaggistica e ai parametri della piattaforma di messaggistica inseriti nella cache nel profilo dell'utente.

Dopo aver completato la nota, chiede di essere avvisata quando la spesa viene approvata. La società utilizza un'applicazione esterna per inviare l'evento di notifica allo stesso skill. Affinché l'app possa inviare l'evento a un'abilità autenticata dall'utente, deve inviare l'ID utente autenticato di Deva anziché l'ID utente della piattaforma di messaggistica. Dato l'ID utente autenticato, l'abilità può cercare l'ID utente della piattaforma e le informazioni dal profilo memorizzato nella cache ottenute quando Deva ha effettuato l'accesso in origine.

Se Deva non ha mai effettuato l'accesso dallo skill, l'autenticazione è scaduta o la cache del profilo è scaduta, Digital Assistant risponde alla richiesta di evento con un errore di 500.

Oltre ai passi descritti in Configura skill, è necessario completare i passi riportati di seguito per configurare le conversazioni avviate dall'applicazione per le competenze autenticate dall'utente.

1. Se lo skill ha già abilitato l'autenticazione utente, andare a Impostazioni > Servizi di autenticazione, aprire il servizio e assicurarsi che l'opzione Aggiorna periodo di conservazione token sia impostata su 14 giorni, corrispondente alla durata di scadenza della cache del profilo utente. È necessario sincronizzare questi valori.

2. Se lo skill non ha ancora abilitato l'autenticazione utente, attenersi alla procedura riportata di seguito.

   1. Assicurarsi che un amministratore abbia completato i passi in Registrazione provider di identità.

   2. Creare un servizio di autenticazione per il provider di identità come descritto in Authentication Services.

   3. Assicurarsi che l'opzione Aggiorna periodo di conservazione token del servizio di autenticazione sia impostata su 14 giorni, il che corrisponde alla durata di scadenza della cache del profilo utente. È necessario sincronizzare questi valori.

   4. Per consentire agli utenti di accedere dalla competenza, aggiungere uno stato per il componente Collegamento account OAuth 2.0 al flusso della finestra di dialogo, come descritto in OAuth 2.0 Collegamento account.

3. Quando si crea il canale dell'applicazione, impostare Usa ID utente autenticato su Attivo. In alternativa, se è già stato creato, aprire il canale e attivarlo.

Nel corpo della richiesta inviato dall'applicazione esterna a Digital Assistant, ricordarsi di impostare la proprietà userId sull'ID utente autenticato come descritto in Configura applicazione esterna.

Affinché le conversazioni avviate dall'applicazione funzionino, sarà necessario creare un canale utente per collegare la competenza all'account della piattaforma di messaggistica. Vedere questi argomenti per la procedura di creazione di un canale utente per la piattaforma specifica.

• Twilio/SMS
• Slack
• Microsoft Team

Tenere presente che se si seleziona uno skill dall'elenco Invia a del canale, tutti i messaggi dell'applicazione esterna inviati a questo canale vengono instradati allo skill selezionato. Tuttavia, se si seleziona un assistente digitale, sarà necessario specificare la competenza di destinazione nel payload dei messaggi dell'applicazione esterna.

È necessario creare un canale applicazione per consentire all'applicazione esterna di inviare messaggi a Digital Assistant. Dopo aver creato il canale, Digital Assistant assegna una chiave segreta. È necessario utilizzare questa chiave segreta nell'applicazione esterna.

1. Nella barra di navigazione a sinistra fare clic su Canali, fare clic su Applicazioni, quindi su + Configurazione applicazione.

2. Immettere un nome ed eventualmente una descrizione.

3. (Opzionale) Tutti i messaggi di errore correlati al canale vengono registrati nel file di log del server. Se si desidera che Digital Assistant invii anche questi messaggi di errore a un servizio Web esterno, immettere l'URL del servizio Web nel campo URL applicazione in uscita.

   Se si verifica un errore, ad esempio un problema durante l'avvio di una conversazione tramite il canale utente, Digital Assistant invia un messaggio di errore come oggetto JSON con le proprietà botId, sessionId e message.

4. (Facoltativo) Se la competenza di destinazione richiede l'autenticazione mediante il componente Collegamento account OAuth 2.0 e l'applicazione esterna invierà l'ID utente autenticato anziché l'ID utente della piattaforma di messaggistica, passare a Usa ID utente autenticato.

   Quando questa opzione è attivata, Digital Assistant cercherà l'ID utente della piattaforma di messaggistica per l'ID utente autenticato specificato. Tenere presente che l'utente deve aver eseguito l'accesso mediante lo skill per completare la ricerca. Per ulteriori dettagli, vedere Configurare uno skill autenticato dall'utente.

5. Fare clic su Crea.

6. Passare a Applicazione abilitata.

7. Prendere nota della chiave segreta e dell'URL in entrata. Questi verranno utilizzati dall'applicazione esterna.

   • Invia messaggi inviando una richiesta POST all'URL in entrata.
   • Utilizza la chiave segreta per autenticare le sue richieste POST.

Se la competenza supporta le conversazioni avviate dall'applicazione e le si aggiunge a un assistente digitale, è possibile modificare questi parametri di configurazione nella pagina Impostazioni dell'assistente digitale:

• Prompt di interruzione: questo prompt viene visualizzato quando si interrompe un flusso per avviare un nuovo flusso.
• Abilita numerazione automatica su azioni di postback: è buona norma assicurarsi che questa impostazione sia true per tutti i canali di solo testo in modo che l'input utente sia meno soggetto a errori. Per impostazione predefinita, questa impostazione è true per tutti i canali Twilio: ${(system.channelType=='twilio')?then('true','false')}

L'applicazione esterna avvia un evento inviando una richiesta POST all'URL in entrata del canale dell'applicazione. Ecco le cose che l'app deve fare per preparare e inviare la richiesta.

• Includere queste proprietà nel corpo della richiesta (esempi riportati di seguito).

  • userId: deve essere uno dei seguenti ID:

    • ID utente bot Microsoft: l'ID utente bot per il canale bot Microsoft. Questo ID è specifico per ogni canale Microsoft Bot. Lo skill salva questo valore nella variabile profile.msBotUserId.

    • ID utente Slack: l'ID membro dell'utente Slack. Lo skill salva questo valore in system.message.channelConversation.userId.

    • ID canale Twilio/SMS: il numero di cellulare dell'utente. Deve essere uno dei numeri associati al numero di telefono dell'account Twilio specificato nella configurazione del canale utente di Digital Assistant. Lo skill salva questo valore nella variabile profile.firstName.

    • ID utente generato dal sistema: se si sta eseguendo il test della competenza da Anteprima, questo deve essere l'ID utente generato dal sistema per la sessione in Anteprima. Vedere Test delle conversazioni avviate dall'applicazione dall'anteprima.

    • ID utente autenticato: se il canale dell'applicazione associato ha Usa ID utente autenticato attivato, deve essere l'ID utente autenticato. L'utente con questo ID utente autenticato deve essere già connesso all'abilità target tramite il componente Collegamento account OAuth 2.0. Vedere Configura una competenza autenticata dall'utente.

  • messagePayload: questo oggetto contiene:

    • type: impostare questa opzione su application.

    • payloadType: il nome dell'evento (tipo di payload) mappato allo stato iniziale desiderato nel flusso della finestra di dialogo. Vedere Configurazione della competenza.

    • skillName e version: (facoltativo) se il canale utente della piattaforma di messaggistica viene instradato a un assistente digitale, è necessario includere gli skill skillName e version in modo che l'assistente digitale sappia a quali competenze e versioni inviare l'evento.

    • channelName: il nome del canale utente della piattaforma di messaggistica configurato per lo skill o l'assistente digitale.

      Se si sta eseguendo il test della competenza da Anteprima, è necessario impostare channelName sul nome del canale di sistema. Vedere Test delle conversazioni avviate dall'applicazione dall'anteprima.

    • variables: (Opzionale) coppie chiave-valore da passare alle variabili del flusso della finestra di dialogo. Se le variabili di flusso corrispondenti sono definite nel flusso della finestra di dialogo, vengono popolate con i valori passati da questo oggetto.

  • channelProperties: questo oggetto è per MS Teams e Slack. Non è necessario includere questo oggetto nel corpo della richiesta se per il canale utente è attivata l'opzione Usa ID utente autenticato.

    Oggetto channelProperties MS Teams

    Questo oggetto è obbligatorio se l'utente non ha interagito con la conversazione entro 14 giorni. Le relative proprietà sono:

    • botName: si tratta dell'handle del bot specificato al momento della creazione della registrazione del canale del bot, come descritto nel Passo 1: Creare un bot. Questo valore viene salvato nella variabile profile.botName.

    • tenantId: l'ID del tenant di Microsoft Teams. Questo valore viene salvato nella variabile profile.tenantId.

    • serviceUrl: URL servizio per il bot. Questo valore viene salvato nella variabile profile.serviceUrl.

    Quando l'utente di Microsoft Teams conversa con la competenza, Digital Assistant acquisisce e memorizza questi valori nella cache del profilo. Se il payload della richiesta di un evento non include l'oggetto channelProperties, lo skill utilizzerà i valori della cache dei profili, se disponibili (la cache scade dopo 14 giorni). Lo skill utilizza i valori del profilo inseriti nella cache solo se mancano nel corpo della richiesta.

    Quando il flusso di finestre di dialogo invia una richiesta di notifica al backend, ad esempio tramite un componente personalizzato, deve passare tali valori del profilo al backend. L'applicazione esterna può quindi utilizzare tali valori nell'oggetto channelProperties nel caso in cui la cache del profilo sia scaduta. Di seguito è riportato uno snippet di codice componente personalizzato che recupera i valori da inviare al backend.

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

    Oggetto channelProperties Slack

    Per Slack, includere queste proprietà nell'oggetto channelProperties:

    • teamId: ID area di lavoro Slack. Questo valore viene salvato nella variabile profile.team_id.

    • channel: l'ID del canale nell'area di lavoro. Cioè, il canale dell'utente. Questo valore viene salvato nella variabile profile.channel.

    È possibile ottenere l'ID e il canale del team dall'URL Web Slack. Ad esempio, se l'URL è https://app.slack.com/client/ABCDEFG/HIJKLMNOP, l'ID team è ABCDEFG e il canale è HIJKLMNOP.

  Di seguito sono riportati alcuni esempi per le diverse piattaforme di messaggistica per le competenze che non utilizzano ID utente autenticati.

  Esempio Slack:

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

  Esempio di 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/"
          } 
      }
  }

  Esempio di Twilio:

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

  Questo esempio mostra come inviare un evento a un canale instradato a un assistente digitale. Quando il canale indirizza a un assistente digitale, è necessario includere il nome e la versione dello skill.

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

  Di seguito è riportato un esempio di competenza autenticata dall'utente, ovvero il canale dell'applicazione associato ha Usa ID utente autenticato attivato. Questo esempio si applica a MS Teams, Slack e Twilio. Tenere presente che per MS Teams e Slack non si include l'oggetto channelProperties quando si esegue l'instradamento a uno skill autenticato dall'utente.

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

• Per autenticare la richiesta, aggiungere un'intestazione X-Hub-Signature con un hash SHA256 del corpo utilizzando la chiave segreta del canale dell'applicazione. Ad esempio:

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

  La sezione Usa Postman come applicazione esterna dell'esercitazione Invia promemoria mediante conversazioni avviate dall'applicazione illustra un esempio di impostazione di questa intestazione.

• Inviare la richiesta POST all'URL in entrata del canale dell'applicazione. Deve essere simile al seguente:

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

Sarà necessario specificare il nome del canale di sistema e l'ID utente dell'anteprima per inviare i messaggi dell'applicazione esterna all'anteprima. Quando un'applicazione esterna invia un messaggio al canale di sistema, Oracle Digital Assistant instrada il messaggio all'anteprima con l'ID utente specificato.

1. Per ottenere il nome del canale di sistema, dalla barra di navigazione a sinistra fare clic su Canali, fare clic su Sistema, quindi esaminare il nome.

   Il nome sarà System_Bot_Test o System_Global_Test.

2. Per ottenere l'ID utente dell'anteprima, aprire lo skill e fare clic su Anteprima .

3. Aprire Network Monitor selezionando Sviluppatore Web nel menu del browser, quindi fare clic su Rete.

4. Selezionare XHR per visualizzare solo le richieste REST.

5. Immettere un messaggio nell'anteprima.

6. Dopo che lo skill ha restituito del testo, andare a Network Monitor, quindi esaminare la scheda Risposta.

   Selezionare ogni risposta finché non ne viene trovata una contenente un valore messagePayload.

7. Immettere userId nel campo Proprietà filtro per visualizzare il valore per userId.

8. Lasciare attiva l'anteprima e non fare clic su Reimposta.

   Se si reimposta o si chiude l'anteprima, l'ID utente viene modificato.

Dopo aver ricevuto il nome del canale di sistema e l'ID utente del sistema, è possibile inviare messaggi dall'applicazione esterna all'anteprima dello skill.

Per utilizzare l'anteprima anziché il servizio di messaggistica, impostare userId sull'ID utente dell'anteprima e impostare channelName sul nome del canale di sistema, come mostrato qui:

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