Skip to content

Call API

Getting started

Introduction

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.

Method list

Name Description
Authentication
login.user Authentication: login
logout.user Authentication: logout
Group of methods for call making
start.employee_call Call to an employee. Makes a direct call from a subscriber to an employee and does not apply any scenario
start.scenario_call This method makes calls as according to a customized scenario. To use the method you only need a virtual number and N scenarios
start.vnumber_call Call to a virtual number
start.informer_call Data calls that allow you to play media files for your subscribers or transmit text messeges. As your messege has been transmitted, such call is completed automatically
start.simple_call Calls to any number except own virtual numbers
Group of methods for call management
make.call Make calls for transfer or consulting
transfer.talk This method allows transferring calls to another employee or an external number (refer to section "Call status diagram")
restore.talk This method allows you to restore a call after a subscriber consulted another employee (refer to section "Call status diagram")
hold.call Holding call
unhold.call Unholding call
add.coach Adding a coach to a conversation
tag.call Tagging an active call
record.call Managing call recordings
You can not disable recording of calls set in your client area
disconnect.leg This method allows you to disconnect certain participants of a call. You can get unique ID of each participant by using "list.calls" method or notification server
send.dtmf Sending DTMF by an employee. This method is used when a subscriber has IVR and it requires for you to choose a menu item
block.contact Blocking a subscriber during call
list.calls Getting a list of active calls and their participants
list.talk_options Getting a list of talk options set in a client area of a virtual PBX
call.talk_option Call talk options set in a client area of a virtual PBX
release.call Releasing call

Agreements

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).

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, release.call Basic set for Call API
Call API Call management hold.call, unhold.call, make.call, disconnect.leg, tag.call, record.call, add.coach, list.calls, send.dtmf, block.contact, restore.talk, transfer.talk, 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:

https://callapi.callgear.com/<version>

where

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

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:

https://callapi.callgear.com/v4.0 \b https://callapi.callgear.com/v4.0

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"
  }
}

General

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

Authentication

Login

Method login.user
API version v4.0
Go back to the methods list

Request parameters

Title Type Required Description
login string yes User login
password string yes User password

Reply parameters

Title Type Required Description
access_token string yes Authentication session key
expire_at number yes Timestamp when a distributed token becomes invalid

Lifespan of a distributed authentication session key after calling the login.user method is 1 hour. Upon the expiry of a session key you need to request it again, calling the login.user method.

To make a request to API you can use a permanent authentication key which is accessible in your client area (refer to Access by key).

Example of a request

{
  "jsonrpc": "2.0",
  "id": "req1",
  "method": "login.user",
  "params": {
    "login": "your_login",
    "password": "your_password"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
      "expire_at": 1475853742
    }
  }
}

Logout

Method logout.user
API version v4.0
Go back to methods list

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key

Example of a request

{
  "jsonrpc": "2.0",
  "id": "req1",
  "method": "logout.user",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": true
    }
  }
}

Group of methods to make calls

Employee call

Method start.employee_call
API version v4.0
Description The method implements a direct call to an employee and does not use any scenario.
Go back to methods list

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
first_call string yes contact, employee

Specifies a number, that should be dialed in the first place:

  • employee - employee;
  • contact - called side (usually a client);
switch_at_once boolean no true, false

Default value false.

If the parameter first_call has value employee, and parameters employee_message and contact_message are given:

  • First call is assigned to an employee mentioned in the employee parameter;
  • After an employee takes a call he or she listens to the message till the end. Only after that a call to an employee mentioned in a contact parameter is made;
  • While dialing a contact, an employee listens to the message specified in the media_file_id parameter;
  • After a subscriber specified in the contact parameter answers, a conversation with an employee begins, if the switch_at_once parameter has value true;
  • After a contact answers, he or she listens to the message till the end, if the switch_at_once parameter has value false. Than a conversation with an employee begins.

If the parameter first_call has value contact, and the parameters contact_message and employee_message are given:

  • In the first place, a call to a subscriber specified in the contact parameter is made;
  • The contact subscriber answers the call and starts listening to the message. At the same time a call to an employee is made);
  • When the employee takes call, the message stops for the contact. Coversation begins if the switch_at_once parameter has value true;
  • When the employee takes call, the message will be played till the end. Than a conversation starts if the parameter switch_at_once has value false;
  • If one of the call's participants finishes listening to the message earlier than the other, he or she starts listening to a message from the media_file_id.

If the parameter contact_message type has value tts, the parameter switch_at_once=true doesn't work
early_switching boolean no true, false

Default value is false.

If a parameter has value true, an employee, dialing a subscriber, hears what's going on the subscriber's line.

