OMniLeads RESTful API¶
This section is destinated to developers that want to execute an integration between its CRM system and OMniLeads. For that reason, the terminology and information provided here has software developers as its public target.
OMnileads offers a RESTful API base on HTTPS / JSON. This API allows access to system resources and services by outside of the user web interface, allowing this way that external systems could communicate in a simple way with OMniLeads.
The authentication methods available for this API are: Session (the agent must be logged on the system via web interface) and Token (using its credentials to obtaing a token)” and then passing it on the headers of the request:
“”Authorization: Bearer <token value>””
For example:
Note
In new releases this section will increase, in order to add new endpoints.
Then when describe the availables endpoints
Login Endpoint¶
This endpoint allows to authenticate as a system user, in case of success, it allows access to others availables endpoints depending of the user profile
URL: POST https://<omnileads_addr>/api/v1/login
figure 1: endpoint login request
| filed name | type | description |
|---|---|---|
| username | string | username value generated from the OML users creation menu |
| password | string | password value generated from the OML users creation menu |
Successful authentication
If the login is successful, the endpoint shows the following output:
figure 2: endpoint login request ok
As shown in the picture, a successful login, returnsfields like security “token”. This token must be used on next requests to the API from the authenticated user. Also, in the field “expires_in” indicates the token lifetime
In case that the system makes a request and the security token has expired, then a new authentication request must be done.
Note
The security token’s lifetime can be configured modifying the “TOKEN_EXPIRED_AFTER_SECONDS” parameter located on “/opt/omnileads/ominicontacto/ominicontacto/settings/production.py”
Authentication failed
If the login failed, the endpoint returns the following output:
figure 3: endpoint login request fail
Endpoint to obtain Contact database structure¶
This endpoint makes possible to obtain information fields informationof contacts database related to a campaign. With this information is possiblethen to create a new contact. The credentials must belong to an Agent(Users) or a Supervisor (Users) associated to a campaign
URL: POST https://<omnileads_addr>/api/v1/campaign/database_metadata/
| filed name | type | description |
|---|---|---|
| idExternalSystem | integer | Optional parameter, if sent the system tries to locate the contact as ‘external_id’ on the Campaign contacts database. If not sent, the system will assume that the value of the paramater ‘idContact’ is the intern id on OML |
| idCampaign | string | Contact identifier to tag, its value depends on if ‘idExternalSystem’ parameter is sent |
In case of no errors ocurred it will show an output like this, with data of the new disposition created
The ‘fields’ field indicate the list of all the fields of a contact database.The field ‘main_phone’ indicates which is the field correspondent to the main numberThe field ‘external_id’ indicates which field correspond to the external id of contact.When the database doesn’t have external id, the ‘external_id’ field will be None.
In case of errors ocurred, the endpoint returns a JSON with the field ‘status’:’ERROR’ and the detailed information of the error on the field’errors’. On other case the ‘status’ field value will be ‘OK’
Endpoit to create contact¶
This endpoint allows to add a contact in a database referred to a campaign.The credentials must belong to an Agent(Users) or a Supervisor (Users)associated to a campaign
URL: POST https://<omnileads_addr>/api/v1/new_contact/
| filed name | type | description |
|---|---|---|
| idExternalSystem | integer | Optional parameter, if sent the system tries to locate the contact as ‘external_id’ on the Campaign contacts database. If not sent, the system will assume that the value of the paramater ‘idContact’ is the intern id on OML |
| idCampaign | string | Contact identifier to tag, its value depends on if ‘idExternalSystem’ parameter is sent |
Also, it must send the values of the fields correspondent to the contactdatabase, and their names can be obtained with using the endpoint: Obtain Contact databse structure (Endpoint to obtain Contact database structure). Is mandatory to send the value to the field ‘main_phone’, and in case the database has external id, the field’s value ‘external_id’ mustn’t exist previously in other contact of database.
In case of no errors ocurred it will show an output like this, with data of the new disposition created
In case of errors ocurred, the endpoint returns a JSON with the field ‘status’:’ERROR’ and the detailed information of the error on the field’errors’. On other case the ‘status’ field value will be ‘OK’
Call generator endpoint¶
Allows to generate 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
| filed name | type | description |
|---|---|---|
| idExternalSystem | string | Optional parameter, it must be sent if needed to link campaign with the external CRM system |
| idCampaign | string | Required parameter, must match with an OML campaign identifier. If the parameter ‘idExternalSystem’ is sent, it must match with the field “external identifier” of a campaign associated to the External System specified |
| idAgent | string | Required parameter, must match to a system Agent identifier. If the parameter ‘idExternalSystem’ is sent must match to the field “external identifier”of an Agent associated to the external CRM System |
| idContact | string | Optional parameter, if is not sent the system assumes that is a new contact. If sent must match with an identifier of the campaing databasecontact. If the ‘idExternalSystem’ is sent, it must match with the contacts database field marked as an external identifier |
In case of errors ocurred, the endpoint returns a JSON with the field ‘status’:’ERROR’ and the detailed information of the error on the field’errors’. On other case the ‘status’ field value will be ‘OK’
Disposition options list endpoint¶
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 endpoint allows to get a disposition options list avalaible for tag a contact on a campaign. The credentials must belong to an Agent (Users).
The parameters for this endpoint must be specified on the url. It has two modes to use, if it uses the (1) mode, with a single parameter, the ‘idc’ parameter value must be an integer specifying the OML intern campaignidentifier
The mode (2) is for using the endpoint from an external CRM system to OML and in this case the parameter ‘ids’ must indicates an external CRM system id and the ‘idc’ parameter must indicates the identifier of one campaign in this external system
In case of the execution without errors the endpoint will return a disposition options list like the following:
In case that the id does not match with an id of a campaign or CRM system the endpoint will return an output like:
Dispositions list endpoint¶
This endpoint allows get a dispositions list made by the agent who make the request. (Users)
URL: GET https://<omnileads_addr>/api/v1/disposition/
In case of no errors ocurred, it returns the dispositions list made it by the agent
Create new disposition endpoint¶
This endpoint allows to “tag” the result of a management about a contact. When a CRM user ends a management, it is normal that management closes with a disposition made, and using this endpoint an External CRM System can integrate this action to OML. The credentials used must belong to an Agent (Users).
URL: POST https://<omnileads_addr>/api/v1/disposition/
| filed name | type | description |
|---|---|---|
| idExternalSystem | integer | Optional parameter, if sent the system tries to locate the contact as ‘external_id’ on the Campaign contacts database. If not sent, the system will assume that the value of the paramater ‘idContact’ is the intern id on OML |
| idContact | string | Contact identifier to tag, its value depends on if ‘idExternalSystem’ parameter is sent |
| idDispositionOption | integer | The disposition option campaign id that will be used to tag the contact, each campaign defines its disposition options. See the endpoint that allows to obtain that values |
| callid | string | Optional parameter, call identifier |
| comments | string | The agent observations in the disposition |
In case of no errors ocurred it will show an output like this, with data of the new disposition created
If an attempt to create a new disposition instance is made, to a contact already tagged on the campaign, the endpoint will return the following error:
If the contact id on the campaign database is not found the endpoint will return the following error:
If the disposition option id is not found the endpoint will return the following error:
Create new contact and assign it a new disposition endpoint¶
This endpoint allows to ‘tag’ a management and, at a same time, to create a contact, it means that it creates the contact and the disposition is linked to this new contact. The credentials used must belong to an Agent (Users).
URL: POST https://<omnileads_addr>/api/v1/new_contact/disposition/
| filed name | type | description |
|---|---|---|
| phone | string | The contact phone number |
| idExternalContact | string | Optional parameter, the contact id on an external CRM system |
| idDispositionOption | integer | The disposition option campaign id that will be used to tag the contact, each campaign defines its disposition options. See the endpoint that allows to obtain that values |
| comments | string | The agent observations in the disposition |
| callid | string | Optional parameter, call identifier |
| <optional_bd_field> | string | Optional parameters, they can define values to fill the custom data” of the contact that will be created, the field names must match with the fields of campaign database |
In case of no errors ocurred it will show an output like this, with data of the new disposition created
If the disposition option id is not found the endpoint will return the following error:
Disposition update endpoint¶
This endpoint allows to update an existent disposition in OMniLeads
The credentials must belong to an Agent (Users)
URL: PUT https://<omnileads_addr>/api/v1/disposition/<idDisposition>
| filed name | type | description |
|---|---|---|
| idExternalSystem | integer | Optional parameter, if sent the system tries to locate the contact as ‘external_id’ on the Campaign contacts database. If not sent, the system will assume that the value of the paramater ‘idContact’ is the intern id on OML |
| idContact | string | Contact identifier to tag, its value depends on if ‘idExternalSystem’ parameter is sent |
| idDispositionOption | integer | The disposition option campaign id that will be used to tag the contact, each campaign defines its disposition options. See the endpoint that allows to obtain that values |
| callid | string | Optional parameter, call identifier |
| comments | string | The agent observations in the disposition |
If doesn’t exist, the endpoint returns the following output:
If in the url a non-existent disposition id is specified, the endpoint will return the following output error:
If the disposition instance is tried to be modified, changing the parameters ‘idContact’ and ‘idDispositionOption’ the system detects that this would make to disposition for the oen contact on the same campaing the endpoint will return the following error output:
If the contact id on the campaign database is not found the endpoint will return the following error:
If the disposition option id is not found the endpoint will return the following error:
Asterisk Agent Session API¶
API endpoints used by the WebPhone to control the Asterisk’s Agent sessions.
