¡Esta es una revisión vieja del documento!


Integraciones con sistemas externos

Integración por URL sistemas externos

Be Aware 360 provee una URL para permitir de sistemas externos puedan integrarse con la plataforma permitiendo un único login entre el Sistema externo y Be Aware 360, mediante el uso del token de autenticación.

URL genérica

Con la última actualización de la aplicación se han realizado mejoras en el formato de la URL de integración con sistemas externos, el cual contempla lo siguiente:

  • Se habilita el parámetro caso para permitir realizar búsqueda por un número de caso específico.
  • Se agrupan los parámetros de contacto en un solo parámetro llamado “contacto”.

Importante:

  • La funcionalidad actual no se verá afectada con los nuevos cambios.
  • Se recomienda migrar las implementaciones actuales al nuevo formato de URL.
  • Para nuevas implementaciones se recomienda utilizar el nuevo formato de URL.

La estructura de la nueva URL queda de la siguiente forma:

https://{URL_Instancia}/integracionview/PLATAFORMA/CANAL/IDCHAT/{"contacto":"parametro_contacto","empresa":"parametro_cuenta","caso":"parámetro_caso"}/TOKEN

Ejemplo ambiente de producción:

https://ba360review.deskbeaware.com/integracionview/genesys/chat/1234567645/{"contacto":"998874563","empresa":null,"caso":"210112-000000"}/ZTMgcHJ1ZWJhY2hhdCAxMjM0IHlCeWdPcktxQTAgMjAyMDAyMDc
https://ba360review.deskbeaware.com/integracionview/genesys/chat/1234567645/{"contacto":"998874563","empresa":null,"caso":null}/ZTMgcHJ1ZWJhY2hhdCAxMjM0IHlCeWdPcktxQTAgMjAyMDAyMDc

Ejemplo ambiente de preproducción:

https://ba360reviewdesk.beaware360.com/integracionview/genesys/chat/1234567645/{"contacto":"998874563","empresa":null,"caso":"210112-000000"}/ZTMgcHJ1ZWJhY2hhdCAxMjM0IHlCeWdPcktxQTAgMjAyMDAyMDc
https://ba360reviewdesk.beaware360.com/integracionview/genesys/chat/1234567645/{"contacto":"998874563","empresa":null,"caso":null}/ZTMgcHJ1ZWJhY2hhdCAxMjM0IHlCeWdPcktxQTAgMjAyMDAyMDc

A continuación se detallan los campos que pueden viajar en la URL:

Campo Descripción Tipo de dato
plataforma Corresponde al nombre de la plataforma del sistema externo que está invocando Be Aware 360. String
canal Corresponde al nombre del canal con el que quedará creado el caso en Be Aware 360. Clic aquí para conocer los valores disponibles de canales. String
ID_Chat Corresponde al Id de la interacción de la plataforma del sistema externo y que quedará relacionado en el caso de Be Aware 360. El tamaño máximo del campo son 120 caracteres. String
contacto Corresponde a cualquier parámetro de búsqueda del contacto en Be Aware 360, entre los campos: Identificador, Nombre, Idrrss, Email y Teléfono. String
empresa Corresponde a cualquier parámetro de búsqueda de la cuenta en Be Aware 360, entre los campos: Identificador, Representante, Razón Social, Giro y Dirección. String
caso Corresponde al número de caso de Be Aware 360. String
auth_token Corresponde al token de autenticación del usuario en Be Aware 360. Para más información sobre el token de autenticación, clic aquí. String

URL anterior

La URL anterior para integración con sistemas externos tiene la siguiente estructura:

{URL_Instancia}/integracionview/{plataforma}/{canal}/{ID_Interaccion}/{"identificador":"179259168","nombre":"","idrrss":null,"email":"","telefono":"","empresa":null,"caso":"201201-000005"}/{auth_token}

Ejemplo ambiente de preproducción:

