📌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 nametypedescription

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 (con opción de devolver el agent_id en campo respuesta):

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», hoy disponible como variable de parametrización en el archivo de inventario de Ansible (inventory.yml).

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 nametypedescription

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 nametypedescription

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 nametypedescription

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

idContact

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

phone

string

Es un parámetro obligatorio, corresponde al número a marcar.

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 nametypedescription

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 nametypedescription

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 nametypedescription

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:

Endpoint para Consultar Estado de Agentes y Cantidad de Llamadas

Estos endpoints habilitan la posibilidad de consultar en tiempo real los estados de agentes y llamadas en campaña, a los efectos de publicarlos en sistemas externos o bots de negocio:

GET

URL: api/v1/agent_status/campaign/<int:campaign_id>

Headers

field

type

Authorizationrequired

Bearer

Bearer xxxxx

Parameters

field

type

Description

campaign_id required

Number

Campaign unique ID

Response

200 Success

field

type

Description

ready

Number

Cantidad de agentes en estado ready

oncall

Number

Cantidad de agentes en llamada

pause

Number

Cantidad de agentes en pausa

4XX Not Found

Name

Description

CampanaNotFound

The campaign_id of the Campana was not found.

Forbidden

Las credenciales de autenticación no se proveyeron.

500 Internal Server Error

Name

Description

InternalServerErrorrequire

The server encountered an internal error

Ejemplos:

{“ready”: 2, “oncall”: 0, “pause”: 2}

GET

URL: api/v1/call_status/campaign/<int:campaign_id>

Headers

field

type

Authorizationrequired

Bearer

Bearer xxxxx

Parameters

field

type

Description

campaign_id required

Number

Campaign unique ID

date_start optional

Date

Format %Y-%m-%d

date_end optional

Date

Format %Y-%m-%d

Response

200 Success

field

type

Description

attended

Number

Cantidad de llamadas atendidas

abandoned

Number

Cantidad de llamadas abandonas

expired

Number

Cantidad de llamadas expiradas

4XX Not Found

Name

Description

CampanaNotFound

The campaign_id of the Campana was not found.

Forbidden

Las credenciales de autenticación no se proveyeron.

500 Internal Server Error

Name

Description

InternalServerErrorrequire

The server encountered an internal error

Ejemplos:

{“attended”: 2, “abandoned”: 0, “expired”: 2}

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.

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/

Última actualización