Una conversación iniciada por la aplicación comienza cuando una aplicación externa envía un evento a la aptitud o al asistente digital al que pertenece. Hay algunos cambios que debe realizar en su aptitud para que la conversación empiece en el lugar adecuado y muestre los valores deseados.

Un evento que se envía desde una aplicación externa debe incluir un tipo de carga útil, que identifica de forma única el evento para la aptitud. Normalmente, el tipo de carga útil indica lo que se supone que debería hacer la aptitud, como msgReminder o cancelAppointment. El evento también puede incluir parámetros en su objeto JSON variables, como el nombre de un paciente o la hora de una cita.

En su skill, debe asegurarse de que haya un estado de inicio en el flujo de diálogo para cada evento (varios eventos pueden tener el mismo estado de inicio). También debe agregar variables de nivel de flujo para incluir los valores de parámetros, si los hay. A continuación, debe asignar el tipo de carga útil del evento al estado de inicio.

Siga estos pasos para cada evento:

1. Si la aplicación externa va a incluir un objeto variables en la carga útil del mensaje del evento, agregue variables de nivel de flujo que contengan los valores de las propiedades del objeto.

   El nombre de variable de nivel de flujo debe coincidir con el nombre de la propiedad del objeto variables. Por ejemplo, para que la aplicación externa envíe un cuerpo de solicitud como este para un evento de recordatorio de cita:

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

2. Asegúrese de que el flujo de diálogo tenga un estado de inicio para el evento.

   Consejo:

   Si la plataforma de mensajes es de solo texto, puede hacer que las entradas de los usuarios sean menos propensas a errores si configura la numeración automática en el flujo de diálogo de la aptitud. Tenga en cuenta también la posibilidad de mostrar u ocultar texto según la plataforma de mensajes. Consulte Canales de solo texto.

3. Para asignar el evento al estado de inicio, haga clic en Configuración , Eventos y, a continuación, en Agregar asignación. A continuación, introduzca estos campos:

   • Tipo de carga útil: nombre que identifica de forma única el evento. La aplicación externa debe utilizar este nombre para dirigir el mensaje al estado aplicable.

     Utilice el tipo de carga útil de la aplicación externa, en lugar del nombre de estado real, ya que la carga útil es una constante, mientras que el nombre del estado podría cambiar si se revisa el flujo de diálogo.

   • Nombre de estado: estado de inicio del evento en el flujo de diálogo.

   En esta captura de pantalla, el tipo de carga útil msgReminder se asigna al estado remindermessage en el flujo de diálogo.

   
   
   Descripción de la ilustración evento-map.png
   

   Al agregar una aptitud a un asistente digital, las asignaciones de eventos a estados de la aptitud se agregan automáticamente a la página Eventos del asistente digital. Puede acceder a esta página desde la página Configuración del asistente digital.

Si para su aptitud se necesita que los usuarios se autentiquen con Oracle Identity Cloud Service u Oracle Access Manager, debe configurar el canal de aplicación, la aptitud y la aplicación externa para permitir que la aptitud asocie el ID de usuario autenticado al ID del usuario bot.

Para que los eventos que se envían a una aptitud autenticada por el usuario funcionen, el usuario debe haber iniciado sesión en el proveedor de identidad de la aptitud. Por ejemplo, supongamos que Deva está utilizando una aptitud para crear un informe de gastos. Antes de que pueda realizar cualquier acción en la aptitud, la aptitud le solicita que se conecte. A continuación, la aptitud asocia su ID de usuario autenticado a su ID de usuario para la plataforma de mensajes, así como los parámetros de la plataforma de mensajes que se almacenan en caché en el perfil del usuario.

Una vez que finaliza el informe, se le pide que se le notifique cuando se apruebe el gasto. La compañía de Deva utiliza una aplicación externa para enviar el evento de notificación a la misma aptitud. Para que la aplicación envíe el evento a una aptitud autenticada por el usuario, debe enviar el ID de usuario autenticado de Deva en lugar del ID de usuario de la plataforma de mensajes. Con el ID de usuario autenticado, la aptitud puede buscar el ID de usuario de la plataforma y la información del perfil almacenado en caché que obtuvo cuando Deva se conectó inicialmente.