https://ba360reviewdesk.beaware360.com/integracionview/chattigo/chat/150/"identificador":"","nombre":"","idrrss":null,"email":"","telefono":"993405075","empresa":null,"caso":null/ZTMgcHJ1ZWJhY2hhdCAxMjM0IHlCeWdPcktxQTAgMjAyMDAyMDc

Ejemplo ambiente de producción:

https://ba360review.deskbeaware.com/integracionview/chattigo/chat/150/"identificador":"","nombre":"","idrrss":null,"email":"","telefono":"993405075","empresa":null,"caso":null/ZTMgcHJ1ZWJhY2hhdCAxMjM0IHlCeWdPcktxQTAgMjAyMDAyMDc

A continuación se detallan los campos que pueden viajar en la URL anterior:

Campo Descripción Tipo de dato
plataforma Corresponde al nombre de la plataforma del sistema externo que está invocando Be Aware 360. String
canal Corresponde al nombre del canal con el que quedará creado el caso en Be Aware 360. Clic aquí para conocer los valores disponibles de canales. String
ID_Interaccion Corresponde al Id de la interacción de la plataforma del sistema externo y que quedará relacionado en el caso de Be Aware 360. El tamaño máximo del campo son 120 caracteres. String
identificador Corresponde al identificador del contacto en Be Aware 360. String
nombre Corresponde al nombre y apellido del contacto en Be Aware 360. String
idrrss Corresponde al Id de las redes sociales del contacto en Be Aware 360. String
email Corresponde al correo electrónico del contacto en Be Aware 360. String
telefono Corresponde al número de teléfono del contacto en Be Aware 360. String
empresa Corresponde a cualquier parámetro de búsqueda de la cuenta en Be Aware 360, entre los campos: Identificador, Representante, Razón Social, Giro y Dirección. String
caso Corresponde al número de caso de Be Aware 360. String
auth_token Corresponde al token de autenticación del usuario en Be Aware 360. Para más información sobre el token de autenticación, clic aquí. String

Búsqueda de casos, cuentas y contactos

Se debe tener en cuenta la siguiente casuística para hacer la búsqueda por Casos, Cuentas o Contactos:

  1. La prioridad de búsqueda es Caso → Cuenta → Contacto.
  2. Si se envía un dato en el parámetro “caso”, realizará búsqueda sobre el objeto de Casos independientemente si vienen valores en los otros parámetros.
  3. Si se envía un dato en el parámetro “empresa”, realizará búsqueda sobre el objeto de Cuentas, por cualquiera de estos campos: Identificador, Representante, Razón Social, Giro y Dirección, solo si no viene un valor en el parámetro caso.
  4. Si se envía un dato en el parámetro “contacto”, realizará búsqueda sobre el objeto de Contactos por cualquiera de estos campos: identificador, nombre, idrrss, email y telefono, solo si no vienen valores en los parámetros caso ni empresa.

Ingreso directo a registro para resultados únicos

Se deben tener en cuenta las siguientes consideraciones en la búsqueda:

  • Si alguna búsqueda entrega un solo resultado, se ingresará directamente a la vista del registro encontrado.
  • Si alguna búsqueda no entrega resultado, se mostrará el buscador correspondiente con el valor ingresado en la búsqueda pero sin resultados.
  • Si alguna búsqueda entrega más de un resultado, se mostrará el buscador correspondiente con el valor ingresado en la búsqueda y los primeros 10 resultados obtenidos. Moviéndose en las páginas se visualizan otros 10 resultados.

Canales aceptados

Los valores posibles que acepta la URL de integración de sistemas externos sobre los canales son:

  • Voz (se acepta Call)
  • Chat
  • Email
  • SMS
  • TWDirect
  • Messenger
  • Facebook
  • Whatsapp
  • Telegram
  • Hangout
  • Instagram

Consumo del token de autenticación

El último parámetro que recibe la URL para integración de sistemas externos con Be Aware 360 es el token de autenticación. Se debe tener en cuenta la siguiente información para obtener el token:

Método

POST

