📌OMniLeads RESTful API

OMniLeads RESTful API

This section is intended for developers who wish to run an integration between the CRM system they maintain and OMniLeads.

Therefore, the terminology and information presented here is intended for software developers. OMniLeads has a RESTful API based on HTTPS / JSON. The API allows access to system resources and services outside the web user interface, thus allowing external systems to easily integrate with OMniLeads.

The authentication methods available to use this API are by Session (the agent must be logged into the system) and by Token (from the login to the API, with the parameters user and agent pass), in this case the following line must be passed in the request headers:

«Authorization: Bearer <token obtenido>»

Example:

Note

As new releases progress, this section will always be expanded as new endpoints emerge as the releases progress.

The available endpoints are described below.

Login Endpoint

This method provides the possibility of authenticating as a system user, and then (in case of a successful login) accessing other available endpoints depending on the user profile with which said login was performed.

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

Successful Authentication

If the login is successful, the method returns the following output (with option to return agent_id in response field):

figure 2: endpoint login request ok

As you can see in the figure, a successful login returns, among other fields, a security token. This token must be used in future API requests from the authenticated user.

In addition, the “expires_in” field sets the lifetime of the generated token. If the system launches a request and the security token has expired, then a new authentication must be performed.

Note

The duration of the security token is configured under the parameter “TOKEN_EXPIRED_AFTER_SECONDS” in the file “/opt/omnileads/ominicontacto/ominicontacto/settings/production.py”, now available as a parameterization variable in the Ansible inventory file (inventory.yml).

Authentication failed

If the login is not successful, the method returns the following output:

figure 3: endpoint login request fail

Endpoint get Contact Database structure

This endpoint enables the possibility of obtaining information from the fields of a campaign's contact database. With this information, it will then be possible to create a contact. The credentials must belong to an Agent or a Supervisor who are associated with the campaign.

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

field name	type	description
idExternalSystem	integer	Optional parameter, if specified the system will try to locate the specified campaign by searching for this value as the “external_id” of the campaign. If not specified the system will assume that the value of the “idCampaign” parameter is the internal id of the campaign in OML
idCampaign	string	Id of the campaign to which the database belongs, the meaning of its value depends on whether the “idExternalSystem” parameter is specified or not

If there are no errors, an output like this will be returned, with the data from the database fields:

The “fields” field indicates the list of all the fields in the database. The “main_phone” field indicates which field corresponds to the main phone number. The “external_id” field indicates which of the fields corresponds to the external identifier of the contact. If the database does not have an external identifier field, the “external_id” field will have the value None.

In case of errors, a JSON will be returned with the “status” field: “ERROR” and the details of the errors in the “errors” field. Otherwise, the value of the “status” field will be “OK”.

Endpoint contact creation

This endpoint enables the ability to add a contact to a campaign's contact database. The credentials must belong to an Agent or a Supervisor who is associated with the campaign.

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

field name	type	description
idExternalSystem	integer	Optional parameter, if specified the system will try to locate the specified campaign by searching for this value as the “external_id” of the campaign. If not specified the system will assume that the value of the “idCampaign” parameter is the internal id of the campaign in OML
idCampaign	string	Id of the campaign to which the database belongs, the meaning of its value depends on whether the “idExternalSystem” parameter is specified or not

In addition, the values ​​of the fields corresponding to the contact data must be sent, and their names can be obtained with the endpoint to obtain the structure of the Contact Database (Endpoint to obtain the structure of the Contact Database). It is mandatory to send a value for the field indicated as “main_phone”, and in case the database has an external identifier field, the value of the field indicated as “external_id” must not previously exist in another contact in the database.

If there are no errors, an output like this will be returned, with the contact data and its OML ID:

If there are errors, a JSON will be returned with the field “status”:”ERROR” and the details of the errors in the field “errors”. Otherwise, the value of the “status” field will be “OK”.

Endpoint for call generation

Allows generating calls (click to call) from an External CRM System. The credentials must belong to an Agent (Users).

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

figure 4: endpoint new call request

field name	type	description
idExternalSystem	string	It is an optional parameter, it must be sent in case you want to identify the campaign with the ID of the external CRM system.
idCampaign	string	It is a mandatory parameter, it must correspond to the identifier of an OML campaign. If the parameter “idExternalSystem” is sent, it must correspond to the “external identifier” field of a Campaign associated with the indicated External System.
idAgent	string	It is a mandatory parameter, it must correspond to the identifier of an Agent in the system. If the parameter “idExternalSystem” is sent, it must correspond to the “external identifier” field of an Agent associated with the external CRM System.
idContacto	string	It is an optional parameter, if it is not sent it is assumed that it is a new contact. If sent it must correspond to the identifier of a Contact in the Campaign's contact database. If the parameter “idExternalSystem” is sent it must correspond to the field in the contact database marked as an external identifier.