For example, an operator is trying to reach a subscriber, but the subscriber is unavailable, and the operator reaches his or hers voicemail. By activating the parameter early_switching = true, the operator gets to hear a message about the subscriber's voicemail. If the parameter early_switching = false, the operator gets to listen to the music from the "media_file_id" parameter

A parameter can have value true only when the parameter first_call has value employee and the parameter switch_at_once has value true. Otherwise an error "-32602 invalid_parameters_combination The combination of parameters is not permitted" occurs (refer to Errors codes).
media_file_id number no

System melody "Dialing music" (dialing_music) is a default value.

Provides ID for a dialing music media file. This can be both a system and a user media file. You can access a list of system and user files by using REST API - Receiving a list of user files, Receiving a list of system files.

Is always played for a call leg that does not have one of the parameters: contact_message or employee_message

virtual_phone_number string yes

Virtual number, rented by client. Number's format should be the same as the international standart E.164 (for example, 74993720692). Is always used as a caller's number when dialing a number from the contact parameter. Is used as a caller's number when dialing a number from the employee parameter, if the show_virtual_phone_number parameter has value true. Virtual numbers are accessible via REST API method - Receiving a list of virtual number.

show_virtual_phone_number boolean no true, false

Default value is true.

Shows an employee a virtual number from the virtual_phone_number parameter as a calling subscriber's number.

contact string yes

A number of a subscriber that is being dialed. The number should follow the international standart E.164 (for example, 79091234567). As a number an employee's SIP can be used.

Extension numbers of employees are not supported.
external_id string no Unique ID, that can be used to connect an event of a call with an outside system.
dtmf_string string no 0-9, *, # Assigns DTMF, that will be sent to a contact. You can specify timeout for when the DTMF symbol is going to be sent by using a symbol . = '1 second'. Example: .12.1..4, i.e. the number 12 will be sent in 1 second, a number 1 will be sent in another second, and than a number 4 will be sent in 2 seconds.
direction string no in, out Default value is in.
Defines call direction in - Incoming call, out - Outgoing call.
An employee to take a call from a contact
employee object yes An employee that will take a call from contact.
id number yes A unique ID of an employee. You can get an ID from REST API - Receiving employee information
If the parameter phone_number is not specified, all the employee's active phone numbers will be consecutively dialed.
phone_number string no

Provides a number an employee that will take a call from a contact. A SIP-number, an extension number or a number in the E.164 format can be used. The number should be Active in a client area and should be appointed to an employee, specified in the id parameter.

A message that a contact listens to
contact_message object no

Defines parameters of a message to play to a subscriber from the contact parameter.

After the message is played, a media_file_id will be played continually
type string yes media, tts

Defines a type of a message. media is a media file, and tts is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, a file ID is used as a value. The media file may be user or system. You can access a media file's ID via REST API - Receiving user files list, Receiving system files list.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message is defined by your service plan or a limit.
A message employee listens to
employee_message object no

Defines parameters of a message an employee listens to.

After the message is played, a media_file_id will be played continually
type string yes media, tts

Defines a type of a message. media file or tts - a text for text for voice synthesis service Text-to-Speech.

value string yes

If the type is media, the file's ID is used as value. This can be a system or a user file. You can access the file's ID using REST API - Receiving user files list, Receiving system files list.

If the field type has tts in it, text for voice synthesis is used as value..

Length of a TTS message is defined by your service plan or a limit.

Example of a reply

Title Type Required Description
call_session_id number yes Unique call session ID

Example of a request

{
  "jsonrpc": "2.0",
  "method": "start.employee_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "first_call": "employee",
    "switch_at_once": true,
    "media_file_id": 2701,
    "show_virtual_phone_number": false,
    "virtual_phone_number": "74993720692",
    "external_id": "334otr01",
    "dtmf_string": ".1.2.3",
    "direction": "in",
    "contact": "79260000000",
    "employee": {
      "id": 25,
      "phone_number": "79260000001"
    },
    "contact_message": {
      "type": "tts",
      "value": "Hello"
    },
    "employee_message": {
      "type": "media",
      "value": "2561"
    }
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "call_session_id": 237859081
    }
  }
}

List of returning errors

Text of error Error code Mnemonics Description
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded Length of your message exceeded limits of your service plan
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found Virtual number is not attributed to client
Employee with id {employee_id} not found. It is not your employee. -32602 employee_not_found
The phone number does not exist or inactive -32602 no_active_phone_number Employee does not have active phone numbers in the employee settings
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Calls to own virtual numbers are not allowed
The contact {contact} has been found in the blacklist -32002 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

Refer to List of errors common for all methods

Scenario call

Method start.scenario_call
API version v4.0
Description 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.
Go back to list of methods

