Page Comparison

_{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 (/variables/). You must set them first in the resource Variables (/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

Table of Contents

Description of Data Structures

Call-Info: <sip:anonymous@anonymous.invalid>;answer-after=4

Expand

title	Expand

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

such as "queue",

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

Variables and their values that may be used further in rules ivr for check varaible, or adds a variable to the request call interactive (in call interactive, the passed variable will always be prefixed with cb_variable_ to avoid overwriting the standard options call_interactive)

Also, using the variables, you can specify:
Auto answer in x sec by specifying in variables

autoanswer ranging from 0 to 300

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

An example of using callback with variables:

Code Block

language	json

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

"autoanswer": "4" will add the sip header Call-Info for src and dst:

Code Block

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

Info
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 (/variables/):

ext_id = 34535
caller_id_name = Ivan

Tabs

[{"content":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"In the "},{"type":"text","text":"authentication ","marks":[{"type":"strong"}]},{"type":"text","text":"section enter the "},{"type":"text","text":"Application_ID","marks":[{"type":"strong"}]},{"type":"text","text":" and "},{"type":"text","text":"Application_Secret","marks":[{"type":"strong"}]},{"type":"text","text":" values obtained during the application registration in the "},{"type":"text","text":"client_id ","marks":[{"type":"strong"}]},{"type":"text","text":"and "},{"type":"text","text":"client_secret","marks":[{"type":"strong"}]},{"type":"text","text":" fields, then click on the \""},{"type":"text","text":"Try it out!","marks":[{"type":"strong"}]},{"type":"text","text":"\" button. If the application data is correct, an access token ("},{"type":"text","text":"access_token","marks":[{"type":"strong"}]},{"type":"text","text":") will be returned in response. The received access token should be entered into the \""},{"type":"text","text":"Access Token Field","marks":[{"type":"strong"}]},{"type":"text","text":"\" at the top of the page and saved by clicking the \""},{"type":"text","text":"Set Token","marks":[{"type":"strong"}]},{"type":"text","text":"\" button."}]},{"type":"table","attrs":{"isNumberColumnEnabled":false,"layout":"default"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"Method","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"Resource","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"Data","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"POST"}]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"/extension/@ext_id/callback/"}]},{"type":"paragraph","content":[{"type":"text","text":" "}]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"{\"caller_id_name\": \"$cv(caller_id_name)\",","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"\"dst_num\": \"string\",","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"\"src_num\": [\"string\"]}","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[]}]},"id":"d0c23076-029a-4288-b544-105c3032f0a8","label":"Interactive API Browser","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"To send requests using the cURL program, set the values of the "},{"type":"text","text":"url ","marks":[{"type":"strong"}]},{"type":"text","text":"and "},{"type":"text","text":"access_token","marks":[{"type":"strong"}]},{"type":"text","text":" variables:"}]},{"type":"paragraph","content":[{"type":"text","text":"export url=\"https://<hostname>/api/ver1.0\"","marks":[{"type":"code"}]},{"type":"text","text":" "},{"type":"hardBreak"},{"type":"text","text":"(where the hostname — is the hostname of the API-server provider of IP-telephony),"}]},{"type":"paragraph","content":[{"type":"text","text":"export access_token=\"8SNsrS0jV35vfmKqKeKtRrHfpbg4UX\"","marks":[{"type":"code"}]},{"type":"text","text":" "},{"type":"hardBreak"},{"type":"text","text":"(the received access token)."}]},{"type":"paragraph","content":[{"type":"text","text":"Send a request:"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"type":"text","text":"curl -H \"Authorization: Bearer ${access_token}\"  -H \"Content-Type: application/json\" -d '{\"caller_id_name\": \"$cv(caller_id_name)\",\"dst_num\": \"string\",\"src_num\": [\"string\"]}'  -X POST ${url}/extension/@ext_id/callback/"}]}]},"id":"cc141cac-0d63-4725-8688-2fee1d49c8a6","label":"cURL Program","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"To send requests in Python, set the values of the variables URL and ACCESS_TOKEN:"}]},{"type":"paragraph","content":[{"type":"text","text":"URL = \"https://<hostname>/api/ver1.0\"","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"(where the hostname — is the hostname of the API-server provider of IP-telephony),"}]},{"type":"paragraph","content":[{"type":"text","text":"ACCESS_TOKEN = \"8SNsrS0jV35vfmKqKeKtRrHfpbg4UX\"","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"(the received access token)."}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"#!/usr/bin/python\n\nimport requests\n\nurl = f'{URL}/extension/@ext_id/callback/'\nheaders = {\n    'Authorization': f'Bearer {ACCESS_TOKEN}',\n    'Content-Type': 'application/json'\n}\ndata = '''{\"caller_id_name\": \"$cv(caller_id_name)\",\"dst_num\": \"string\",\"src_num\": [\"string\"]}'''\nresponse = requests.post(url, headers=headers, data=data)\nprint(response.text)"}]}]},"id":"7240e9bc-4b0b-4784-a4e7-b0bc63959b6f","label":"In Python3","type":"tab"}]

"Extension Number" Section Resources

Expand

title	POST /extension/{extension_id}/callback/

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
extension_id	string

JSON Options

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
call_api_id	string
call_id	string

Versions Compared

Old Version 5

New Version Current

Key

Description of Data Structures

Example of Using Variables in Request

"Extension Number" Section Resources