URL Recurso

  • URL producción: https://api.beaware360.com
  • URL preproducción (Instancias de los partners): https://api-prep.beaware360.com
  • Resource: /ba360/apir/v10/login/authexternalsystem

Body

{
	"user":"USERNAME",
	"pass":"USERPASS",
	"company":"COMPANY",
	"secretkey":"DgRCJT+oAQ5qsK8sBhD0NQ==",
	"clientkey":"/GUslVpfTHkPj3YX7wt2eQ=="
}

Secretkey y Clientkey

Los valores de los campos secretkey y clientkey son propios para cada instancia y manejados por el administrador de la plataforma. Se habilitó una vista especial para el administrador llamada Aplicaciones externas para obtener los valores de ambos campos, teniendo en cuenta las siguientes consideraciones:

  • Al ingresar por primera vez se generan ambos parámetros de forma automática.
  • En la vista se entrega la posibilidad de “Regenerar” el SecretKey invalidando el valor anterior.

Habilitación de la vista Aplicaciones externas

Para generar los valores de secretkey y clientkey, el administrador de la plataforma debe tener acceso a la vista de Aplicaciones externas. Para agregar esta vista a los permisos del administrador, se deben realizar los siguientes pasos:

  1. Navegar al menú Agente > Roles.
  2. Clic en el botón Permisos para el rol Administrador.
  3. Buscar por Aplicaciones Externas y otorgar todos los permisos.
  4. Clic en el botón Guardar.
  5. El usuario con rol de administración verá el menú en el próximo inicio de sesión.
  6. La vista queda disponible en el menú Otros > Aplicaciones externas.
    1. Nota: Al ingresar por primera vez se generarán los valores para Clientkey y Secretkey.

Lógica de negocio

Se deben tener en cuenta las siguientes consideraciones:


Lógica de negocio para manejo de usuarios

  1. Si el usuario no existe, se crea.
    1. Toma el rol marcado por defecto en la vista de Roles.
      1. Si no se ha configurado un rol por defecto, lo crea sin rol.
    2. Toma el grupo marcado por defecto en la vista de Grupos.
      1. Si no se ha configurado un grupo por defecto, lo crea sin grupo.
    3. Nombre, Apellido y User se toma del valor “user”.
    4. Contraseña, se toma del valor “pass”.
    5. Email se forma desde el valor “user” como {user}@authexternalsystem.com. Luego debe ser modificado por un administrador de usuarios para evitar el envío de correos electrónicos que reboten.
      1. Ejemplo:
        1. Valor campo user: UserNew.
        2. Email: UserNew@authexternalsystem.com.
    6. Zona horaria se toma desde el valor de la instancia.
    7. Idioma se toma desde el valor de la instancia.
    8. Luego de crear, entrega token de autenticación.
  2. Si el usuario existe, entrega token de autenticación o error en autenticación.
  3. Si los datos del Usuario son vacíos o nulos, se entrega mensaje de error y no se realiza la acción de validación/creación.

Lógica de negocio para manejo de token

  1. Si el token enviado en la URL es válido, se accede a la plataforma.
  2. Si el token enviado en la URL no es válido:
    1. Se muestra pantalla de login solicitando credenciales.
    2. Luego del login exitoso se redirige a la vista invocada en la URL.
  3. Si no se envía token en la URL:
    1. Se muestra pantalla de login solicitando credenciales.
    2. Luego del login exitoso se redirige a la vista invocada en la URL.

Integración por URL Genesys PureCloud

En construcción

Integración del histórico de conversación con Be Aware Social

Esta integración permite, desde la Consola de Agentes de Be Aware 360, acceder a la conversación realizada en el canal social (Whatsapp, Messenger, Instagram, etc.) entre el cliente y el ejecutivo que deriva en la creación del caso.

Al crear el caso desde Be Aware Social, se crea una nota automática con un enlace que muestra la conversación relacionada al caso. Al presionar sobre el enlace, desde la Consola de Be Aware 360, se muestran los mensajes correspondientes a la conversación y los adjuntos asociados.

