Skip to content

Call API

Getting started


Current document describes Call API, which allows you to make calls and manage them.

You can also manage calls received via virtual PBX. To do so you need a unique ID for your call session. You can get it from the REST API notification server.

API is based on JSON-RPC 2.0 specification and does not support team operation.

In case of a request to API, HTTP/1.1 with SSL/TLS connection protection is used as a transport protocol. In this case the following requirements should be met:

  • Title Content-Type has to be application/json; charset=UTF-8
  • Title Content-Length has to have correct message length, as required by HTTP/1.1 specification.


The following agreements are accepted:

  • Blank fields always return with a null value. In case of a rail an empty rail is returned, in case of an object an empty object returns;
  • All the fields related to time and date are transferred as according to ISO 8601 in the following format YYYY-MM-DDT hh:mm:ssZ;
  • Requests to API are always made using POST method;
  • All the settings in requests/replies, in the JSON data structure and in the names of the methods are entitled in the Snake Case style - with words separated by underscores;
  • The data returns only in JSON format as according to FC 7159 specification;
  • Data encoding UTF-8;

Authorizing IP address

By default access to API is denied for everyone. To enable inquiries, you need to add the host IP address used to make an inquiry to the whitelist. This can be done in your client area "Administrator -> Account -> Rules and safety regulations", tab "API".

Call API users

You can choose a new set of authorization rules in a form of a check box Access to Call API. Go to your client area "Account" -> "User administration" and enable Call API Basic set component.

This can only be done by the administrator.

Access by login and password

Authentication by login and password. Reply contains a key to access Call API

Default duration of a session is 1 hour.

Access by key

To enable access by key you need to go to your user settings and tick a box "Access by key". Be careful: you can see and copy the key only at the moment when it's generated. After you have saved the settings the key is only available in the application's code or another place where you're storing it.

Depending on your settings keys can be temporary or permanent.

Statistics and reports

You can access all requests to API in your client area "Reports" -> "Tech Log" -> "Requests to API". This excludes requests with errors:

  • If a JSON or a request structure error returns - mnemonics "parse_error" or "invalid_request";
  • If an error with the call for a non-existent method returns - mnemonics "method_not_found";
  • If an authentication error returns - "access_token_blocked", "access_token_invalid", "access_token_expired", "auth_error";
  • If an error that involves a request from an non-authorized IP returns - mnemonics "ip_not_whitelisted".

You can find detailed information about any call in "Reports" -> "Inquiries" -> "Calls" using filtering "Call session ID".

In case there is no "Call session ID" option in your filters, you need to add it to the available report's columns.

Managing security settings for calls

You can manage security settings for your calls (mobile, national, international) in your client area "Account" -> "Security rules and settings" -> "API".

By default international calls are not permitted. Other call types are allowed.

Permissions for calls are categorized by Call API components (refer to Components).


Title for client List of methods Description
Call API Basic set start.employee_call, start.vnumber_call, start.simple_call, login.user, logout.user, Basic set for Call API
Call API Call management,,, disconnect.leg,,,, list.calls, send.dtmf,,,, list.talk_options, call.talk_option A set that allows you to manage calls.
Call API Informer calls start.informer_call A set that allows you to call clients and play a TTS or another preset media file. As your informer message is complete the call ends automatically
Call API Call scenario start.scenario_call A set that allows you to call clients using a virtual number and a set of scenarios.

Return data format

Format MIME Type
JSON application/json

By default JSON format is used. Accept title is ignored.

Basic URL to access API

Basic URI to access API:<version>


<version> is an API version (refer to Versions)


Call API supports versioning. A version is specified in a basic URL as vX.Y, where X is a number of a major version, and Y is a number of a minor version.

Versions should be spelled using a dot, such as 4.0

If a new version is released, the previous one is considered outdated. Therefore if you send a request to an old version of API in meta parameters (refer to Meta parameters) the parameter current_version_depricated with value true will be returned. This means that within the next couple of months the old version may become unavailable.

Example: \b

Maximum number of supported versions is 2
Support period for old versions is 2 months

Limits and restrictions

