Callback (/callback/)

You can test API methods on the interactive API browser page and without writing code
Some of the resources described on the page may not be available by default due to the type of application (see Creating and authorizing applications).

The callback resource allows you to initiate a call between numbers using the API. After the successful API request, the system calls all the numbers that are the call origins and, after one of them has picked up the handset by, starts to call the destination number.  

In this resource, you may use Variables. You must set them first in the resource Variables. Then, when requesting for callback, you may use the variables instead of request parameters via:

  1. “@{VAR_NAME}” if it is the extension_id in the request URL 

  2. “$cv({VAR_NAME})” if it is an option in the request body  

The variables may be used by the client user only. See example below 

Description of Data Structures 

Name 

Type 

Mandatory 

Default Value 

Description 

Name 

Type 

Mandatory 

Default Value 

Description 

allow_public_transfer 

boolean 

no 

true 

Allows call transfer when calling an external number 

announce_sound_id 

long 

no 

 

Identifier of the sound to be played when the origin number picks up the handset before the destination number will be called 

call_duration 

long 

no 

System value 

Maximum call duration, in seconds 

caller_id_name 

string 

no 

 

Caller name. If no value is specified, the extension number name, which the call is initiated from, will be used 

caller_id_number 

string 

no 

 

Caller number. If no value is specified, the extension number, which the call is initiated from, will be used 

src_ani 

string 

no 

 

Number from the client external number list that will be transferred as a caller ID when calling an external number or numbers from the array src_num. It is not transmitted to internal numbers. If a number is specified that is not in the external customer number list (DID), the option src_ani will be ignored 

dst_ani 

string 

no 

 

Number from the client external number list that will be transferred as a caller ID when calling an external number from dst_num. It is not passed to internal numbers. If a number is specified that is not in the external customer number list (DID), the option dst_ani will be ignored 

dst_announce_sound_id 

long 

no 

 

The identifier of the sound played when the callee picks up the handset will be heard by all call participants 

dst_dtmf 

string 

no 

 

A DTMF tone sequence that will be transmitted to the number dst_num as soon as the dst_num call is answered. Allowed numbers are 0123456789*# as well as symbols W and w. W is a one second pause, w is a half second pause 

dst_num 

string 

yes 

 

Number of the call destination. Unlike src_num, all incoming call rules for the number are processed here and queues voice menu (IVR) and may be specified 

src_caller_id_name 

string 

no 

 

Caller name to be passed to numbers from the list src_num. If no value is specified, the option caller_id_name will be used. If caller_id_name is not specified, the extension number name, which the call is initiated from, will be used 

src_caller_id_number 

string 

no 

 

Caller number to be passed to numbers from the list src_num. If no value is specified, the option caller_id_number will be used. If caller_id_number is not specified, the extension number, which the call is initiated from, will be used 

src_num 

string 

yes 

 

An array of call source numbers, for example, a list of internal and/or mobile numbers. Internal numbers of "IVR" type cannot be specified here. The numbers from the array are called without regard to the rules of the incoming call

transfer_after_dst_hangup 

string 

no 

 

The number to which the system will transfer the call if the originating party src_num is the last in the conversation

transfer_after_src_hangup 

string 

no 

 

The number to which the system will transfer the call if the destination party dst_num is the last in the conversation

callback_rate_limit 

int 

no 

 

For each client, limit of call quantity is specified. If it is necessary that the callback occupies not the entire calls limit, but only % of calls from the calls limit, you must specify the callback_rate_limit from 0% to 100%. The higher the % is, the higher the probability that the callback will be declined, and for 100%, the callback will be definitely declined with an error callback_rate_limit_exceeded 

variables 

dict 

no 

 

This is per-call variables. Read more: Variables (Dynamic variables passed when initiating callback)

An example of using callback with variables

{   "dst_num": "000116644",   "src_num": [     "341"   ],   "variables": {"autoanswer": "4",    "testvar": "'testval"} }

 

wait_for_pickup 

int 

no 

Системное значение 

Maximum time out for picking-up the handset, in seconds. First, the caller numbers are waited to pick up the handset, then the callee number is waited to pick up the handset. If early-media is played for dst-num, then the wait_for_pickup timer will resume from the moment early-media is played. If during the wait_for_pickup time the handset is not picked up, the call will not be made (if options transfer_after_* are passed, it is recommended to wait for the wait_for_pickup timers expiration) 

call_api_id 

string 

yes 

 

Returns in response to a callback request. It is used for the possibility of subsequent call management 

call_id 

string 

yes 

 

Returns in response to a callback request and serves as its identifier. By it, you can filter events related to this callback and get reports based on its results. It is synonym to call_uuid for the resource call history 

Callback result 
After initiating a call, you can make a request for the resource "Call history (/call_history/, /calls/)": 
GET /client/{client_id}/call_history/{call_uuid} 
specifying the "call_id" received as a result of call initiation as "{call_uuid}" 

Example of Using Variables in Request 

Use the variables already set in the resource Variables

  • ext_id = 34535 

  • caller_id_name = Ivan 

"Extension Number" Section Resources 

POST /extension/{extension_id}/callback/ 

Initiate a call. The extension_id specified in the path is required to be the identifier of the extension number of the 'phone' type. 

URL Options 

Name 

Type 

Name 

Type 

extension_id 

string 

JSON Options 

Name 

Type 

Mandatory 

Name 

Type 

Mandatory 

allow_public_transfer 

boolean 

no 

announce_sound_id  

long 

no 

call_duration 

long 

no 

caller_id_name 

string 

no 

caller_id_number 

string 

no 

dst_ani  

string 

no 

dst_announce_sound_id  

long 

no 

dst_dtmf 

string 

no 

dst_num 

string 

yes 

src_caller_id_name 

string 

no 

src_caller_id_number 

string 

no 

src_num 

array [string] 

yes 

transfer_after_dst_hangup  

string 

no 

transfer_after_src_hangup 

string 

no 

wait_for_pickup 

long 

no 

Response Fields 

Name 

Type 

Name 

Type 

call_api_id 

string 

call_id 

string