📌OMniLeads RESTful API

OMniLeads RESTful API

Esta sección está destinada hacia aquellos desarrolladores que desean ejecutar una integración entre el sistema CRM que mantienen y OMniLeads. Por lo tanto la terminología y la información aquí expuesta tiene como público objetivo a desarrolladores de software.

OMniLeads dispone de una RESTful API basada en HTTPS / JSON. La API permite el acceso a recursos y servicios del sistema por afuera de la interfaz web de usuario, permitiendo así que sistemas externos puedan integrarse de manera sencilla con OMniLeads.

Las formas de autenticación disponibles para utilizar esta api son por Sesión (el agente debe estar logueado en el sistema) y por Token (a partir del login a la API, con los parámetros usuario y pass de agente), en este caso se debe pasar la siguiente línea en los headers de la petición:

«Authorization: Bearer <token obtenido>»

Por ejemplo:

Nota

Con el transcurrir de los nuevos releases, esta sección irá siempre ampliándose ya que nuevos endpoints irán surgiendo con el transcurrir de los releases.

A continuación se describen los endpoints disponibles.

Endpoint de Login

Este método proporciona la posibilidad de autenticarse como usuario del sistema, para luego (en caso de un login exitoso) acceder a otros endpoints disponibles dependiendo el perfil de usuario con el que se ha realizado dicho login.

URL: POST https://<omnileads_addr>/api/v1/login

figure 1: endpoint login request

field name	type	description
username	string	username del usuario generado en el menú de creación de usuarios de OML
password	string	password del usuario generado en el menú de creación de usuarios de OML

Autenticación exitosa

Si el login es exitoso, el método devuelve la siguiente salida:

figure 2: endpoint login request ok

Como se puede observar en la figura, un login exitoso devuelve entre otros campos un «token» de seguridad. El mismo deberá ser utilizado en las próximas peticiones a la API desde el usuario autenticado. Además en el campo «expires_in» deja asentado el tiempo de vida del token generado.

En caso de que el sistema lance una petición y el token de seguridad haya expirado, entonces se deberá proceder nuevamente con una nueva autenticación.

Nota

El tiempo de duración del token de seguridad se configura bajo el parámetro «TOKEN_EXPIRED_AFTER_SECONDS» dentro del archivo «/opt/omnileads/ominicontacto/ominicontacto/settings/production.py»

Autenticación fallida

Si el login no es exitoso, el método devuelve la siguiente salida:

figure 3: endpoint login request fail

Endpoint obtener estructura de Base de Datos de Contactos

Esta endpoint habilita la posibilidad de obtener información de los campos de una base de datos de contactos de una campaña. Con esta información será posible luego crear un contacto. Las credenciales deberán pertenecer a un Agente (Usuarios) o a un Supervisor (Usuarios) que estén asociados a la campaña.

URL: POST https://<omnileads_addr>/api/v1/campaign/database_metadata/

field name	type	description
idExternalSystem	integer	Parámetro opcional, si se especifica el sistema intentará localizar la campaña especificada buscando este valor como “id_externo” de la campaña. En caso de no especificarse el sistema asumirá que el valor del parámetro “idCampaign” es el id interno de la campaña en OML
idCampaign	string	Id de la campaña a la que pertenece la base de datos el significado de su valor depende de si se especifica o no el parámetro “idExternalSystem”

En caso de no haber errores se devolverá un output como este, con los datos de los campos de la base de datos:

El campo “fields” indica la lista de todos los campos de la base de datos. El campo “main_phone” indica cual es es campo correspondiente al teléfono principal. El campo “external_id” indica cual de los campos corresponde al identificador externo del contacto. En caso de que la base de datos no tenga campo identificador externo, el campo “external_id” tendrá el valor None.

En caso de haber errores se devolverá un JSON con el campo “status”:”ERROR” y el detalle de los mismos en el campo “errors”. Caso contrario el valor del campo “status” será “OK”.

Endpoint creacion de contacto

Esta endpoint habilita la posibilidad de agregar un contacto a una base de datos de contactos de una campaña. Las credenciales deberán pertenecer a un Agente (Usuarios) o a un Supervisor (Usuarios) que estén asociados a la campaña.

URL: POST https://<omnileads_addr>/api/v1/new_contact/

field name	type	description
idExternalSystem	integer	Parámetro opcional, si se especifica el sistema intentará localizar la campaña especificada buscando este valor como “id_externo” de la campaña. En caso de no especificarse el sistema asumirá que el valor del parámetro “idCampaign” es el id interno de la campaña en OML
idCampaign	string	Id de la campaña a la que pertenece la base de datos el significado de su valor depende de si se especifica o no el parámetro “idExternalSystem”

