Saltar a contenido

API Mensajería

A continuación se muestra las api mas importante a utilizar para establecer una funcionalidad completa con Lynn en caso de mayor información del conjunto completo de api puede hacer uso de la siguiente Url https://documenter.getpostman.com/view/4212906/UVCCd3Ap (Messenger Service)

Graphical user interface, text, application Description automatically
generated

CreateToken

Se utiliza para generar el Token que autoriza utilizar al resto de las API.

Ruta:

/api/LynnService/CreateToken

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
BODY { "accessToken": "string", "accessTokenSecret": "string", "tenant": “number” } accessToken Cadena de texto que forma parte de los parámetros de autenticación, se genera al momento de crear las credenciales de seguridad del tenant y ya no se puede modificar. Ejemplo: 90234137e9752f1. Nota: Es similar a un usuario. accessTokenSecret Cadena de texto que forma parte de los parámetros de autenticación, se genera al momento de crear las credenciales de seguridad del tenant y ya no se puede modificar. Ejemplo: 66d83a1b-4da4-42f5-9883-44b8f32c36d5. Tenant Identificador numérico del tenant. Se obtiene en la interfaz gráfica de Lynn.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Nota: Esta respuesta se debe incluir en la cabecera de las peticiones siguientes para poder manejar la seguridad. Ejemplo: Variable Authorization: bearer eyJhbGciOiJIUzoEzKw4ly8jgmmAoxJbg Json Respuesta { "token": "eIkpXVCJ9.eyJhefWYXYMSl8e84YxLxrCWKVeY4N Us_2c239NG4" }
401 Unauthorized Sin Respuesta.

SessionByCriteria

Crea una interacción basada en un criterio el cual permite identificar al cliente, en caso de que el criterio ya posee una interacción recupera el sessionID previamente creado

Ruta:

/api/LynnService/SessionByCriteria/{criteria}/{value}/{inactivityTimeout}/{clientIdentification}/{callIId}/{capacityType}/{clientId}/{channelId}/{tenant}/{verbose}

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
criteria URL Cadena de texto con el criterio del registro que se va a buscar, tiene un formato común. Ejemplo: rut_usuario.
value URL Valor correspondiente al criterio que se estableció en el parámetro anterior, tiene un formato de cadena de texto abierto. Ejemplo: 231231, abcds 232dsdda, 0000-0000-0000-0000.
inactivityTimeout URL Tiempo de inactividad en segundos para comparar y solo obtener las últimas interacciones el cual su último request es menor al valor de este parámetro, este tiempo de inactividad no aplica mientras está en la cola de la estrategia.
clientIdentification URL Nombre del cliente, se debe mantener en toda la conversación.
callId URL Identificador de la llamada de voz asociada, en el caso de que aplique, sino se puede enviar con el valor “unknown”.
capacityType URL Tipo de capacidad del canal. Las capacidades válidas son: UNKNOWN = 0 PhoneCall = 1 DeviceVoice = 2 WebViewer = 3 OfficialChannel = 4, UnOfficialChannel = 5
clientId URL Identificador del cliente, es un uniqueidentifier que se debe mantener en toda la conversación.
channelId URL Identificador del canal por el cual se está comunicando el cliente y que es registrado en la plataforma que soporta el tenant.
tenant URL El valor del id de tenant configurado para el cliente.
verbose URL Nivel de logs a generar [1…5].
BODY Ud_X Parámetros custom enviados al api que corresponden a los user data, se puede enviar el json con cualquier cantidad de estos parámetros. Json Respuesta { "ud_1":"val1", "ud_2":"val2", "ud_3":"val3" }

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Nota: La respuesta puede ser una lista de este objeto, el cual, es solo un ejemplo y puede variar en algunos parámetros. Json Respuesta { }
401 Unauthorized Sin Respuesta.

SendMessage

envía un mensaje a Lynn.