Si Deva nunca se ha conectado desde la aptitud, su autenticación ha caducado o la caché del perfil ha caducado, Digital Assistant responde a la solicitud del evento con un error 500.

Además de los pasos de Configuración de la aptitud, debe completar los siguientes pasos para configurar las conversaciones iniciadas por la aplicación para aptitudes autenticadas por el usuario:

1. Si su aptitud ya ha activado la autenticación de usuarios, vaya a Configuración > Servicios de autenticación, abra el servicio y asegúrese de que la opción Período de retención de token de refrescamiento esté definida en 14 días, lo que coincide con la duración de caducidad de la caché del perfil de usuario. Estos valores deben estar sincronizados.

2. Si su aptitud aún no ha activado la autenticación de usuario, realice estos pasos:

   1. Asegúrese de que un administrador haya realizado los pasos de Registro de proveedor de identidad.

   2. Cree un servicio de autenticación para el proveedor de identidad, como se describe en Servicios de autenticación.

   3. Asegúrese de que la opción Período de retención de token de refrescamiento del servicio de autenticación esté definida en 14 días, lo que coincide con la duración de la caducidad de la caché del perfil de usuario. Estos valores deben estar sincronizados.

   4. Para permitir a los usuarios conectarse desde la aptitud, agregue un estado para el componente Enlace de cuenta OAuth 2.0 al flujo de diálogo, como se describe en OAuth 2.0 Enlace de cuenta.

3. Cuando cree el canal de aplicación, cambie el valor de Usar ID de usuario autenticado a Activado. O bien, si ya está creado, abra el canal y cámbielo a Activado.

En el cuerpo de la solicitud que envía la aplicación externa a Digital Assistant, recuerde definir la propiedad userId como el ID de usuario autenticado, según se describe en Configuración de la aplicación externa.

Para que las conversaciones iniciadas por la aplicación funcionen, tendrá que crear un canal de usuario para enlazar la aptitud a su cuenta de la plataforma de mensajes. Consulte estos temas para conocer los pasos necesarios para crear un canal de usuario para la plataforma específica.

• Twilio/SMS
• Slack
• Microsoft Teams

Tenga en cuenta que, si selecciona una aptitud de la lista Enrutar a del canal, todos los mensajes de la aplicación externa que se envíen a este canal se enrutarán a la aptitud seleccionada. Sin embargo, si selecciona un asistente digital, tendrá que especificar la aptitud de destino en la carga útil de mensaje de la aplicación externa.

Debe crear un canal de aplicación que permita a la aplicación externa enviar mensajes a Digital Assistant. Después de crear el canal, Digital Assistant asigna una clave secreta. Debe utilizar esta clave secreta en la aplicación externa.

1. En la barra de navegación izquierda, haga clic en Canales, Aplicaciones y, a continuación, en Agregar configuración de la aplicación.

2. Introduzca un nombre y, si quiere, una descripción.

3. (Opcional) Todos los mensajes de error relacionados con el canal se registran en el archivo log del servidor. Si también desea que Digital Assistant envíe estos mensajes de error a un servicio web externo, introduzca el URL del servicio web en el campo URL de aplicación saliente.

   Si se produce un error, como un problema al iniciar una conversación a través del canal de usuario, Digital Assistant envía un mensaje de error como un objeto JSON con las propiedades botId, sessionId y message.

4. (Opcional) Si la aptitud de destino necesita autenticación mediante el componente de enlace de cuenta OAuth 2.0 y la aplicación externa envía el ID de usuario autenticado, en lugar del ID de usuario de la plataforma de mensajes, active Usar ID de usuario autenticado.

   Si está activado, el Digital Assistant buscará el ID de usuario de la plataforma de mensajes para el ID de usuario autenticado especificado. Tenga en cuenta que el usuario debe haber iniciado sesión a través de la aptitud para que la búsqueda se realice correctamente. Para obtener más información, consulte Configuración de una aptitud autenticada por el usuario.

5. Haga clic en Crear.

6. Active Aplicación activada.

7. Tome nota de la clave secreta y del URL de entrada. La aplicación externa los utilizará.

   • Envía mensajes mediante el envío de una solicitud POST al URL de entrada.
   • Utiliza la clave secreta para autenticar sus solicitudes POST.