If there are errors, a JSON will be returned with the field “status”:”ERROR” and the details of the errors in the field “errors”. Otherwise, the value of the “status” field will be “OK”.

Endpoint listing of rating options

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)

This method allows you to obtain a list of the rating options available to rate a contact in a campaign.

The credentials must belong to an Agent (Users). The parameters of this endpoint are specified in the URL. It has two ways of use, if you use variant (1), with a single parameter, the value of the parameter “idc” must be an integer specifying the internal id of an OML campaign.

Variant (2) is to be used in the interaction from an external CRM system to OML and in this case the parameter “ids” must specify the id of the external CRM system and the parameter “idc” the identifier of a campaign in that external system. In the event that the endpoint is executed without errors, an output will be returned with a list of rating options indicating which of the options are hidden similar to the following:

If the ID of a non-existent campaign or external CRM system is not entered, an output similar to the following will be returned:

Endpoint call disposition list

This method allows you to obtain a list of the ratings that an agent has made. The credentials must belong to an Agent (Users).

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

If there are no errors, the list of ratings made by the agent will be returned.

Endpoint create new rating

This endpoint enables the possibility of "rating" a transaction on a contact. When a CRM user finishes a transaction, it is normal for it to be closed with a rating, so with this method the external CRM System can impact the rating in OMniLeads. The credentials must belong to an Agent (Users).

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

field name	type	description
idExternalSystem	integer	Optional parameter, if specified the system will try to locate the specified contact by searching for this value as “external_id” in the campaign database. If not specified the system will assume that the value of the “idContact” parameter is the internal id of the contact in OML.
idContact	string	Id of the contact to be rated, the meaning of its value depends on whether or not the “idExternalSystem” parameter is specified
idDispositionOption	integer	The id of the campaign rating option with which the contact will be rated. Each campaign defines its own rating options, see the endpoint that allows you to obtain them. The option must not be hidden.
callid	string	Optional parameter, the call id
comments	string	Agent's remarks in the rating

If there are no errors, an output like this will be returned, with the data of the new qualification created:

If you try to create a new qualification instance for a contact already qualified in the campaign, the following error will be returned

If the contact id is not found in the campaign database, the following error message will be returned:

If the rating option id is not found in the campaign database, or the rating option is hidden, the following error message will be returned:

Endpoint create new contact and assign rating to it

This endpoint enables the possibility of "qualifying" a management at the same time as creating a contact, that is, the contact is created and associated with the qualification to be created. The credentials must belong to an Agent (Users).

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

field name	type	description
phone	string	The contact's phone number
idExternalContact	string	Optional parameter, the contact id in an external CRM system
idDispositionOption	integer	The id of the campaign rating option with which the contact will be rated. Each campaign defines its own rating options, see the endpoint that allows you to obtain them. The option must not be hidden.
comments	string	Agent's remarks in the rating
callid	string	Optional parameter, the call id
<optional_bd_field>	string	Optional parameters, values ​​can be defined to fill in the data of the contact to be created, the field names must match the fields in the campaign database.

If there are no errors, an output like this will be returned, with the data of the new qualification created:

If the rating option id is not found in the campaign database, or the rating option is hidden, the following error message will be returned:

Endpoint to modify an existing rating

This endpoint enables the ability to modify an existing rating in OMniLeads.

Credentials must belong to an Agent (Users).

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

field name	type	description
idExternalSystem	integer	Optional parameter, if specified the system will try to locate the specified contact by searching for this value as “external_id” in the campaign database. If not specified the system will assume that the value of the “idContact” parameter is the internal id of the contact in OML.
idContact	string	Id of the contact to be rated, the meaning of its value depends on whether or not the “idExternalSystem” parameter is specified
idDispositionOption	integer	The id of the campaign rating option that the contact will be rated with. Each campaign defines its own rating options, see the endpoint that allows you to get them. The option should not be hidden in case the original option is changed.
callid	string	Optional parameter, the call id
comments	string	Agent's remarks in the rating

If there is no error, the following type of output will be returned:

If a non-existent rating id is specified in the URL, the following error output will be returned:

If you try to modify the rating instance by changing the parameters “idContact” and “idDispositionOption” and you find that there could be two ratings for the same contact in a campaign, the following error message will be displayed:

If the contact id is not found in the campaign database, the following error message will be returned:

If the rating option id is not found in the campaign database, or the new rating option is hidden, the following error message will be returned:

Agent Session API in Asterisk

API endpoints used by WebPhone through which you can control agent sessions in 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 to obtain SIP Agent credentials

Eset endpoint provides the necessary credentials to authenticate the agent on the SIP server using a WebPhone.

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