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:
“@{VAR_NAME}” if it is the extension_id in the request URL
“$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
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)
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 :
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.