Parameters of request

Title Type Required Valid value Description
access_token string yes Authentication session key
virtual_phone_number string yes

Virtual number, rented by client. Format of the number should comply with the international standart E.164 (for example, 74993720692). Is always used as a caller's number when dialing the number of a contact. Is used as a caller's number when calling an employee if scenario implies setting "Show during call" with value "Number of service" in operation "Call Forwarding". You can access virtual numbers using REST API method - Receiving a list of virtual numbers.

external_id string no Unique ID, that can be used to connect call action with an outside system.
dtmf_string string no 0-9, *, # Sets DTMF, that will be sent to a subscriber from the contact parameter. You can set a timeout for when to dispatch DTMF using symbol . = '1 second'. For example: .12.1..4, i.e. in 1 second the figure 12 will be sent, in another second the figure 1 will be sent, and than in 2 seconds the figure 4 will be sent.
contact string yes

A number that is used to reach a subscriber. Its format should comply with international standart E.164 (for example, 79091234567). You can also use SIP number as an emploee's number.

If the parameter contact_message is not given, a subscriber will listen to a system melody - Dialing music (dialing_music)
Employees' extension numbers are not supported.
first_call string yes contact, employee

Defines number, that should be reached in the first place:

  • employee - employee;
  • contact - called side (usually client);
switch_at_once boolean no true, false

Default value is false.

If the first_call parameter has value employee, a message is specified for an employee in the scenario, and the parameter contact_message is given:

  • The first call reaches an employee from the scenario;
  • After the employee takes call he listents to the message till the end, and after that dials a contact;
  • While dialing the contact, the employee listens to a system melody - Dialing music (dialing_music);
  • After the contact answers the call, a conversation with the employee starts if the parameter switch_at_once has value true;
  • After a contact answers the call, he or she will listen the message till the end if the parameter switch_at_once has value false. After that a conversation begins.

If the parameter first_call has value contact, the parameter contact_message and a message for an employee are given in the scenario:

  • A call to a contact should be made in the first place);
  • After the contact takes call, he or she starts listening to the message. At the same time a call to an employee from the scenario is being made;
  • After the employee takes call the message will be interrupted for the contact. Than a conversation begins if the parameter switch_at_once has value true;
  • After the employee takes call, both the employee and the subscriber will listen to the message till the end, after that a conversation begins if the parameter switch_at_once has value false;
  • If one of the call's participants finishes lestening to the message earlier than the other one, he or she listens to a system melody - Dialing music (dialing_music).

If the parameter contact_message type has value tts, the parameter switch_at_once=true doesn't work
scenario_id number yes Unique scenario ID that can be accessed by using REST API - Receiving a list of scenarios.
direction string no in, out Default value is in.
Defines direction of a call: in - Incoming call, out - Outgoing call.
Message that a contact listens to.
contact_message object no

Defines parameters of the message that a contact listens to.

As the message is played, a system melody is played continually - Dialing music (dialing_music)
type string yes media, tts

Defines a type of a message. media - meida file or tts - text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, an ID of the file to be played is used as value. The file may be both a system or a user file. You can access the file's ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.
Message that is played for an employee
employee_message object no

Defines parameters of a message that's going to be played for an employee.

A message for an employee specified in the scenario has a higher priority than a message from the `employee_message` parameter. However both of the messages will be played in sequence.
After a message is played, the code>media_file_id message will be played continually.
type string yes media, tts

Defines the type of a message. media - media file or tts - text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, an ID of the file to be played is used as value. This file can be both a system or a user file. You can access the file's ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.

Parameters of a reply

Title Type Required Description
call_session_id number yes Unique call session ID

Example of a request

