API for developers¶

If you are developer or integrator, you can integrate your information system or business application with “Virtual Mobile PBX” using the HTTP API.

Basic call information¶

The interface allows you to get basic information about the calls made by subscribers of your “Virtual Mobile PBX” for a certain period of time.

Note

Basic information about calls is available for all numbers of Virtual Mobile PBX that have “Convergent” service package. It doesn’t require additional “API FMC” service plan.

Note

You will need an authorization token (FMC Token) to use API, which you can get in “CRM Integration” section of your “Virtual Mobile PBX” integration Web-portal, that is available at the link https://fmc.kyivstar.ua/crm-integration (use your “Virtual Mobile PBX” admin login and password).

Information is provided in several formats: CSV, JSON and XML. Use a URL with appropriate method suffix to select the data format you need.

HTTP method:

GET

Method URL:

https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv

or

https://fmc.kyivstar.ua/api/cdr/v1/callstat.json

or

https://fmc.kyivstar.ua/api/cdr/v1/callstat.xml

Parameters:

token (required)

64-character authorization key

Example: “868b26d121e50f3b9e715bd86e77f2d6dbef354e7a9bcdb0aae0a0868a32e4a1”

from (required)

Timestamp in format “YYYY-MM-DDTHH:MM:SS”

Start of time interval

Example: “2017-04-29T14:25:00”

to (required)

Timestamp in format “YYYY-MM-DDTHH:MM:SS”

End of time interval

Example: “2017-05-03T17:24:55”

names (optional)

Flag (possible values “on” or “off”)

Adds to data subscriber’s names which were found in the address book of your “Virtual Mobile PBX”

Default value - “off”

departments (optional)

Flag (possible values “on” or “off”)

Adds to data subscriber’s department name which were found in the address book of your “Virtual Mobile PBX”

Default value - “off”

ownership (optional)

Flag (possible values “on” or “off”)

Adds to data a sign of the subscriber’s belonging to an enterprise of your “Virtual Mobile PBX”

Default value - “off”

direction (optional)

Flag (possible values “on” or “off”)

Adds to data a call type: incoming or outgoing

Default value - “off”

Status codes:

200 OK: Successful request, the response contains a file with data in the selected format
400 Bad Request: One of the required parameters is missing or one of the parameters has an invalid value
403 Forbidden: Invalid authorization key specified
500 Internal Server Error: Internal integration server error

Remarks:

Timestamps are specified in the time zone Europe/Kyiv (EET/EEST)
Maximum period of time for one request is 7 days
Parameter from can’t be “older” than 30 days
The `` to`` parameter cannot be assigned a value in the “future”. `` to`` <= `` now``.
One of parameters from or to can be not specified. In this case it will be automatically calculated according to one of the following formulas:
- from = to - 7 days
- to = min(from + 7 days, now())

Request example:

GET /api/cdr/v1/callstat.json?token=868b26...32e4a1&from=2017-04-29T14:25:00&to=2017-05-03T17:24:55 HTTP/1.1
Host: fmc.kyivstar.ua

Response example:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Content-Disposition: attachment; filename="callstat_2017-04-29T14:25:00_2017-05-03T17:24:55.json"

{
    "calls": [
        {
            "end_timestamp": "2017-04-29 21:39:48",
            "start_timestamp": "2017-04-29 21:39:35",
            "calling_number": "0675376761",
            "duration": 14,
            "called_number": "0671234567",
        }
    ]
}

Request example using cURL utility:

curl -X GET \
  'https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv?token=868b26...32e4a1&from=2017-04-29T14:25:00&to=2017-05-03T17:24:55'

Request example on PHP:

<?php

$request = new HttpRequest();
$request->setUrl('https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'token' => '868b26...32e4a1',
  'from' => '2017-04-29T14:25:00',
  'to' => '2017-05-03T17:24:55'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Request example on Python:

import requests

url = "https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv"

querystring = {
    "token": "868b26...32e4a1",
    "from": "2017-04-29T14:25:00",
    "to": "2017-05-03T17:24:55"
}

response = requests.request("GET", url, params=querystring)

print(response.text)

Request example on Java:

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://fmc.kyivstar.ua/api/cdr/v1/callstat.csv?token=868b26....32e4a1&from=2017-04-29T14%3A25%3A00&to=2017-05-03T17%3A24%3A55")
  .get()
  .build();

Response response = client.newCall(request).execute();

Extended functionality¶

If you need additional API methods, allowing you to develop deeper integration with “Virtual Mobile PBX” you can use a service Generic FMC API that provides a rich set of methods for integration of your business application (like CRM, ERP, etc) with mobile telephony.

Detailed technical documentation in OpenAPI format is available at the link: https://fmc.kyivstar.ua/manual/openapi.html

Note

This service is only available for the phone numbers which are subscribed on “Converged” + “API FMC” service plans. The list of Kyivstar telephone numbers with the “API FMC” package can be seen in the “Extended Services” section of your “Virtual Mobile PBX” web portal at the address https://fmc.kyivstar.ua/provisioning.

Integration of “Virtual Mobile PBX” and Generic FMC API provides such opportunities:

Registering your webhook for Call states receiving;
Controlling phone calls (reject, etc);
Retrieving extended call history;
Fetching an mp3 file with call record;
Outgoing call initiation (click2dial);
“CLIP” - Changing calling number presentation via API;
“DND” - Changing DND (Do Not Disturb) settings via API;
Receiving information about phone status (free/busy) and DND status (on/off);

Note

Information about the configuration can be found in the chapter Integrartion with Generic FMC API.

Call states¶

The Generic FMC API will send to your application’s webook states of the phone call (alerting, established, finished). Each call state contains useful information that can be used for the integration of your application with a mobile network. Like call_control_id that can be used for call control, etc.

Call control¶

This method allows you to control a call. You can terminate the call - either reject it on the ringing (alerting) phase or terminate an already established call. Also, you can hold/unhold the established call. For call control operation you need to have call_control_id that can be received either from the call state webhook or from the Click2Dial method.

Call history¶

The main difference between extended call history from basic one, described above Basic call information, is the following:

Integrated with the call recording. You will receive a record_id if call was recorded. This record_id that can be used in the method Call recording for fetching an mp3 file;
There is information with ringing duration (the time while the phone was ringing until the call has been answered or rejected);
There is a call completion code (according to the specification ITU-T Q.850 https://www.itu.int/rec/T-REC-Q.850/), that will allow you to have the reason for call termination;

Call recording¶

This method provides you the possibility to fetch an mp3 file with a call recording.

Note

Phone call recording service is only provided for numbers that the Call recording feature has been purchased for.

Click2Dial¶

This function allows you to initiate a call from your phone to any number. You can use it for the implementation of Click2Dial functionality in your application.

CLIP¶

Some business processes require changing a calling number presentation to some “common”/”group”/”virtual” company number. Using this method you can do it automatically from your application.

DND¶

This functionality allows you to enable/disable DND (Do not disturb) on the phone via API.

Phone Status¶

Using this API method you can check if subscriber is avalable or busy. Also it check the status of DND function - on or off.