Se puede utilizar en múltiples casos enviar mensaje al ejecutivo, para enviar un texto para que el bot lo evalúe cognitivamente (Solo en los casos donde el tenant posea un entrenamiento cognitivo), se puede usar para enviar la opción escogida de un menú y también se puede utilizar para responder una pregunta especifica el bot por ejemplo: “Ingrese su Rut”, “Ingrese su email”, etc.

Ruta:

/api/LynnService/SendTextMessage/{sessionId}/{capacityType}/{clientId}

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
sessionId URL Identificador de la sesión a la cual desea enviar el mensaje.
capacityType URL Tipo de capacidad del canal. Las capacidades válidas son: UNKNOWN = 0 PhoneCall = 1 DeviceVoice = 2 WebViewer = 3 OfficialChannel = 4, UnOfficialChannel = 5
clientId URL Identificador del cliente, es un uniqueidentifier que se debe mantener en toda la conversación.
BODY El texto del mensaje a enviar. Se envía el body en formato de texto plano.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Esta respuesta corresponde a una respuesta donde la intención solicitada no existe, parámetros importantes:
sessionId Identificador de la sesión actual, generada al momento de la creación de la sesión y cuya vigencia será igual a la establecida en el parámetro timeout al momento de crear la sesión.
intent número de la intención solicitada, si su valor es null corresponde a que la intención que se intentó forzar no existe.
eventMessages Lista de objetos que corresponden a los eventos de los mensajes establecidos en la respuesta para su procesamiento visual.
event Identifica el tipo de evento asociado al mensaje, existen 43 tipos de eventos de mensajes, para ver la lista completa ir a Eventos de Mensajes.
messageType Tipo de mensaje de la respuesta: 1 Menú, 2 Evento, 3 Texto, se encuentra en cada objeto de la lista eventMessages.
code Sub-Evento generado en la respuesta del mensaje, la lista completa la puede encontrar en Sub-Eventos de Mensajes.
availableByVoice Valor booleano que indica si el evento de mensaje está disponible por voz. availableByText Valor booleano que indica si el evento de mensaje está disponible en texto.
Json Respuesta { }
401 Unauthorized Sin Respuesta.

CancelCurrentInteraction

se utiliza para indicar a Lynn que debe cancelar la acción actual, por ejemplo, Estas esperando en una cola por un agente y quiere salir de la misma para continuar con las autoatenciones del Bot, otro ejemplo el bot solicita un dato de entrada pero quiere cancelar para realizar otra acción.

Ruta:

/api/LynnService/CancelCurrentInteraction/{tenant}/{sessionId}/{reason}

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
sessionId URL Identificador de la sesión que se desea cancelar.
reason URL Razón por la cual se desea cancelar la interacción.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Este es el valor actual de la entidad en texto plano, entregado en el body de la respuesta. sessionId Identificador de la sesión actual, generada al momento de la creación de la sesión y cuya vigencia será igual a la establecida en el parámetro timeout al momento de crear la sesión. eventMessages Lista de objetos que corresponden a los eventos de los mensajes establecidos en la respuesta para su procesamiento visual. id Identificador de la solicitud de cancelación. Json Respuesta { "sessionId": "734a6c23-4ab8-4aff-8d99-fc6408664986", "eventMessages": [], "id": "00000000-0000-0000-0000-000000000000" }

UploadFile

permite adjuntar un archivo durante la interacción del cliente, se recomienda usar esta Api cuando estes con un ejecutivo conectado.

Ruta:

/api/LynnService/UploadFile

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
sessionId URL Identificador de la sesión que se desea recuperar.
Content-Type: multipart/form-data
file BODY FileToUpload El nombre del fichero.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Success Propiedad que indica que si se pudo cargar el archivo. sessionId Sesión de la interacción actual del cliente en formato GUID, se genera cuando se inicia el chat. fileId Identificar del archivo en la plataforma en formato GUID para buscar el archivo en la plataforma donde se encuentre guardado. URL Dirección web donde se encuentra el archivo a descargar, la base de la dirección viene proporcionada por la dirección de instalación de Lynn. Json Respuesta { "success": true, "sessionId": "3dc84449-dd7b-46fe-963b-23c23330dec9", "fileId": "6593d153-f90b-4725-8e85-eae8cd74eb98", "url": "MobileApp/File?tenant=27&file=6593d153-f90b-4725-8e85-eae8cd74eb98", "message": null }
401 Unauthorized Sin Respuesta.