Si su aptitud soporta las conversaciones iniciadas por la aplicación y agrega esa aptitud a un asistente digital, tal vez desee ajustar estos parámetros de configuración en la página Configuración del asistente digital:

• Indicador de interrupción: este indicador se muestra cuando se interrumpe un flujo para iniciar uno nuevo.
• Activar numeración automática en acciones de devolución: se recomienda asegurarse de que este valor sea true para todos los canales de solo texto para que la entrada del usuario sea menos propensa a errores. Por defecto, este valor es true para todos los canales de Twilio: ${(system.channelType=='twilio')?then('true','false')}

La aplicación externa inicia un evento mediante el envío de una solicitud POST a una dirección URL de entrada del canal de la aplicación. Estas son las acciones que debe realizar la aplicación para preparar y enviar la solicitud.

• Incluya estas propiedades en el cuerpo de la solicitud (a continuación se muestran ejemplos):

  • userId: debe ser uno de los siguientes ID:

    • ID de usuario de bot de Microsoft: ID de usuario del bot para el canal de bots de Microsoft. Este ID es específico de cada canal de bots de Microsoft. La aptitud guarda este valor en la variable profile.msBotUserId.

    • ID de usuario de Slack: ID de miembro del usuario de Slack. La aptitud guarda este valor en system.message.channelConversation.userId.

    • ID de canal de Twilio/SMS: número de teléfono móvil del usuario. Debe ser uno de los números asociados al número de teléfono de la cuenta de Twilio especificado en la configuración del canal de usuario del asistente digital. La aptitud guarda este valor en la variable profile.firstName.

    • ID de usuario generado por el sistema: si prueba su aptitud desde Vista previa, debe ser el ID de usuario generado por el sistema para la sesión en Vista previa. Consulte Prueba de conversaciones iniciadas por la aplicación desde la vista previa.

    • ID de usuario autenticado: si el canal de aplicación asociado tiene el valor Usar ID de usuario autenticado definido en Activado, debe ser el ID del usuario autenticado. El usuario con este ID de usuario autenticado ya debe estar conectado a la aptitud de destino a través del componente de enlace de cuenta OAuth 2.0. Consulte Configuración de una aptitud autenticada por el usuario.

  • messagePayload: este objeto contiene:

    • type: defínalo en application.

    • payloadType: nombre del evento (tipo de carga útil) asignado al estado de inicio deseado en el flujo de diálogo. Consulte Configuración de la aptitud.

    • skillName y version: (opcional) si el canal de usuario de la plataforma de mensajes se enruta a un asistente digital, debe incluir los elementos skillName y version de la aptitud para que el asistente digital sepa a qué aptitud y versión enviar el evento.

    • channelName: nombre del canal de usuario de la plataforma de mensajes configurado para la aptitud o el asistente digital.

      Si está probando la aptitud desde Vista previa, debe definir channelName en el nombre del canal del sistema. Consulte Prueba de conversaciones iniciadas por la aplicación desde la vista previa.

    • variables: (Opcional) pares de clave-valor que transferir a las variables del flujo de diálogo. Si las variables de flujo correspondientes están definidas en el flujo de diálogo, se rellenan con los valores transferidos desde este objeto.

  • channelProperties: este objeto es para MS Teams y Slack. No es necesario incluir este objeto en el cuerpo de la solicitud si se activa Usar ID de usuario autenticado para el canal de usuario.

    Objeto channelProperties de MS Teams

    Este objeto es necesario si el usuario no ha interactuado con la conversación durante 14 días. Sus propiedades son:

    • botName: manejador de bots que ha especificado al crear el registro de canal de bots, como se describe en Paso 1: creación de un bot. Este valor se guarda en la variable profile.botName.

    • tenantId: ID del inquilino de Microsoft Teams. Este valor se guarda en la variable profile.tenantId.

    • serviceUrl: URL del servicio para el bot. Este valor se guarda en la variable profile.serviceUrl.

    Cuando el usuario de Microsoft Teams conversa con la aptitud, Digital Assistant captura y almacena estos valores en la caché del perfil. Si la carga útil de la solicitud de un evento no incluye el objeto channelProperties, la aptitud utilizará los valores de la caché de perfil, si está disponible (la caché caduca después de 14 días). La aptitud usa los valores del perfil almacenados en caché solo si faltan en el cuerpo de la solicitud.

    Cuando el flujo de diálogo envía una solicitud de notificación al backend, como, por ejemplo, a través de un componente personalizado, debe transferir esos valores de perfil al backend. A continuación, la aplicación externa puede utilizar esos valores en el objeto channelProperties en el caso de que la caché de perfil haya caducado. Este es un fragmento de código de componente personalizado que obtiene los valores que enviar 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') : "";

    Objeto channelProperties de Slack

    Para Slack, incluya estas propiedades en el objeto channelProperties:

    • teamId: ID de espacio de trabajo de Slack. Este valor se guarda en la variable profile.team_id.

    • channel: ID del canal en el espacio de trabajo. Es decir, el canal del usuario. Este valor se guarda en la variable profile.channel.

    Puede obtener el ID de equipo y el canal desde la URL de la web de Slack. Por ejemplo, si la URL es https://app.slack.com/client/ABCDEFG/HIJKLMNOP, el ID de equipo es ABCDEFG y el canal es HIJKLMNOP.

  A continuación se muestran ejemplos de las distintas plataformas de mensajes para las aptitudes que no usan ID de usuario autenticados.

  Ejemplo de Slack:

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

  Ejemplo de 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/"
          } 
      }
  }

  Ejemplo de Twilio:

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

  En este ejemplo se muestra cómo enviar un evento a un canal que se enrute a un asistente digital. Cuando el canal se enruta a un asistente digital, debe incluir el nombre y la versión de la aptitud.

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

  A continuación se muestra un ejemplo de una aptitud autenticada por el usuario (es decir, el canal de aplicación asociado tiene el valor de Usar ID de usuario autenticado definido en Activado). Este ejemplo se aplica a MS Teams, Slack y Twilio. Tenga en cuenta que para MS Teams y Slack, no incluye el objeto channelProperties al enrutar a una aptitud autenticada por el usuario.

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

