📌OMniLeads RESTful API
Última actualización
Última actualización
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.
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
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
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/
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”.
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/
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”.
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
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”.
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:
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.
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/
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:
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/
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:
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>
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:
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>
field
type
Authorizationrequired
Bearer
Bearer xxxxx
Parameters
field
type
Description
campaign_id required
Number
Campaign unique ID
Response
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
Name
Description
CampanaNotFound
The campaign_id of the Campana was not found.
Forbidden
Las credenciales de autenticación no se proveyeron.
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>
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
field
type
Description
attended
Number
Cantidad de llamadas atendidas
abandoned
Number
Cantidad de llamadas abandonas
expired
Number
Cantidad de llamadas expiradas
Name
Description
CampanaNotFound
The campaign_id of the Campana was not found.
Forbidden
Las credenciales de autenticación no se proveyeron.
Name
Description
InternalServerErrorrequire
The server encountered an internal error
Ejemplos:
{“attended”: 2, “abandoned”: 0, “expired”: 2}
Este endpoint habilita la posibilidad de consultar en tiempo real los estados de agentes en modo lista:
GET
URL: api/v1/agent_status_list/campaign/<int:campaign_id>
field
type
Authorizationrequired
Bearer
Bearer xxxxx
Parameters
field
type
Description
campaign_id required
Number
Campaign unique ID
Response
Success 200. Array of objects:
field
type
Description
name
String
Nombre del agente
status
String
Estado del agente
Error 4xx
Name
Description
CampanaNotFound
The campaign_id of the Campana was not found.
Forbidden
Las credenciales de autenticación no se proveyeron.
Name
Description
InternalServerErrorrequire
The server encountered an internal error
Example response:
[{"name":"Kirk Mccall","status":"OFFLINE"},{"name":"Kimberly Leonard","status":"PAUSE"}]
Endpoints de la API utilizados por el WebPhone mediante los cuales puede controlar las sesiones del agente en Asterisk.
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/