Limits are based on points system, i.e. each method has a value measured in points.

Points are marked off only in case of a successful request, i.e. the request is marked as successful in a request report. A request is considered successful if the result is returned with a status success = true or with a call session ID.

Limits are tied to a component Call API Basic set (refer to Components) and are recognized depending on a method's value in points.

Data about limits returns in every reply in meta parameters (refer to Meta parameters), except when the limits are not recognized;

  • If JSON or request structure errors return - mnemonics "parse_error" or "invalid_request";
  • If an error involving call to an non-existent method returns - mnemonics "method_not_found";
  • If an authentication error returns - "access_token_blocked", "access_token_invalid", "access_token_expired", "auth_error";
  • If an error that involves a request from an non-authorized IP returns - mnemonics "ip_not_whitelisted".

Data about limits returns in meta parameters (refer to Meta parameters).

Expanding limits

You can manage limits in your client area "Account" -> "Rates and options".

Limits titles:

  • Call API points per minute;
  • Call API points per day;
  • TTS message length.

If you don't have any limits in your client area, you may have restrictions in your service plan. In this case you need to contact your personal manager or technical support.

Meta parameters

They return as a reply to a call for a method. They can be found both in a successful request or in a request with an error.

Parameter api_version returns only for versions that are deprecated.

Description of parameters

Parameter title Description
day_limit Current limit points per day
day_remaining Points left till daily limit
day_reset Seconds till daily limit is reset
minute_limit Current limit point per minute
minute_remaining Points till minute limit
minute_reset Seconds till minute limit is reset
current_version_depricated Indication that an old version may become unavailable within 2 months
current_version Current version
latest_version Latest version

JSON structure