Además deberán enviarse los valores de los campos correspondientes a los datos del contacto, y cuyos nombres pueden obtenerse con el endpoint de obtener estructura de de Base de Datos de Contactos (Endpoint obtener estructura de Base de Datos de Contactos). Es obligatorio enviar un valor para el campo indicado como “main_phone”, y en caso de que la base de datos tenga campo identificador externo, el valor del campo indicado como “external_id” no deberá existir previamente en otro contacto de la base de datos.

En caso de no haber errores se devolverá un output como este, con los datos del contacto y su id en OML:

En caso de haber errores se devolverá un JSON con el campo “status”:”ERROR” y el detalle de los mismos en el campo “errors”. Caso contrario el valor del campo “status” será “OK”.

Endpoint de Generación de llamadas

Permite generar llamadas (click to call) desde un Sistema CRM Externo. Las credenciales deberán pertenecer a un Agente (Usuarios).

URL: POST https://<omnileads_addr>/api/v1/makeCall

figure 4: endpoint new call request

field name	type	description
idExternalSystem	string	Es un parámetro opcional, debe enviarse en caso de que se quiera identificar a la campaña con el ID del sistema CRM externo
idCampaign	string	Es un parámetro obligatorio, debe corresponder al identificador de una campaña de OML. Si se envía el parámetro “idExternalSystem” debe corresponder con el campo «identificador externo» de una Campaña asociada al Sistema Externo indicado
idAgent	string	Es un parámetro obligatorio, debe corresponder al identificador de un Agente del sistema. Si se envía el parámetro “idExternalSystem” debe corresponder al campo «identificador externo» de un Agente asociado al Sistema CRM externo
idContacto	string	Es un parámetro opcional, si no es enviado se asume que es un contacto nuevo. De ser enviado debe corresponder al identificador de un Contacto de la base de datos de contactos de la Campaña. Si se envía el parámetro “idExternalSystem” deberá corresponder con el campo de la base de datos de contactos marcado como identificador externo

En caso de haber errores se devolverá un JSON con el campo “status”:”ERROR” y el detalle de los mismos en el campo “errors”. Caso contrario el valor del campo “status” será “OK”.

Endpoint listado de opciones de calificación

URL GET https://<omnileads_addr>/api/v1/campaign/<idc:integer>/dispositionOptions/ (1)

URL GET https://<omnileads_addr>/api/v1/campaign/<idc:string>/dispositionOptions/<ids:integer>/ (2)

Este método permite obtener un listado de las opciones de calificación disponibles para calificar a un contacto en una campaña Las credenciales deberán pertenecer a un Agente (Usuarios).

Los parámetros de este endpoint se especifican en la url. El mismo tiene dos formas de uso, si usa la variante (1), con un solo parámetro, el valor del parámetro “idc” deberá ser un entero especificando el id interno de una campaña de OML.

La variante (2) es para ser usada en la interacción desde un sistema de CRM externo hacia OML y en este caso el parámetro “ids” deberá especificar el id del sistema de CRM externo y el parámetro “idc” el identificador de una campaña en ese sistema sistema externo.

En el caso de que el endpoint se ejecute sin errores se devolverá un output con una lista de opciones de calificación indicando cuales de las opciones se encuentran ocultas parecidos al siguiente:

En caso de que se no ingrese un id de una campaña o sistema de CRM externo inexistente se devolverá un output parecido a:

Endpoint listado de calificaciones

Este método permite obtener un listado de las calificaciones que ha realizado un agente. Las credenciales deberán pertenecer a un Agente (Usuarios).

URL: GET https://<omnileads_addr>/api/v1/disposition/

En caso de no haber errores se devolverá la lista de calificaciones realizadas por el agente.

Endpoint crear nueva calificación

Esta endpoint habilita la posibilidad de «calificar» una gestión sobre un contacto. Cuando un usuario del CRM finaliza una gestión, es normal que se cierre con una calificación, por lo que con éste método el Sistema CRM externo puede impactar la calificación en OMniLeads. Las credenciales deberán pertenecer a un Agente (Usuarios).

URL: POST https://<omnileads_addr>/api/v1/disposition/

