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.

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.

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

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

Group of methods to make calls

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

Group of methods for call management

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

Error messages

Title			Type	Required	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`