Para configurar esta integración se deben realizar los siguientes pasos:

  1. Ingresar un caso en el PUC, solicitando la entrega de los parámetros de configuración. En el caso se entregarán:
    1. Usuario de la integración.
    2. Contraseña del usuario.
    3. URL del servicio.
  2. Navegar al menú Otros > Parámetros.
  3. Crear un parámetro con el nombre ext_sys_user. El valor del parámetro corresponderá al usuario entregado en el caso.
  4. Crear un parámetro con el nombre ext_sys_pass. El valor del parámetro corresponderá a la contraseña del usuario entregado en el caso.
  5. Crear un parámetro con el nombre ext_sys_url. El valor del parámetro corresponderá a la URL entregada en el caso.

Una vez configurados los parámetros mencionados anteriormente, ya puede empezar a acceder al histórico de conversación en los casos.

Nota: Los nombres de los parámetros se deben respetar tal y como están escritos en esta documentación.

Integración SSO con el Directorio Activo de Microsoft Azure

La consola de Be Aware 360 cuenta con la posibilidad de realizar login unificado (SSO) con la plataforma Azure Active Directory para usuarios de Be Aware 360 en Consola.

Con esta integración se permite gestionar el acceso a la consola de Be Aware 360 a través de la configuración de usuarios en Azure Active Directory, dónde no necesitarán realizar doble login (Azure + Be Aware 360) si no que con el acceso a Microsoft Azure se habilita el acceso a Consola de Be Aware 360.

Flujo de autenticación en Be Aware 360 con Azure Active Directory

Una vez activada la integración SSO Azure en Be Aware 360, el acceso a Consola se realizará de la siguiente manera:

  1. Un usuario ingresa a la página de login de la consola de Be Aware 360.
  2. El sistema detecta que la instancia de Be Aware tiene activa la integración con Azure Active Directory y automáticamente redirigirá al usuario a la plataforma de Microsoft Azure para solicitar el acceso:
    1. Si el usuario no ha iniciado sesión en Microsoft Azure, se solicitarán los accesos de dicha plataforma.
    2. Si el usuario ya tienen sesión iniciada en Microsoft Azure, no solicitará ingreso de credenciales.
  3. En Microsoft Azure se validan los permisos del agente para acceder a Be Aware 360.
    1. Si el usuario tiene los permisos correspondientes, se redirigirá a la consola de Be Aware 360.
    2. Si el usuario no tiene los permisos necesarios para el ingreso, se dará mensaje de error en Microsoft Azure.
  4. Con el acceso correcto en Microsoft Azure, se redirigirá al usuario a la consola de Be Aware 360.
    1. Se realiza el ingreso a la consola de Be Aware 360 con el usuario del agente que accede.
      1. En caso que no se encuentre el usuario correspondiente, se dará mensaje de error.
  5. Al realizar el logout desde la consola de Be Aware 360 se redirigirá a la página de cierre de sesión de Be Aware 360.
    1. La sesión en Microsoft Azure no se cerrará.

Configuración de la integración entre Be Aware 360 y Azure Active Directory

Creación y configuración de aplicación Be Aware 360 en Azure

Se debe crear y configurar la aplicación Be Aware 360 en Azure AD.

Creación de Aplicación:

Dentro del portal de Azure:

  1. Ingresar a Azure Active Directory
  2. En el menú lateral izquierdo, Ir a sección Administrar > Registro de aplicaciones
  3. Crear nuevo registro presionando sobre Nuevo registro
  4. Completar los datos de la aplicación:
    1. Nombre: Be Aware 360
    2. Tipo de cuenta compatible: Seleccionar tipo de Cuenta
    3. URI de redirección:
      1. Opción: Aplicación de página única.
      2. Valor: Colocar URL de login de Be Aware 360.
    4. Guardar.

Configuración de Autenticación: Dentro del portal de Azure:

  1. Ingresar a Azure Active Directory
  2. En el menú lateral izquierdo, Ir a sección Administrar > Autenticación
  3. En la sección Flujos de concesión implícita e híbridos, marcar las opciones:
    1. Tokens de acceso
    2. Tokens de id