• Para autenticar la solicitud, agregue una cabecera X-Hub-Signature con un valor hash SHA256 del cuerpo mediante la clave secreta del canal de aplicación. Por ejemplo:

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

  La sección Usar Postman como aplicación externa del tutorial Enviar recordatorios mediante conversaciones iniciadas por la aplicación muestra un ejemplo de definición de esta cabecera.

• Envíe la solicitud POST al URL de entrada del canal de aplicación. Debería tener un aspecto similar a:

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

Necesitará el nombre de canal del sistema y el ID de usuario de vista previa para enviar los mensajes de su aplicación externa a la vista previa. Cuando una aplicación externa envía un mensaje al canal del sistema, Oracle Digital Assistant enruta el mensaje a la vista previa que tenga el ID de usuario especificado.

1. Para obtener el nombre del canal del sistema, en la barra de navegación izquierda, haga clic en Canales, Sistema y, a continuación, compruebe el nombre.

   El nombre será System_Bot_Test o System_Global_Test.

2. Para obtener el ID de usuario de la vista previa, abra la aptitud y haga clic en Vista previa .

3. Para abrir Network Monitor (Monitor de red), seleccione primero Web Developer (Desarrollador web) en el menú del explorador y, a continuación, haga clic en Red.

4. Seleccione XHR para visualizar únicamente las solicitudes REST.

5. Introduzca un mensaje en la vista previa.

6. Después de que la aptitud genere texto, vaya al Monitor de red y, a continuación, observe el separador Respuesta.

   Seleccione cada respuesta hasta que encuentre una que contenga messagePayload.

7. Introduzca userId en el campo Propiedades de filtro para mostrar el valor para userId.

8. Deje activa la vista previa y no haga clic en Restablecer.

   Si restablece o cierra la vista previa, el ID de usuario cambiará.

Después de obtener el nombre del canal del sistema y el ID de usuario del sistema, puede enviar mensajes desde su aplicación externa a la vista previa de la aptitud.

Para utilizar la vista previa en lugar del servicio de mensajería, defina userId en el ID de usuario de la vista previa y channelName en el nombre del canal del sistema, como se muestra a continuación:

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