retailCRM Documentation

Integration procedure of virtual PBX with the system

Capabilities of integration the system and virtual PBX

System API for telephony allows:

  1. Initiate call from the system
  2. Upload calls history to the system
  3. Get responsible manager by phone number for incoming calls routing
  4. Notify system about call events

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:

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.

Registering and setting the telephony

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.

Extention codes

Setting correspondence between extention codes and users can be done in two ways:

If telephony settings have field makeCallUrl filled and the authorized system user has specified extention code, the pages will get a phone icon.

External numbers

You can set correspondence of external numbers and shops in two ways:

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.

Example of telephony creating/editing

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",
    "accountUrl": "http://api.telephony-test.com/settings",
    "integrations": {
        "telephony": {
            "clientId": "2dbh26tahjj26sg",
            "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 telephony

Getting information about integration with telephony is performed with the help of method GET /api/v5/integration-modules/{code}

Calls history uploading

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:

History uploading immediately after call

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.

Periodical calls history uploading

PBX sends to system periodically (for example, every 10 minutes) history of calls, which accumulated since the last upload.

Call records

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:

For correct audio playing you need to specify corect Content-Type heading.

Getting of responsible manager

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.

Call events

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
}

Call initiation

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:

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

System user status change notification

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:

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.


PrintEditHistory
Page last modified on October 31, 2017, at 09:48 AM