Configuración de parámetros opcionales:

:!: Nota: Este paso es necesario para obtener desde el token de Azure los parámetros que son opcionales, entre ellos el email del usuario a autenticar con SSO.

Dentro del portal de Azure:

  1. Ingresar a Azure Active Directory
  2. En el menú lateral izquierdo, Ir a sección Administrar > Registro de aplicaciones
  3. Seleccionar e ingresar a la aplicación Be Aware 360 creada anteriormente
  4. En el menú lateral izquierdo, Ir a sección Administrar > Configuración de token

Continuar con los siguientes pasos:

  1. Agregar parámetro email. El parámetro email es utilizado cuando en la configuración de Be Aware 360 se selecciona como Identificador de usuario de Azure el Correo. Corresponde a la configuración por defecto.
    1. Seleccionar la opción + Agregar notificación opcional
      1. Seleccionar Id como tipo de token
      2. Seleccionar el parámetro email
      3. Presionar Agregar
      4. Marcar la casilla para activar el permiso de Microsoft Graph Email
      5. Presionar Agregar
  2. Agregar parámetro upn (user principal name). El User Principal Name (upn) o Nombre principal de usuario es otro parámetro que puede ser utilizado para identificar al usuario Azure. Este parámetro es utilizado cuando se selecciona como Identificador de usuario de Azure al Nombre principal de Usuario en la configuración de Be Aware 360.
    1. Seleccionar la opción + Agregar notificación opcional
      1. Seleccionar Id como tipo de token
      2. Seleccionar el parámetro upn
      3. Presionar Agregar
      4. Si aparece, Marcar la casilla para activar el permiso de Microsoft Graph Email. Presionar Agregar
      5. Presionar sobre los tres puntos que aparecen a la derecha en el parámetro upn
      6. Seleccionar Editar
      7. Colocar como Sí (activar) al valor de Autenticado externamente.
      8. Dejar como No (inactivo) el valor Reemplazar almohadillas.
      9. Presionar sobre Guardar.

Para más información sobre los parámetros del id token de Azure ver:

https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens https://learn.microsoft.com/en-us/azure/active-directory/develop/active-directory-optionalclaims

Obtención de datos de la aplicación

Se necesitan obtener datos de la aplicación creada en Azure AD para, luego, ser utilizados en la configuración de Be Aware 360.

Para realizar la configuración en Be Aware 360 se necesitan los datos de Dominio principal (Tenant) e Id. de aplicación (Client ID).

Para obtenerlos realizar los siguientes pasos:

Dentro del Portal de Azure:

  1. Ingresar a Azure Active Directory
  2. En la sección Información General > Información básica:
    1. Copiar el valor de Dominio principal. Este será utilizado como Tenant de Azure.
  3. En el menú lateral izquierdo, Ir a sección Administrar > Registro de aplicaciones
    1. En la sección Aplicaciones propias
      1. Copiar el valor Id. de aplicación (cliente) para la aplicación Be Aware 360 (creada en pasos anteriores).

Sincronización de usuarios de Azure y de Be Aware 360

La sincronización de usuarios entre sistemas es manual, es decir, se crea un usuario en Azure, luego se crea un usuario en Be Aware 360 y se establece la identificación por un parámetro en específico que deben tener ambos usuarios.

Para lograr la identificación de los usuarios se debe tener una coincidencia entre el identificador del usuario Azure y el identificador del usuario Be Aware 360. Para lograr la identificación se configura en Be Aware 360 el parámetro de Azure y el de Be Aware 360 a considerar. Ver Configurar y activar SSO con Azure.