field name	type	description
idExternalSystem	integer	Parámetro opcional, si se especifica el sistema intentará localizar al contacto especificado buscando este valor como “id_externo” en la en la BD de la campaña. En caso de no especificarse el sistema asumirá que el valor del parámetro “idContact” es el id interno del contacto en OML
idContact	string	Id del contacto que se quiere calificar, el significado de su valor depende de si se especifica o no el parámetro “idExternalSystem”
idDispositionOption	integer	El id de la opción de calificación de la campaña con que se va a calificar al contacto, cada campaña define sus propias opciones de calificación, ver el endpoint que permite obtenerlas. La opción no debe estar oculta.
callid	string	Parámetro opcional, el id de la llamada
comments	string	Las observaciones del agente en la calificación

En caso de no haber errores se devolverá un output como este, con los datos de la nueva calificacion creada:

Si se intenta crear una nueva instancia de calificación a un contacto ya calificado en la campaña de devolverá el siguiente error

Si no se encuentra el id del contacto en la bd de la campaña se devolverá el siguiente mensaje de error:

Si no se encuentra el id de la opcion de calificación en la bd de la campaña, o la opción de calificación se encuentra oculta, se devolverá el siguiente mensaje de error:

Endpoint crear nuevo contacto y asignarle calificación

Esta endpoint habilita la posibilidad de «calificar» una gestión al mismo tiempo crear un contacto, es decir, se crea el contacto y se le asocia a la calificación que se va a crear Las credenciales deberán pertenecer a un Agente (Usuarios).

URL: POST https://<omnileads_addr>/api/v1/new_contact/disposition/

field name	type	description
phone	string	El número de teléfono del contacto
idExternalContact	string	Parámetro opcional, el id del contacto en un sistema de CRM externo
idDispositionOption	integer	El id de la opción de calificación de la campaña con que se va a calificar al contacto, cada campaña define sus propias opciones de calificación, ver el endpoint que permite obtenerlas. La opción no debe estar oculta.
comments	string	Las observaciones del agente en la calificación
callid	string	Parámetro opcional, el id de la llamada
<optional_bd_field>	string	Parámetros opcionales, pueden definirse valores para rellenar los datos del contacto a crear, los nombres de campos deben coincidir con los campos de la BD de la campaña

En caso de no haber errores se devolverá un output como este, con los datos de la nueva calificacion creada:

Si no se encuentra el id de la opcion de calificación en la bd de la campaña, o la opción de calificación se encuentra oculta, se devolverá el siguiente mensaje de error:

Endpoint para modificar una calificación existente

Esta endpoint habilita la posibilidad de modificar una calificación existente en OMniLeads.

Las credenciales deberán pertenecer a un Agente (Usuarios).

URL: PUT https://<omnileads_addr>/api/v1/disposition/<idDisposition>

field name	type	description
idExternalSystem	integer	Parámetro opcional, si se especifica el sistema intentará localizar al contacto especificado buscando este valor como “id_externo” en la en la BD de la campaña. En caso de no especificarse el sistema asumirá que el valor del parámetro “idContact” es el id interno del contacto en OML
idContact	string	Id del contacto que se quiere calificar, el significado de su valor depende de si se especifica o no el parámetro “idExternalSystem”
idDispositionOption	integer	El id de la opción de calificación de la campaña con que se va a calificar al contacto, cada campaña define sus propias opciones de calificación, ver el endpoint que permite obtenerlas. La opción no debe estar oculta en caso de que se cambie la original.
callid	string	Parámetro opcional, el id de la llamada
comments	string	Las observaciones del agente en la calificación

Si no existe error se devolverá el siguiente tipo de output:

Si en la url se especifica un id de calificación inexistente se devolverá el siguiente output de error:

Si se intenta modificar la instancia de calificación, cambiando los parámetros “idContact” y “idDispositionOption’y se encuentra que podrían existir dos calificaciones para un mismo contacto en una campaña se mostrará el siguiente mensaje de error:

Si no se encuentra el id del contacto en la bd de la campaña se devolverá el siguiente mensaje de error:

Si no se encuentra el id de la opcion de calificación en la bd de la campaña, o la nueva opción de calificación se encuentra oculta, se devolverá el siguiente mensaje de error:

API de Sesión de Agente en Asterisk

Endpoints de la API utilizados por el WebPhone mediante los cuales puede controlar las sesiones del agente en Asterisk.

• API de sesión de Agente en Asterisk

  • Inicio de sesión de agente en Asterisk

  • Cierre de sesión de agente en Asterisk

  • Ingreso en pausa de agente

  • Salida de pausa de agente

Endpoint para obtener las credenciales SIP de Agente

Este enpoint provee las credenciales necesarias para autenticar al agente en el servidor SIP mediante un WebPhone.

URL: GET https://<omnileads_addr>/api/v1/sip/credentials/agent/