EndSession

finalizar una interacción en Lynn.

Ruta:

/api/LynnService/EndSession/{tenant}/{sessionId}

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
sessionId URL Identificador de la sesión que se desea terminar.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success sessionId Identificador de la sesión actual, generada al momento de la creación de la sesión y cuya vigencia será igual a la establecida en el parámetro timeout al momento de crear la sesión. messages Lista de mensajes que se le enviaran al cliente antes de cerrar la sesión. intent Número de la intención solicitada, si su valor es null corresponde a que la intención que se intentó forzar no existe. eventMessages Lista de objetos que corresponden a los eventos de los mensajes establecidos en la respuesta para su procesamiento visual. event Identifica el tipo de evento asociado al mensaje, existen 43 tipos de eventos de mensajes, para ver la lista completa ir a Eventos de Mensajes. messageType Tipo de mensaje de la respuesta: 1 Menú, 2 Evento, 3 Texto, se encuentra en cada objeto de la lista eventMessages. code Sub-Evento generado en la respuesta del mensaje, la lista completa la puede encontrar en Sub-Eventos de Mensajes. availableByVoice Valor booleano que indica si el evento de mensaje está disponible por voz. availableByText Valor booleano que indica si el evento de mensaje está disponible en texto. Json Respuesta { "sessionId": "734a6c23-4ab8-4aff-8d99-fc6408664986", "messages": [], "eventMessages": [ { "event": 3, "details": "", "source": "EndSession", "messageType": 2, "data": null, "code": 4, "sessionId": "734a6c23-4ab8-4aff-8d99-fc6408664986", "id": "297356ef-7e63-4bb4-a116-7aedc65d4c76", "correlation": 0, "capacities": [ { "capacityType": 3, "name": "", "clientId": "ef344f35-8e28-4251-96ac-ab1b5cbb2c70", "description": "" } ], "date": "2019-11-11T10:56:27.8892839-03:00", "availableByVoice": true, "availableByText": true, "conversationId": "00000000-0000-0000-0000-000000000000", "part": 0, "partName": "FOX", "description": null, "intent": null } ] }
401 Unauthorized Sin respuesta.

GetConfiguration

Permite recuperar una configuración especifica de Lynn.

Ruta:

/api/LynnService/GetConfiguration/{tenant}/{configurationName}

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
configurationName URL Nombre de la configuración que se le asignó al momento de crearlo.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Name Esto representa el nombre de la configuración que acaba de consultar y es idéntico al valor colocado en el campo configurationName. value Este es el valor que tiene esa configuración. Json Respuesta { "name": "CHAT_ENGINE", "value": "PURE_ENGAGE" }
401 Unauthorized Sin Respuesta.

GetHistoricalDialogBySession: Recuperar los diálogos de la conversacion para SesionId especifico.

Ruta:

/api/LynnService/GetHistoricalDialoguesBySession/{tenant}/{sessionId}

Método: POST

Tabla de parámetros

Parámetros Locación Descripción
Tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
SessionId URL Identificador de la sesión que se desea obtener.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success [ ]
401 Unauthorized Sin respuesta.

SendMessageWithIntent

Se manda a ejecutar una intención en especifica en caso tal de que la misma no exista dentro del flujo del tenant se intenta de evaluar el texto cognitivamente solo en el caso de que el bot este preparado para trabajar cognitivamente.

Ruta:

/api/LynnService/SendTextMessageWithIntent/{sessionId}/{capacityType}/{clientId}/{intent}

Método: POST

Tabla de parámetros

