Call API

Getting started

Introduction

The current document describes the Call API, which allows you to make and manage calls.

You can also manage calls received through the virtual PBX. To do this, you need a unique ID for your call session, which you can obtain from the REST API notification server.

The API is based on the JSON-RPC 2.0 specification and does not support batch operations.

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

The Content-Type header must be application/json; charset=UTF-8.
The Content-Length header must specify the correct message length, as required by the HTTP/1.1 specification.

Conventions

The following conventions are used:

Empty fields are always returned with a null value. For an array, an empty array is returned; for an object, an empty object is returned.
All fields related to time and date are transferred according to ISO 8601, in the following format: YYYY-MM-DDThh:mm:ssZ.
Requests to the API are always made using the POST method.
All keys in requests/responses, in the JSON data structure, and in method names use snake_case style - with words separated by underscores.
Data is returned only in JSON format, according to the RFC 7159 specification.
Data encoding: UTF-8.

Authorizing IP address

By default, access to the API is denied for everyone. To enable requests, you need to add the host IP address used to make a request to the whitelist. This can be done in your client area "Administrator" -> "Account" -> "Security", tab "API".

Call API users

You can choose a set of authorization rules in the form of a checkbox Access to Call API. Go to your client area "Administrator" -> "User management" -> click the User you want to grant Call API access to and enable the Call API Basic set component.

This can only be done by the administrator.

Authentication by login and password. The reply contains a key to access the Call API.

The 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 the "Access by key" box. Be careful: you can see and copy the key only at the moment it is generated. After you have saved the settings, the key is only available in the application's code or another place where you store it.

Depending on your settings, keys can be temporary or permanent.

Statistics and reports

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

If a JSON or request-structure error is returned - the mnemonic parse_error or invalid_request.
If an error caused by a call to a non-existent method is returned - the mnemonic method_not_found.
If an authentication error is returned - access_token_blocked, access_token_invalid, access_token_expired, auth_error.
If an error caused by a request from a non-authorized IP is returned - the mnemonic ip_not_whitelisted.

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

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

Managing security settings for calls

You can manage security settings for your calls (mobile, national, international) in your client area "Account" -> "Security", tab "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

Client-facing name	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. Once 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, the JSON format is used. The Accept header is ignored.

Base URL to access the API

The base URI to access the API:

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

where

<version> is the API version (refer to Versions).

Versions

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

Versions should be written 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 the API, the current_version_deprecated parameter with the value true will be returned in the meta parameters (refer to Meta parameters). This means that within the next couple of months the old version may become unavailable.

Example:

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

The maximum number of supported versions is 2.

The support period for old versions is 2 months.

Limits and restrictions

Limits are based on a points system; that is, each method has a value measured in points.

Points are deducted only for a successful request; that is, the request is marked as successful in a request report. A request is considered successful if the result is returned with the status success = true or with a call session ID.

Limits are tied to the Call API Basic set component (refer to Components) and are applied depending on a method's point value.

Data about limits is returned in every reply in the meta parameters (refer to Meta parameters), except when limits are not applied:

If JSON or request-structure errors are returned - the mnemonic parse_error or invalid_request.

If an error caused by a call to a non-existent method is returned - the mnemonic method_not_found.

If an authentication error is returned - access_token_blocked, access_token_invalid, access_token_expired, auth_error.

If an error caused by a request from a non-authorized IP is returned - the mnemonic ip_not_whitelisted.

Data about limits is returned in the meta parameters (refer to Meta parameters).

Expanding limits

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

Limit names:

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 are returned in response to a method call. They appear both in a successful response and in a response with an error.

The api_version parameter is returned only for versions that are deprecated.

Description of parameters:

Parameter name	Description
`day_limit`	Current limit - points per day
`day_remaining`	Points left until the daily limit
`day_reset`	Seconds until the daily limit is reset
`minute_limit`	Current limit - points per minute
`minute_remaining`	Points left until the minute limit
`minute_reset`	Seconds until the minute limit is reset
`current_version_deprecated`	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_deprecated": "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		Unique ID of the request to the API. Is not communicated in notifications. It appears only in the `Request ID` parameter of Statistics and reports.
method	string	yes		The method being called (refer to the Methods list)
jsonrpc	string	yes	2.0	JSON-RPC specification number
params	object	yes		Contains the body of the request to the API. The body changes depending on the method.

Call state diagram

Authentication

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 call flow (scenario).
"start.scenario_call"	The method allows you to make calls according to a customized scenario. To use the method, you only need a virtual phone number and a 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 your own virtual numbers. This is not a call from an employee to any number.

Group of methods for call management

Method	Description
"make.call"	Make a call for transfer or consulting.
"transfer.talk"	The method allows transferring calls to another employee or to an external number (refer to "Call state diagram").
"restore.talk"	This method allows you to restore a conversation after a subscriber consulted another employee (refer to the "Call state diagram" section).
"hold.call"	Holding a call.
"unhold.call"	Unholding a call.
"tag.call"	Tagging an active call.
"disconnect.leg"	The method allows you to disconnect various legs of a call. You can access the ID for each leg via the list.calls method or a notification server.
"add.coach"	Adding a coach to a call.
"record.call"	Managing call recording. You cannot switch off the recording of a call set via your client area.
"block.contact"	Block a contact during a call.
"call.talk_option"	Calling a talk option set in the client area of your virtual PBX.
"send.dtmf"	Sending DTMF by an employee. The method is used when the client side has an IVR and it requires 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.
"release.call"	Releasing a call.

Error messages

Parameter			Type	Required	Description
error			object	yes	Object with error contents
	code		number	Yes	Code of the error (refer to Groups 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 are also errors specific to certain methods)
		field	string	no	Name of the parameter associated with the error. Nested parameters are separated 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 parameter substitutions for a template with error text. That is, it contains values that can change dynamically, such as limits or TTS message length. The value from this parameter can be used in error messages in the interface built on top of Call API (operator's workspace).
		extended_helper	string	no	Link to a page with more information about the error and possible solutions

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 method
-32603	Internal errors of the JSON-RPC server. If an error occurs, you need to contact technical support and provide the request that caused the 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 the given direction (refer to Security rules) and blacklist.
-32003	Errors with access rights - IP address is not in the whitelist, a user does not have access rights
-32004	Errors related to the wrong order of called methods
-32007	Errors related to the virtual number
-32008	Errors related to components
-32009	Errors related to an account. If an error occurs, you need to contact technical support and provide the request that caused the error, as well as the time of the request.
-32029	Errors related to limits
-32099	Errors related to support for various JSON-RPC 2.0 specification features - batch 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 expired	-32001	`access_token_expired`	Applies only to a permanent token. If a token expires, the error is returned
Access token has been blocked	-32001	`access_token_blocked`	If a permanent token is blocked, the error is returned
Access token is invalid	-32001	`access_token_invalid`	The error is returned 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 the service plan are exceeded (refer to Limits and restrictions)
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. If an error occurs, you should contact technical support and provide the request that caused the 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`	If an error occurs, you should contact technical support and provide the request that caused the error, as well as the time of the request.
Data supplied is of wrong type	-32602	`data_type_error`	For example, if a `string` is expected but an `int` is received
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 the method or API, or the action, is forbidden
Invalid JSON was received by the server.	-32700	`parse_error`	Invalid JSON
Batch operations not supported	-32099	`batch_operations_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 missing	-32602	`required_parameter_missed`	The required parameter is missing
Invalid parameter value	-32602	`invalid_parameter_value`	Returns in all cases when an incorrect parameter value has been transmitted, or it does not comply with the required input format
Unexpected method parameter(s)	-32602	`unexpected_parameters`	If parameters that are not mentioned in the JSON method structure have been given in `params`