System API for telephony allows:
Working with API is produced in accordance with API rules. For integration are used API-methods of section Telephony.
Virtual PBX and system integration algorythm:
USER
Request system access API-key from user
API
Register new telephony
API | USER
Fill system users extention numbers specify correspondence when registering telephony
API | USER
Fill external telephone numbers or specify correspondence when registering telephony
API
Upload call history from virtual PBX to the system
API
Use data of responsible manager when allocating calls
API
Send notifications about call events to the system
Steps with mark [USER] are the steps where data must be filled in by user. The rest steps with mark [API] are made by API-requests.
Registration of new telephony and settings change of existing should be made by method POST /api/v5/integration-modules/{code}/edit. If telephony with code code
already exists, method changes it settings, otherwise the new telephony will be created. During telephony registration a unique code clientId
is passed in method. This code allows to identify in telephony account the system, from which the request makeCallUrl
arrives.
If issue false
in the field allowEdit
, integration settings editing will be available only through API. Only deletion of integration will be available for system users.
In the field makeCallUrl
the address is issued, to which the system will send queries for call initiation.
In the field changeUserStatusUrl
the address is issued, to which the system will send queries for system user status change notification.
Setting correspondence between extention codes and users can be done in two ways:
additionalCodes
in telephony creating/editing method.
If telephony settings have field makeCallUrl
filled and the authorized system user has specified extention code, the pages will get a phone icon.
You can set correspondence of external numbers and shops in two ways:
externalPhones
in telephony creating/editing method.
If telephony settings have external numbers set and the call is initiated from an entity interfaced with the shop, then externalPhone
parameter will be issued tomakeCallUrl
address.
If externalPhone
parameter is set in call event and telephony settings have this external number, the pop-up window will display information about call direction. For example to Shop 1.
For example, there is a system https://example.retailcrm.ru
. There are 2 users in the system with ID 1
, 2
and two shops with symbol codes shop1
, shop2
.
On the telephony side there are extention numbers 100
, 200
and external numbers +7-499-999-99-99
, +7-499-888-88-88
.
For creating/editing telephony with code my-telephony
you need to send POST
-query to https://example.ecomlogic.com/api/v5/integration-modules/my-telephony/edit
address with integrationModule
parameter as a JSON value:
{
"code": "my-telephony",
"active": true,
"name": "Telephony name",
"logo": "http://api.telephony-test.com/logo.svg",
"clientId": "2dbh26tahjj26sg"
"accountUrl": "http://api.telephony-test.com/settings",
"integrations": {
"telephony": {
"makeCallUrl": "http://api.telephony-test.com/make-call",
"allowEdit": false,
"inputEventSupported": true,
"additionalCodes":[
{"userId":"1", "code":100},
{"userId":"2", "code":200}
],
"externalPhones":[
{"siteCode":"shop1", "externalPhone":"+7-499-999-99-99"},
{"siteCode":"shop2", "externalPhone":"+7-499-888-88-88"}
],
"changeUserStatusUrl": "http://api.telephony-test.com/change-status"
}
}
}
Response
HTTP/1.1 201 OK
{
"success": true
}
Getting information about integration with telephony is performed with the help of method GET /api/v5/integration-modules/{code}
For calls history uploading needs to use method POST /api/v5/telephony/calls/upload. It is possible to save up to 50 calls per one request. PBX can upload history using one of two strategies:
After the fact of the outgoing or incoming call, PBX sends to system the history about this call. Thus in request will be transmitted one history record, as a rule.
PBX sends to system periodically (for example, every 10 minutes) history of calls, which accumulated since the last upload.
A link to call record is issued in calls[][recordUrl]
field.
If you try to hear a call, system will send GET
-query to calls[][recordUrl]
with paramenters:
clientId
— is a unique system code, transferred by telephony when registered
For correct audio playing you need to specify corect Content-Type
heading.
Method GET /api/v5/telephony/manager allows to transmit phone number, by which the system tries to find customer and return the responsible manager for this customer, if any. This method is useful for incoming call routing on extension of responsible manager.
Manager is considered to be free if he is authorized in system and has set free status. More than that an extention code needs to be set for the manager in integration settings. If one of these conditions is not set, the responsible manager will not be returned by the method.
By method POST /api/v5/telephony/call/event possible to inform system about call events. Need to transmit three types of events: incoming call, outgoing call and the end of call. At the moment of incoming call event transmittion, the manager who gets call will see call card.
For example, the system https://example.ecomlogic.com
has active telephony integration. Extention numbers 100, 200 and external numbers +7-499-999-99-99, +7-499-888-88-88 are created in the system.
You need to send a POST
-query to the address https://example.ecomlogic.com/api/v5/telephony/call/event
with an event
, parameter as a JSON value:
{
"phone": "+7-555-555-55-55",
"type": "in",
"codes":["100"],
"externalPhone": "+7-444-444-44-44"
}
Response
HTTP/1.1 200 OK
{
"success": true
}
When setting integration, the address is transferred in the field configuration["makeCallUrl"]
on which the system will be sending queries of call initiation.
System is sending a query GET {configuration["makeCallUrl"]} with parameters:
clientId
— is a unique system code, transferred when registering telephony
code
— extention code of the user who initiates the call
phone
— telephone number, to which the call is initiated to
userId
— ID of system user
externalPhone
— external telephone number, if present in telephony settings.
In case of succesful call inititation PBX should return HTTP-status 200
. Otherwise any other status which will be interpreted as call nitiation error, user will be informed about it. HTTP-response body will be ignored.
Example of request on makeCallUrl
For example, makeCallUrl-address https://api.telephony-test.com/make-call
has been registered. Manager with extension 100
and id 1
calls customer with phone number +7 (912) 123-45-67.
Query
https://api.telephony-test.com/make-call?clientId=2dbh26tahjj26sg&code=100&phone=+79121234567&userId=1
Response
HTTP/1.1 200 OK
If telephony settings has field changeUserStatusUrl
filled and authorized system user has extention number set, the system will send requests for notification about user status change in the system.
System sends query GET {configuration["changeUserStatusUrl"]} with following parameters:
clientId
— unique system code, transferred when registering telephony
userId
— ID of system user
code
— extention code of the user, whose status has been changed
status
— new status of user in the system.
status
field can take values: [free|busy|dinner|break]
Example of a query to changeUserStatusUrl
For example there is a registered changeUserStatusUrl-address http://api.telephony-test.com/change-status
. Manager with extension code 100
and ID 1
changed status to busy
.
Query
http://api.telephony-test.com/change-status?clientId=2dbh26tahjj26sg&code=100&userId=1&status=busy
Body and status of HTTP-response are ignored.