"metadata": {
  "api_version": {
    "current_version_depricated": "boolean",
    "current_version": "string",
    "latest_version": "string"
  "limits": {
    "day_limit": "number",
    "day_remaining": "number",
    "day_reset": "number",
    "minute_limit": "number",
    "minute_remaining": "number",
    "minute_reset": "number"


Fields common for all methods

Title Type Required Valid value Description
id string or number yes Request to API unique ID.
Is not communicated in notifications. Is featured only in the the Request ID parameter of Statistics and reports
method string yes Called in method (refer to Methods list)
jsonrpc string yes 2.0 JSON-RPC specification number
params object yes Contains a request's to API body. The body changes depending on a method.

Call state diagram


Method Description
"login.user" Login
"logout.user" Logout

Group of methods to make calls

Method Description
"start_employee_call" The method implements a direct call to an employee and does not use any scenario.
"start.scenario_call" Method allows you to make calls according to a customized acenario. To use the method you only need a virtual phone number and N scenario.
"start.vnumber_call" Call to a virtual number.
"start.informer_call" Informer call with an option to play a media file for a subscriber or transmit a text message. After the message is played, the call ends automatically.
"start.simple_call" Call to any number except own virtual numbers. This is not a call from an employee to any number.

Group of methods for call management

Method Description
"" Make call for transfer or consulting.
"" Method allows transferring calls to another employee or to an external number (Refer to "Diagram of call statuses").
"" This method allows you to restore a conversation after a subscriber consulted another employee (refer to section "Diagram of call statuses").
"" Holding call.
"" Unholding call.
"" Tagging an active call.
"disconnect.leg" Method allows you to disconnect various legs of a call. You can access ID for each leg via the list.calls method or a notification server.
"" Adding a coach to a call.
"" Managing call recording. You can not switch off the recording of a call set via your client area.
"" Block a contact during call.
"call.talk_option" Calling talk option set in the client area of your virtual PBX.
"send.dtmf" Sending DTMF by an employee. The method is used when client side has IVR and it requires for you to choose a menu option.
"list.talk_options" Receiving a list of talk options set in the client area of your virtual PBX.
"list.calls" Receiving a list of active calls and their participants.
"" Releasing a call.

Error messages

Title Type Required Valid value Description
error object yes Object with error contents
code number Yes Code of error (refer to Group of error codes)
message string yes Error message (refer to List of errors common for all methods)
data object yes Object with error details
mnemonic string yes Unique text code of an error (refer to List of errors common for all methods. There is also errors that are specific for certain methods)
field string no

Name of the parameter, associated with error

Embedded parameters are displayed devided by a "dot": .

For example: employee.phone_number

value string no

Contains information transmitted by a client without any changes

In some cases it may be absent. For example, when a required parameter is not filled in.
params object no Map of parameters' substitutions for a template with a text about an error. I.e. Contains value that can be changed in dynamics, such as limits, TTS message length. Value from this parameter can be used in error messages in the interface above Call API (operator's workspace).
extended_helper string no Link to a page with more information about error and possible silutions

Example of an error

  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32602,
    "message": "Data supplied is of wrong type",
    "data": {
      "mnemonic": "data_type_error",
      "field": "contact",
      "value": "number",
      "params": {
        "object": null
      "extended_helper": null

Groups of error codes

Code of error Description
-32700 Errors related to JSON validation
-32600 Errors related to validating parameters of a request - id, jsonrpc
-32601 Errors related to methods
-32602 Errors related to validating parameters in a called methods
-32603 Internal errors of JSON RPC server
In case an error occurs, you need to enquire with technical support, and transmit a request that caused error, as well as the time of the request.
-32001 Authentication errors and errors with keys
-32002 Errors related to: security rules prohibit calls in given direction (refer to Security rules) and blacklist.
-32003 Errors with access right - ip address is not in the whitelist, a user does not have access right
-32004 Errors related to wrong order of called methods
-32007 Errors related to virtual number
-32008 Errors related to components
-32009 Errors related to an account.
In case an error occurs, you need to enquire with technical support, and transmit a request that caused error, as well as the time of the request.
-32029 Errors related to limits
-32099 Errors related to support of various JSON RPC 2.0 specifications - Group operations, Notifications

List of errors common for all methods

Text of message Code Mnemonics Description
Invalid Request The JSON sent is not a valid Request object -32600 invalid_request Errors related to validating parameters of a request - id, jsonrpc
Access token has been expired -32001 access_token_expired Applies only to a permanent token. If a token expires, the error returns
Access token has been blocked -32001 access_token_blocked If a permanent token is blocked, the error returns
Access token is invalid -32001 access_token_invalid The error returns if a permanent/temporary token is not found or a permanent token's lifespan is up
Limit per {limit_type} has been exceeded. Value of current limit per {limit_type} is {limit_max_value} -32029 limit_exceeded Limits of service plan are exceeded (refer to Limits and regulations)
Component {component_name} has been disabled -32008 component_disabled
Your IP {ip} is not whitelisted -32003 ip_not_whitelisted IP address of a request is not in the whitelist (refer to client area "Account" -> "Call API" tab "IP addresses"
Login or password is wrong -32001 auth_error Incorrect login or password
Your account has been disabled, contact the support service -32009 account_inactive Account blocked.
In case an error occurs, you should enquire with technical support, and transmit a request that caused error, as well as the time of the request.
Call session not found -32602 call_session_not_found Session ID not found
Internal error, contact the support service -32603 internal_error
In case an error occurs, you should enquire with technical support, and transmit a request that caused error, as well as the time of the request.
Data supplied is of wrong type -32602 data_type_error For example, if we are waiting string but receiving int
The method does not exist / is not available -32601 method_not_found Called method is not included in the specification (refer to List of methods)
Permission denied -32003 forbidden No access rights or access to method or API, or any action is forbidden
Invalid JSON was received by the server. -32700 parse_error Invalid JSON
Batch operations not supported -32099 batch_opreations_not_supported Batch operations are not supported (refer to JSON-RPC 2.0)
Notifications not supported -32099 notifications_not_supported Notifications are not supported (refer to JSON-RPC 2.0)
The required parameter has been missed -32602 required_parameter_missed The required parameter has been missed
Invalid parameter value -32602 invalid_parameter_value Returns in all cases when incorrect value of a parameter has been transmitted, or it doesn't comply with required format of input
Unexpected method parameter(s) -32602 unexpected_parameters If parameters that are not mentioned in JSON method structure have been given in params