{
  "jsonrpc": "2.0",
  "method": "start.scenario_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "virtual_phone_number": "74993720692",
    "external_id": "34rty567",
    "dtmf_string": "..1.2.3",
    "contact": "79260000000",
    "first_call": "employee",
    "switch_at_once": false,
    "scenario_id": 23456,
    "direction": "in",
    "contact_message": {
      "type": "media",
      "value": "237"
    },
    "employee_message": {
      "type": "media",
      "value": "237"
    }
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "call_session_id": 234568
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded Length of your message exceeded the limit of your service plan
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found Virtual number does not belong to the client
Scenario with id {scenario_id} not found -32602 scenario_not_found
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Calls to own virtual numbers are not permitted
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

Refer to section List of errors common for all methods

Call to a virtual number

Method start.vnumber_call
API version v4.0
Description Call to a virtual number.
Go back to the list of methods

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
virtual_phone_number string yes

Virtual number, rented by client. Format should comply with the international standart E.164 (for example, 74993720692). Is always used as a caller's number when dialing a number of a contact. Is used as a caller's number when calling an employee if scenario implies setting "Show during call" with value "Number of service" in operation "Call Forwarding". You can access virtual numbers via REST API method - Receiving a list of virtual numbers

external_id string no Unique ID that can be used to connect a call action with an outside system.
dtmf_string string no 0-9, *, # Defines DTMF, that will be sent to a contact. You can specify timeout for when the DTMF symbol is going to be sent by using a symbol . = '1 second'. Example: .12.1..4, i.e. the number 12 will be sent in 1 second, a number 1 will be sent in another second, and than a number 4 will be sent in 2 seconds.
direction string no in, out Default value is in.
Defines the direction of call: in - Incoming call, out - Outgoing call.
contact string yes

The number of a subscriber you're reaching for. The format should comply with the international standart E.164 (for example, 79091234567). You can also use SIP number of an employee.

If the parameter contact_message is not given, a subscriber will listen to a system melody - Dialing Music (dialing_music)
Extension numbers of the employees are not supported.
first_call string yes contact, employee

Defines number that should be dialed in the first place:

  • employee - employee;
  • contact - called side (usually a client);
switch_at_once boolean no true, false

Default value is false.

If the parameter first_call has value employee, a message for an employee from the scenario and the contact_message parameter are given:

  • First call reaches an employee from the scenario;
  • After the employee takes call, he or she listens to the message till the end, and only after that a call to the contact is made;
  • While dialing the contact, the employee listens to a system melody - Dialing Music (dialing_music);
  • As the contact replies, a conversation with the employee happens, if the parameter switch_at_once has value true;
  • After the contact replies, he or she listens to the message till the end if the parameter switch_at_once has value false. Than a conversation with the employee begins.

If the parameter first_call has value contact, the parameter contact_message is given, and a message to the employee is given in the scenario:

  • A call to a contact should be made in the first place;
  • After the contact takes call he or she listens to the message. At the same time a call to an employee from the scenario is made;
  • After the employee takes call the message will be interrupted for the contact. Than a conversation begins if the parameter switch_at_once has value true;
  • After the employee takes call, both the employee and the subscriber will listen to the message till the end, after that a conversation begins if the parameter switch_at_once has value false;
  • If one of the call's participants finishes listening to the message earlier than the other one, he or she listens to a system melody - Dialing Music (dialing_music).

If the parameter contact_message type has value tts, the parameter switch_at_once=true doesn't work
A message that is to play to a contact
contact_message object no

Defines parameters of the message, that needs to be played to a contact.

After the message is played, system melody starts playing continually - Dialing Music (dialing_music)
type string yes media, tts

Defines the type of a message. media is a media file, and tts is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, ID of the file that's to be played is used as value. The file can be both system and user. You can access an ID of the file via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.

Parameters of a reply

Title Type Required Description
call_session_id number yes Call session unique ID

Example of a request

{
  "jsonrpc": "2.0",
  "method": "start.vnumber_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "virtual_phone_number": "74993720692",
    "external_id": "34rty567",
    "dtmf_string": "..1.2.3",
    "direction": "in",
    "contact": "79260000000",
    "first_call": "employee",
    "switch_at_once": false,
    "show_virtual_phone_number": true,
    "contact_message": {
      "type": "media",
      "value": "237"
    }
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "call_session_id": 123467589
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded The length of your message exceeded the limits of your service plan
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found Virtual number doesn't belong to a client
Virtual phone number does not have a scenario -32007 scenario_not_found
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Calls to own virtual numbers are not allowed
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

Refer to List of errors common for all methods

Informer call

Method start.informer_call
API version v4.0
Description 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.
Go back to list of methods

After the message is played to a subscriber, the call ends.

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
virtual_phone_number string yes

Virtual number, rented by client. Format should comply with the international standart E.164 (for example, 74993720692). Is always used as a caller's number when dialing a number of a contact. You can access virtual numbers via REST API method - Receiving a list of virtual numbers.

external_id string no Unique ID, that can be used to connect an event of a call with an outside system.
dtmf_string string no 0-9, *, # Assigns DTMF, that will be sent to a contact. You can specify timeout for when the DTMF symbol is going to be sent by using a symbol . = '1 second'. Example: .12.1..4, i.e. the number 12 will be sent in 1 second, a number 1 will be sent in another second, and than a number 4 will be sent in 2 seconds.
direction string no in, out Default value is in.
Defines the direction of a call: in - Incoming call, out - Outgoing call.
contact string yes

Number of a subscriber you're reaching for. Format should comply with the international standart E.164 (for example, 79091234567). You can also use SIP number of an employee.

Extension numbers of employees are not supported.
dialing_timeout number no up to 120 seconds Default value is 30. Waiting time to receive a reply from a contact. If there is no reply, the call ends. Waiting time in in seconds.
A message to be played for a contact
contact_message object yes

Defines parameters of a message that's to be played for a contact.

type string yes media, tts

Defines type of a message: media is a media file or tts is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.

Parameters of a reply

Title Type Required Description
call_session_id number yes Call session unique ID

Example of a request

{
  "jsonrpc": "2.0",
  "method": "start.informer_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "virtual_phone_number": "74993720692",
    "external_id": "34rty567",
    "dtmf_string": "..1.2.3",
    "direction": "in",
    "dialing_timeout": 25,
    "contact": "79260000000",
    "contact_message": {
      "type": "tts",
      "value": "Test message"
    }
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "call_session_id": 1238694
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded The length of your message exceeded the limits of your service plan
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found Virtual number does not belong to a client
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Calls to own virtual numbers are not allowed
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

Refer to List of errors common for all methods

Simple call

Method start.simple_call
API version v4.0
Description Call to any number except own virtual numbers. This is not a call from an employee to any number.
Go back to the list of methods

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
first_call string yes contact, operator

Defines a number that should be dialed in the first place:

  • operator - an operator, who will be able to manage calls via conversation options;
  • contact - called side (usually client);
switch_at_once boolean no true, false

Default value is false.

If the parameter first_call has value operator and the parameter operator_message is given, an operator takes call. He or she listens to the message till the end, and than calls a contact. If the parameter switch_at_once has value true and the parameter contact_message is given, the message will be interrupted for the leg contact.

While reaching for a contact, an operator listens to the message from the parameter media_file_id. Consequently if the parameter switch_at_once has value false, and the parameter contact_message is given, the message will be played till the end for the leg contact. If the parameter first_call has value contact, and the parameter contact_message is given, a client takes call. Than he or she listens to the message, and at the same time a call to an operator is made. If the parameter switch_at_once has value true and the parameter operator_message is given, after an operator takes call, messages will be interrupted for both the contact and the operator. Consequently, if the parameter switch_at_once has value false, the message will be played till the end for the legs contact and operator. If one of the legs finishes lisneting to the message earlier than the other one, he or she listens to the promt, given in the parameter media_file_id.
early_switching boolean no true, false

Default value is false.

If the parameter has value true, an employee, dialing a subscriber, will hear what's happening on the line.

For example, an oreator is trying to reach a subscriber, the subscriber is unavailable, and the operator reaches his or hers voicemail. Activating the parameter early_switching = true, the operator will be able to hear a message from the subscriber's voicemail. If the parameter early_switching = false, the operator will listen to the music given in the parameter "media_file_id"

The parameter can have value true only if the parameter first_call have value operator, and the parameter switch_at_once has value true. Otherwise the error "-32602 invalid_parameters_combination The combination of parameters is not permitted" occurs (refer to section Errors codes).
media_file_id number no

Default value is a system melody "Dialing Music" (dialing_music).

Defines ID of a media file with Dialing Music. The file can be system or user. You can access list of system and user files via REST API - Receiving a list of user files, Receiving a list of system files.

Is always played for the leg that doesn't have one of the parameters: contact_message or operator_message

virtual_phone_number string yes

Virtual number, rented by client. Format of the number should comply with the international standart E.164 (for example, 74993720692). Is always used as a caller's number when dialing a number of a contact. Can be used as a caller's number when dialing a number of an operator if the parameter show_virtual_phone_number has value true. You can access virtual numbers via REST API method - Receiving a list of virtual numbers.

show_virtual_phone_number boolean no true, false

Default value is true.

Defines whether a virtual number from the parameter virtual_phone_number will be shown to an operator as a caller's number or not.

contact string yes

Number of a subscriber you're reaching for. Format should comply with the international standart E.164 (for example, 79091234567). You can also use SIP number of an employee.

Extension numbers of employees are not supported.
external_id string no Unique ID, that can be used to connect an event of a call with an outside system.
dtmf_string string no 0-9, *, # Assigns DTMF, that will be sent to a contact. You can specify timeout for when the DTMF symbol is going to be sent by using a symbol . = '1 second'. Example: .12.1..4, i.e. the number 12 will be sent in 1 second, a number 1 will be sent in another second, and than a number 4 will be sent in 2 seconds.
direction string no in, out Default value is in.
Defines the direction of call in - Incoming call, out - Outgoing call.
An operator that's going to talk to a contact
operator string yes Number of an operator that's going to talk to a contact. The operator can manage the call - conversation options. Format should comply with the international standart E.164 (for example, “79091234567”).
Is not considered as employee. Is not featured as an employee in reports.
operator_confirmation string no 0-9, *, #, any Receiving a confirmation from an operator that he or she is ready to take call. When using value "any", you can send the conversation by pushing any of the buttons.
contact_message object no

Defines parameters of the message that's to be played for a contact.

After the message is played, a message from the parameter media_file_id is played continually.
type string yes media, tts

Defines type of a message: media is a media file or tts - is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.
Message to be played for an operator
operator_message object no

Defines parameters of a message that's to be played for an operator.

After the message is played, a message from the parameter media_file_id is played continually.
type string yes media, tts

Defines type of a message: media is a media file or tts - is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.

Parameters of a reply

Title Type Required Description
call_session_id number yes Call session unique ID

Example of a request

{
  "jsonrpc": "2.0",
  "method": "start.simple_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "first_call": "operator",
    "switch_at_once": true,
    "media_file_id": 2701,
    "show_virtual_phone_number": false,
    "virtual_phone_number": "74993720692",
    "external_id": "334otr01",
    "dtmf_string": ".1.2.3",
    "direction": "in",
    "contact": "79260000000",
    "operator":"79262444491",
    "contact_message": {
      "type": "tts",
      "value": "Hello"
    },
    "operator_message": {
      "type": "media",
      "value": "2561"
    }
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "call_session_id": 237859081
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics Description
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded Length of your message exceeded the limits of your service plan
The media file with id {media_file_id} not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found Virtual number does not belong to a client
Parameter contact can not contain own virtual phone number -32602 own_virtual_phone_number_not_allowed Calls to own virtual numbers are not allowed
The contact {contact} has been found in the blacklist -32002 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

Refer to List or errors common for all methods

Group of methods for call management

Make call for transfer or consulting

Method make.call
API version v4.0
Description Make call for transfer or consulting
Go back to List of methods

The method can only be used after a "hold.call" call. Refer to the "Diagram of call statuses" section.

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, using a notification server or REST API.
to string yes

Number od a subscriber you're reaching for. Format should comply with the international standart E.164

. It can be an extension number, an external number, a number of an employee or a sip number
A message that's to be played for a subscriber from the parameter to
to_message object no

Defines parameters of a message, that's to be played for a subscriber from the parameter to_message.

A subscriber on hold will listen to the message till the end while waiting for reply.
type string yes media, tts

Defines type of a message: media is a media file or tts - is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "make.call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 2354891,
    "to": "79260000000"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
This method can not be called in this state -32004 invalid_state Method can be called only after the hold.call method
The character encoding must be UTF-8 -32602 character_encoding_not_allowed
The phone number does not exist or inactive -32602 no_active_phone_number Employee may not have active numbers

Refer to List of errors common for all methods

Transferring calls

Method transfer.talk
API version v4.0
Description Method allows transferring calls to another employee or to an external number (Refer to "Diagram of call statuses")
Go back to list of methods

Method can only be used after the "make.call" call. Refer to "Diagram of call statuses"

Parameters of a request

Name Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "transfer.talk",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 2786459
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
This method can not be called in this state -32004 invalid_state Method can be called only after the make.call method in condition dialing or operator_talk (refer to Diagram of call statuses)

Refer to List of errors common for all methods

Restoring talk

Method restore.talk
API version v4.0
Description This method allows you to restore a conversation after a subscriber consulted another employee (refer to section "Diagram of call statuses")
Go back to List of methods

Method can be used only after the "make.call" call. Refer to "Diagram of call statuses"

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.

Parameters of a request

{
  "jsonrpc": "2.0",
  "method": "restore.talk",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 25374860
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
This method can not be called in this state -32004 invalid_state Method can be called only after the make.call method in condition dialing or operator_talk (Refer to Diagram of call statuses)

Refer to List of errors common for all methods

Holding call

Method hold.call
API version v4.0
Description Holding call
Go back to list of methods

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
call_session_id number yes nique ID of a call session, that you can get in a reply message after calling the methods start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
Playing a message for a calling subscriber
contact_message object yes Defines parameters of a message that should be played to a calling subscriber. A calling subscriber is a number from the contact parameter in the methods: start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call or subscriber calling a virtual PBX.
type string yes media, tts

Defines type of a message: media is a media file or tts - is a text for voice synthesis service Text-to-Speech.

value string yes

If the field type has media in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID via REST API - Receiving a list of user files, Receiving a list of system files.

If the field type has tts in it, text for voice synthesis is used as value.

Length of a TTS message depends on your service plan or a limit.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "hold.call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 23465781,
    "contact_message": {
      "type": "media",
      "value": "2034"
    }
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
This method can not be called in this state -32004 invalid_state Method can be called only in condition Talk (refer to Diagram of call statuses)
The media file with id {media_file_id} not found -32602 media_file_not_found
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded Length of your message exceeded the limits of your service plan
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

Refer to list of errors common for all methods

Unholding call

Method unhold.call
API version v4.0
Description Unholding call
Go back to List of methods

Method can only be used after calling "hold.call". Refer to "Diagram of call statuses"

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "unhold.call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 2846590
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
This method can not be called in this state -32004 invalid_state Method can be called only in condition hold (Refer to Diagram of call statuses)

Refer to List of errors common for all methods

Tagging call

Method tag.call
API version v4.0
Description Tagging an active call
Go back to List of methods

You can only tag an active call. You can tag inactive calls via REST API method - Tagging a request

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
tag_id number yes Tag unique ID that you can access via REST API method - Receiving a list of tags

Example of a request

{
  "jsonrpc": "2.0",
  "method": "tag.call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 2846590,
    "tag_id": 36
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics or error Description
Tag with {tag_id} not found -32602 tag_not_found
Duplicate tag -32602 duplicate_tag

Refer to List of errors common for all methods

Disconnecting a leg of a call

Method disconnect.leg
API version v4.0
Description 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
Go back to List of methods

Disconnecting a contact (refer to the methods start.employee_call, start.scenario_call, start.informer_call, start.vnumber_call) leads to ending the whole call session

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
leg_id number yes Unique ID of a call's leg that you can access via a notification server.

Parameters of a request

{
  "jsonrpc": "2.0",
  "method": "disconnect.leg",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 2875654,
    "leg_id": 9875
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
The call's leg not found -32602 leg_not_found

Refer to List of errors common for all methods

Adding a coach to a call

Method add.coach
API version v4.0
Description Adding a coach to a call
Go back to List of methods

Method allows to add a coach mentioned in your client area or in the parameter phone_number to a conversation

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
phone_number string no Number of a coach, if he or she is not mentioned in your client area.
If a number of a coach is given, a coach from your client area's settings is added.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "add.coach",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 27934036,
    "phone_number": "79260000000"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
The coach not found in your settings -32602 coach_not_found
The phone number does not exist or inactive -32602 no_active_phone_number

Refer to List of errors common for all methods

Managing call recording

Method record.call
API version v4.0
Description Managing call recording. You can not switch off the recording of a call set via your client area.
Go back to list of methods

Method allows you to manage recording of an active call. You can not switch off universal recording of calls.

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
action string yes on, off Operation on a call recording. on - switching on the recording, off - switching off the recording

Example of a request

{
  "jsonrpc": "2.0",
  "method": "record.call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 235496,
    "action": "on"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
Permission denied -32003 forbidden You can not switch off universal recording of call. Universal recording of call is an employee level setting.
The call record is already started -32602 record_already_started Recording already started
The call record is not enabled -32602 record_already_stopped Recording has not been started

Refer to List of errors common for all methods

Block a contact

Method block.contact
API version v4.0
Description Block a contact during call
Go back to list of methods

Parameters of a request

Name Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "block.contact",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 27485639
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
The contact with phone number {contact_phone_number} already exists -32602 duplicate_contact

Refer to List or errors common for all methods

Using talk options

You can manage talk options in your client area "Virtual PBX" -> "Talk options". Recall of certain talk options disables them. For example, Voice recorder, Call coach (refer to list.talk_options)

Method call.talk_option
API version v4.0
Description Calling talk option set in the client area of your virtual PBX
Go back to List of methods

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
button string yes Button, calling talk option.
Buttons and actions are set in your client area.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "call.talk_option",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 246578,
    "button": "1"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

List of returning errors

Text of error Code of error Mnemonics of error Description
This method can not be called in this state -32004 invalid_state
Internal error, contact the support service -32603 internal_error
Permission denied -32003 forbidden You can not switch off universal recording of calls at the level of employee settings
Call session not found -32602 call_session_not_found
Talk option not found -32602 talk_option_not_found Button is not set

Refer to List of errors common for all methods

Sending DTMF by an employee

Method send.dtmf
API version v4.0
Description Sending DTMF by an employee. The method is used when client side has IVR and it requires for you to choose a menu option.
Go back to List of methods

Parameters of a request

Title Type Required Valid value Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
dtmf_string string yes 0-9, *, # Defines DTMF, that will be sent to a contact. In case of an outgoing call from a virtual PBX to a subscriber,
Sending DTMF is possible only via single symbols.
You can also call preset talk options. For incoming calls, talk options become available 30 seconds after the call.

Example of a request

{
  "jsonrpc": "2.0",
  "method": "send.dtmf",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 27934036,
    "dtmf_string": "1"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

Receiving talk options list

Method list.talk_options
API version v4.0
Description Receiving a list of talk options set in the client area of your virtual PBX
Go back to list of methods

You can set talk options in your client area "Virtual PBX" -> "Talk options".

Parameters of a request

Title Type Required Description
access_token string yes Authentication session key

Parameters of a reply

Title Type Required Description
button string yes Button that is used to call talk options
mnemonic string yes Mnemonic name of a talk option Possible values:
  • finish_conversation - Finish conversation
  • tag_call - Tag call
  • record_talk - Voice recorder (recording calls)
  • transfer_call - Transfer
  • run_scenario - Run scenario
  • call_coach - Call coach
  • receive_fax - Receive fax
  • save_numa - Save AON to a group
name string yes Name of talk option
Option value
button_value object no Some options may contain names of tags, scenarios, etc. This object contains additional information on talk option
id number yes Unique ID of an object that is activated when calling a talk option. For example, ID of a scenario
value string yes Name of an object, that is activated when calling a talk option. For example, name of a scenario

Example of a request

{
  "jsonrpc": "2.0",
  "method": "list.talk_options",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d"
  }
}

Example of a reply

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": [
      {
        "button": "1",
        "mnemonic": "tag_call",
        "name": "Tag",
        "button_value": {
          "id": 254,
          "value": "Relevant"
        }
      }
    ]
  }
}

Receiving a list of active calls

Method list.calls
API version v4.0
Description Receiving a list of active calls and their participants
Go back to list of methods
Parameters of a request
Title Type Required Valid value Description
access_token string yes Authentication session key
direction string no in, out Defines what sessions should be shown - incoming, outgoing. If the parameter is not given, all the sessions are shown.
virtual_phone_number string no Defines active calls from what virtual number to show.
Number should begin with a 7
Parameters of a reply
Title Type Required Valid value Description
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
direction string yes in, out Direction of call session
start_time string yes Call start time. Format YYYY-MM-DD hh:mm:ss
virtual_phone_number string yes Virtual number, that was used as a representative's number.
contact_phone_number string yes Number of a subscriber
external_id string yes Unique ID of a request in an outside system of a client
List of tags
tags array yes List of tags
tag_id number yes Unique tag ID
tag_name string yes Tag name
Call session legs
legs array yes List of call session legs
leg_id number yes Unique ID of a leg
calling_phone_number string yes Number of a calling subscriber
called_phone_number string yes Number of a called subscriber
is_operator boolean yes true, false Indentifies a leg that can manage talk options.
employee_id number yes Unique ID of an employee
employee_full_name string yes Name of an employee
record_call_enabled boolean yes true, false

Call recording switched on/switched off.
true - switched on, false - switched off

state string yes

Status of a call leg

Possible values:
  • Redial
  • Conversation
  • Next in line
  • Disconnect
  • Operators' conversation
  • On hold
  • Transferring call
  • Sending dtmf
  • Receiving fax
  • Fax received
  • Sending fax
  • Fax sent
Example of a request
{
  "jsonrpc": "2.0",
  "method": "list.calls",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "direction": "in",
    "virtual_phone_number": "74951045771"
  }
}
Example of a reply
{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": [
      {
        "call_session_id": 206597836,
        "direction": "in",
        "start_time": "2016-10-19T12:26:48.418",
        "virtual_phone_number": "74951045771",
        "contact_phone_number": "74959268686",
        "external_id": null,
        "tags": [
          {
            "tag_id": 456,
            "tag_name": "Relevant"
          }
        ],
        "legs": [
          {
            "leg_id": 287866245,
            "calling_phone_number": "74951045771",
            "called_phone_number": "74959268686...9.2.3.3",
            "is_operator": false,
            "employee_id": null,
            "employee_full_name": null,
            "record_call_enabled": true,
            "state": "Talk"
          },
          {
            "leg_id": 287866221,
            "calling_phone_number": "74959268686",
            "called_phone_number": "79262444393",
            "is_operator": true,
            "employee_id": 2345,
            "employee_full_name": "Test",
            "record_call_enabled": true,
            "state": "Talk"
          }
        ]
      }
    ]
  }
}

Releasing call session

Method release.call
API version v4.0
Description Releasing a call
Go back to List of method
Parameters of a request
Title Type Required Description
access_token string yes Authentication session key
call_session_id number yes Unique ID of a call session, that you can get in a reply message after calling the methods start.informer_call, start.vnumber_call, start.scenario_call, start.employee_call, via a notification server or REST API.
Example of a request
{
  "jsonrpc": "2.0",
  "method": "release.call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "call_session_id": 28575639
  }
}
Example of a reply
{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "success": "true"
    }
  }
}

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