📌OMniLeads RESTful API
Última actualización
Última actualización
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.
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 |
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).
If the login is not successful, the method returns the following output:
figure 3: endpoint login request fail
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”.
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”.
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”.
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:
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.
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:
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:
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:
API endpoints used by WebPhone through which you can control agent sessions in Asterisk.
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/