Parámetros para identificación de usuario de Azure

  • Correo:
    • Corresponde al parámetro email del usuario de Azure.
    • Es la configuración por defecto en Be Aware 360.
    • Para utilizar este valor, se debe agregar el parámetro opcional email en el Id token.
    • Hay que considerar que este parámetro queda vacío en Azure para los usuarios creados en la configuración de Azure dentro de la organización.
  • ID de Objeto;
    • Corresponde al parámetro Object ID (oid) del usuario en Azure.
    • Es un valor único e inmutable de Azure.
  • Subject:
    • Corresponde al parámetro Subject (sub) del usuario en Azure.
    • Es un valor único e inmutable de Azure.
  • Nombre principal de usuario:
    • Corresponde al parámetro User principal name (upn) del usuario en Azure.
    • Para utilizar este valor, se debe agregar el parámetro opcional email en el Id token.

Parámetros para identificación de usuario de Be Aware 360

  • Correo:
    • Corresponde al parámetro “correo electrónico” del usuario de Be Aware 360.
    • Es la configuración por defecto en Be Aware 360.
    • Hay que considerar que si existen dos (o más) usuarios en Be Aware 360 con el mismo correo electrónico, la identificación se llevará a cabo con el primero de ellos por orden de ID (primero creado).
  • Nombre de usuario:
    • Corresponde al parámetro “Usuario” del usuario en Be Aware 360.
    • Es un valor único.
  • ID Externo:
    • Corresponde al parámetro “ID Externo” del usuario en Be Aware 360.

:!: Nota: Para elegir el parámetro de identificación en Azure y en Be Aware 360 se debe tener la seguridad que todos los usuarios tendrán valores válidos en ambos parámetros y que servirán para la identificación en el login unificado.

Permisos de aplicación para usuarios Azure

Los usuarios en Azure deben tener otorgados permisos de la aplicación Be Aware 360 (creada anteriormente) para lograr el envío de los parámetros necesarios para la identificación de usuarios.

Para dar permisos a los usuarios realizar los siguientes pasos.

Dentro del Portal de Azure:

  1. Ingresar a Aplicaciones empresariales
  2. Seleccionar la aplicación Be Aware 360 creada anteriormente
  3. En el menú lateral izquierdo, Ir a sección Administrar > Usuarios y grupos
  4. Seleccionar la opción + Agregar usuario o grupo
  5. Agregar los usuarios o los grupos correspondientes
  6. Guardar cambios

Activación y configuración de SSO en Be Aware 360

Luego de realizar las configuraciones mencionadas anteriormente, se debe activar la integración SSO con Azure desde la administración de Be Aware 360.

:!: Importante: Una vez activada, el ingreso a la Consola de Be Aware 360 será realizada por usuarios válidos en Azure. Si no existen usuarios en Azure con acceso válido, no será posible acceder a la Consola de Be Aware 360 y será necesario comunicarse con el Soporte de Be Aware 360 para desactivar la integración.

Permisos al Rol administrador

Dentro de la Consola de Be Aware 360:

  1. Ingresar al menú lateral > Agente > Roles
  2. Presionar sobre Permisos (botón verde) en el rol del administrador
  3. Marcar las casillas del permiso Administrar SSO Azure
  4. Presionar Guardar

:!: Nota: Luego de aplicar los permisos, el usuario con el rol modificado debe cerrar sesión y volver a ingresar a la Consola para ver los cambios aplicados.

Configurar y activar SSO con Azure

Dentro de la Consola de Be Aware 360:

  1. Ingresar al menú Directorio Activo de Azure (menú lateral > Otros > Directorio Activo de Azure).
  2. Seleccionar la opción SI. Esto habilitará el resto de los campos.
  3. Colocar el valor de Dominio principal (obtenido en Azure) en el campo Tenant.
    1. Corresponde a un valor obligatorio.
    2. Este valor se guarda encriptado, por lo que al volver a ingresar a la vista se verá encriptado.
  4. Colocar el valor de Id. de aplicación (obtenido en Azure) en el campo Client ID.
    1. Corresponde a un valor obligatorio.
    2. Este valor se guarda encriptado, por lo que al volver a ingresar a la vista se verá encriptado.
  5. Seleccionar el Identificador de usuario en Azure.
  6. Seleccionar el Identificador de usuario en Be Aware 360.
  7. Guardar cambios.