Parámetro Locación Descripción
tenant URL Valor numérico que relaciona el id de tenant configurado en Lynn.
sessionId URL Identificador de la sesión a la cual desea enviar el mensaje.
capacityType URL Tipo de capacidad del canal. Las capacidades válidas son: UNKNOWN = 0 PhoneCall = 1 DeviceVoice = 2 WebViewer = 3 OfficialChannel = 4, UnOfficialChannel = 5
clientId URL Identificador del cliente, es un uniqueidentifier que se debe mantener en toda la conversación.
intent URL La intención a forzar. Esto provoca que Lynn ejecute dicha intención sin evaluación de texto asociada.
BODY El texto del mensaje a enviar. Se envía el body en formato de texto plano.

Respuestas

Código http Descripción Cuerpo de la respuesta
200 Success Esta respuesta corresponde a una respuesta donde la intención solicitada no existe, parámetros importantes: sessionId Identificador de la sesión actual, generada al momento de la creación de la sesión y cuya vigencia será igual a la establecida en el parámetro timeout al momento de crear la sesión. intent número de la intención solicitada, si su valor es null corresponde a que la intención que se intentó forzar no existe. eventMessages Lista de objetos que corresponden a los eventos de los mensajes establecidos en la respuesta para su procesamiento visual. event Identifica el tipo de evento asociado al mensaje, existen 43 tipos de eventos de mensajes, para ver la lista completa ir a Eventos de Mensajes. messageType Tipo de mensaje de la respuesta: 1 Menú, 2 Evento, 3 Texto, se encuentra en cada objeto de la lista eventMessages. code Sub-Evento generado en la respuesta del mensaje, la lista completa la puede encontrar en Sub-Eventos de Mensajes. availableByVoice Valor booleano que indica si el evento de mensaje está disponible por voz. availableByText Valor booleano que indica si el evento de mensaje está disponible en texto. Json Respuesta { }
401 Unauthorized Sin Respuesta.

Api Reportes

El api se puede consumir sobre aquellos reportes que han sido configurado dentro de Lynn, en tal caso no se puede preguntar por la data de un reporte que no haya sido creado.

Durante la etapa de diseño de la app que consume el api se ejecuta el CheckAvilableReports para recuperar la información de los reportes que pueden ser consultados (Estos valores no cambian al menos que se elimine o agregue una gráfica en los reportes actuales)

Luego identificado que reporte se desea obtener se puede crear la app que consulte periódicamente el servicio ExecuteReport con el id del reporte. cabe acotar que si desea recuperar data asociada a varias gráficas debe ejecutar el servicio ExecuteReport por cada id de reporte a recuperar.

CreateToken: Se utiliza para generar el Token que autoriza utilizar al resto de las API.

CheckAvilableReports: Te muestra una lista de los reportes disponibles para el tenant que se encuentra en uso he indica los parámetros necesarios para ejecutar el Reporte.

ExecuteReport: Utilizando los datos del api anterior (CheckAvailableReports) se debe recuperar la data asociada al reporte por el cual se consulta. Si es la data es muy extensa esta se puede paginar.

Api Campañas

Posibles Errores

Session not found: El error se presenta ya que está ejecutando un api con un id sesión que posiblemente ya expiró.

Cuando una interacción finaliza, Lynn envía un evento al webhook del tipo EndSession pero por si algún motivo este no fue recibido tratado correctamente se puede dar este error. orized esto puede aplicar por dos posibles casos:

  • Credenciales invalidas: se debe validar las credenciales usadas, se recuerda que debe coincidir los 3 parámetros (tenant\<int>, ApiToken\<string>, ApiSecret\<string>) y esta deben existir en el ambiente de Lynn, se recuerda que existe dos ambientes el de Testing y Production, y cada uno de ellos posee sus propias credenciales.

  • Token caducó: El token tiene un tiempo de vigencia en ese caso al recibir este error se vuelve a generar el token con el servicio CreateToken, y repite el api y las posteriores con el nuevo token.

Http Status 429: (Too Many Request) la aplicación del cliente está haciendo un llamado excesivo se debe evitar reutilizando el objeto de conexión.