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}^).

Using this resource, you can notify third-party applications about extension number events. Quantity of monitored events is limited, you can get the limit through the resource "Limits (/limit/)".

Table of Contents

Description of Data Structures

Event

Expand

title	Expand

Name

Type

Mandatory

Default Value

Description

url

string

yes

URL, where the request is sent to, when an event occurs. For example: 'https://myshost.org/calls'

event_type

string

yes

An extension number event that causes a request to be sent. The options are:

dial-in: incoming call;
dial-out: outgoing call;
hangup: end of connection;
answer: answer;
message-in: incoming message;
message-out: outgoing message;
voicemail: voice message is received

method

string

yes

Request method

GET
POST

Event Data

Expand

title	Expand

If the request method is GET, the data will be in the request header; but if the request method is POST, the data will be in the request body. In both cases, the data is in the format application/x-www-form-urlencoded.

Name	Type	Description
EventType	string	Type of Event. Depending on the event type, the value may be dial-in, dial-out, hangup, answer, message-in or message-out
CallID	string	Unique call identifier. It is not changed when forwarding. You can use it to identify belonging of different events to the same call
CallerIDNum	string	Caller number
CallerIDName	string	Caller name (if any)
CalledDID	string	Callee public number (if any)
CalledExtension	string	Name of the called extension number (in the form xxx*yyy@domain)
CalledExtensionID	int	Identifier of the called extension number. It is convenient for subsequent API calls waiting for еру identifier
CallStatus	string	Call status. For the event_type dial-in and dial-out: CALLING For the event_type answer: ANSWER For the event_type hangup: ANSWER: the call was answered BUSY: the call received a signal "busy" NOANSWER: the call was not answered (the server timeout timer expired) CANCEL: the caller canceled the call before the server timeout timer expiration CONGESTION: an error occurred during the call CHANUNAVAIL: the callee has no registration For the event_type message-in and message-out, event data is available in the page "Messages (/message/) and Chats (/chat/)."
CallFlow	string	Call direction: IN: incoming; OUT: outgoing
CallerExtension	string	Caller extension number (in the form xxx*yyy@domain)
CallerExtensionID	int	Identifier of the caller extension number. It is convenient for subsequent API calls waiting for the identifier
CalledNumber	string	Called number
RecID	string	If call recording is switched on for the extension number, then its identifier is contained here. It is equivalent to record_uuid in REST API. You can get the record file using this identifier. It is meaningful for events hangup and voicemail only
CallAPIID	string	Unique call identifier to manage the call (for example: break, transfer, parking)
Diversion	string	Number from the same SIP field when the call incomes to the PBX (rfc5806). Optional (only if it is present in SIP headers). It usually shows the number that had forwarded the call before the call came to the PBX
EventTime	int	Event generation time: microseconds since January 1, 1970
Duration	int	For the event hangup, contains the talk time, in microseconds. For the event voicemail, it is message duration
Transfered	string	When it is present in the events CallFlow=out, it allows you to differ calls initiated by an extension number from calls forwarded from an extension number: yes: the outgoing call has occurred as a result of forwarding The field may be missing
Bridged	string	It is present in queue events (CallFlow='in') and voice menus (IVR): yes: the call was answered after it was put in the queue /IVR; no: the call was not answered after it was put in the queue /IVR
BridgedDuration	int	Optional. For the event hangup, contains real conversation time, in microseconds. This paramter is usefull when Duration doesn’t contain real conversation time: for example if src_num for call initiation is a queue
CallBackID	string	It is present when the call is initiated. It may be useful when you need to determine whether multiple events belong to one call initiation
SubCallID	string	Unlike the option CallID that is the same for the whole call; this option allows you to select a component in the call. For example, if, within one call, the call came to one extension number several times (for example, several times in a circle, as a queue agent), then this option differs. It is useful for you to group the call components dial-in, dial-out, answer, hangup
ClientApiID	string	Optional. Includes the content of the SIP header Client-Api-Id when forming a client-side call. This option is convenient to relate events with calls initiated by the client equipment. The SIP header length must not exceed 100 characters. For example: "Client-Api-Id: 1234567Az"
RemoteNumber	string	Optional. It is present for incoming calls if CallerIDNum does not match the number that is connected to (for example, when transferring an outgoing call from one extension number to another)
ANI	string	Optional. For outgoing calls (CallFlow=out) to numbers outside the PBX (for example, mobile), this option allows you to determine the number set for identification
Tag	string	If the tag variable is set when a call is initiated, it will appear in the events of that call. With its help, it is convenient to track the belonging of an event to a group of calls.

Generation Features

Voice menu (IVR): when a call comes in, a dial-in event is generated, when a call is released, a hangup event is generated (thus, there are no events dial-out and answer).

The queue works with two threads:

Thread	Description
in	When a call is put in the queue this option has the value dial-in, when the connection ends this option has the value hangup (there is no answer event)
out	When calling each of the queue agents this option has the value dial-in; if the call was answered this option has the value answer; when the connection ends this option has the value hangup

If the call is forwarded to a number outside the PBX using incoming call rules (the extension number type does not matter), then a dial-out event is generated from this extension number to the corresponding number with the option Transfered: "yes".

Let's say the following call initiation (callback) is used:

Code Block

language	json

POST /extension/@200/callback/
{
  "dst_num": "+79817654321",
  "src_num": [
    "200"
  ]
}

If at the same time the internal number “200” is the owner of the call and makes a call to itself, then for optimization there will be no call events for the internal number itself. For example, connecting the extension number "200" with the number "+79817654321" on behalf of the extension number "200" initiates the "dial-out" from "200" to "+79817654321" (there will be no "dial-in" from "200" to " 200 "and" dial-out "from" 200 "to" 200 ").

Info
Events message-in и message-out available only for internal numbers of the “phone” type

Example

For extension number 000*099 with ID 175 and call recording enabled, let’s add events 'dial-out', 'answer', 'hangup'. The options "?myid=175" are added to all URLs to make it clear on the side https://somehost.com/ who owns the event if the events are generated from different extension numbers. 

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/175/event/"}]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"{"},{"type":"hardBreak"},{"type":"text","text":"\"url\": \""},{"type":"text","text":"https://somehost.com/fordel/show.php?myid=175","marks":[{"type":"link","attrs":{"href":"https://somehost.com/fordel/show.php?myid=175"}}]},{"type":"text","text":"\","},{"type":"hardBreak"},{"type":"text","text":"\"method\": \"GET\","},{"type":"hardBreak"},{"type":"text","text":"\"event_type\": \"dial-out\""},{"type":"hardBreak"},{"type":"text","text":"}"}]}]}]}]},{"type":"paragraph","content":[]}]},"id":"be851b15-6460-4049-a125-d6c576a4db46","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 \\\n-H \"Authorization: Bearer ${access_token}\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n    \"url\": \"https://somehost.com/fordel/show.php?myid=175\",\n    \"method\": \"GET\",\n    \"event_type\": \"dial-out\"\n}' \\\n-X POST ${url}/extension/175/event/"}]}]},"id":"737a8c55-9ae5-4b82-8f47-dc6439feb333","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/175/event/'\nheaders = {\n    'Authorization': f'Bearer {ACCESS_TOKEN}',\n    'Content-Type': 'application/json'\n}\ndata = '''{\n    \"url\": \"https://somehost.com/fordel/show.php?myid=175\",\n    \"method\": \"GET\",\n    \"event_type\": \"dial-out\"\n    }'''\nresponse = requests.post(url, headers=headers, data=data)\nprint(response.text)"}]}]},"id":"3e376471-cfcb-4425-b1d0-7e05153ce340","label":"In Python3","type":"tab"}]

System response:

Code Block

language	json

{
  "url": "https://somehost.com/fordel/show.php?myid=175",
  "method": "GET",
  "event_type": "dial-out",
  "id": 72
}

Tabs

[{"content":{"version":1,"type":"doc","content":[{"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/175/event/"}]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"{"},{"type":"hardBreak"},{"type":"text","text":"\"url\": \""},{"type":"text","text":"https://somehost.com/fordel/show.php?myid=175","marks":[{"type":"link","attrs":{"href":"https://somehost.com/fordel/show.php?myid=175"}}]},{"type":"text","text":"\","},{"type":"hardBreak"},{"type":"text","text":"\"method\": \"GET\","},{"type":"hardBreak"},{"type":"text","text":"\"event_type\": \"answer\""},{"type":"hardBreak"},{"type":"text","text":"}"}]}]}]}]},{"type":"paragraph","content":[]}]},"id":"2ca15d35-6928-4223-a7b0-3478d2193286","label":"Interactive API Browser","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"curl \\\n-H \"Authorization: Bearer ${access_token}\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n    \"url\": \"https://somehost.com/fordel/show.php?myid=175\",\n    \"method\": \"GET\",\n    \"event_type\": \"answer\"\n}' \\\n-X POST ${url}/extension/175/event/"}]}]},"id":"a8e45825-7983-4d88-aaf2-1c221ea0fef2","label":"cURL Program","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"#!/usr/bin/python\n\nimport requests\n\nurl = f'{URL}/extension/175/event/'\nheaders = {\n    'Authorization': f'Bearer {ACCESS_TOKEN}',\n    'Content-Type': 'application/json'\n}\ndata = '''{\n    \"url\": \"https://somehost.com/fordel/show.php?myid=175\",\n    \"method\": \"GET\",\n    \"event_type\": \"answer\"\n    }'''\nresponse = requests.post(url, headers=headers, data=data)\nprint(response.text)"}]}]},"id":"88fe62c9-06a6-4dc3-b5e4-92797f158516","label":"In Python3","type":"tab"}]

System response:

Code Block

language	json

{
  "url": "https://somehost.com/fordel/show.php?myid=175",
  "method": "GET",
  "event_type": "answer",
  "id": 73
}

Tabs

[{"content":{"version":1,"type":"doc","content":[{"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/175/event/"}]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"{"},{"type":"hardBreak"},{"type":"text","text":"\"url\": \""},{"type":"text","text":"https://somehost.com/fordel/show.php?myid=175","marks":[{"type":"link","attrs":{"href":"https://somehost.com/fordel/show.php?myid=175"}}]},{"type":"text","text":"\","},{"type":"hardBreak"},{"type":"text","text":"\"method\": \"GET\","},{"type":"hardBreak"},{"type":"text","text":"\"event_type\": \"hangup\""},{"type":"hardBreak"},{"type":"text","text":"}"}]}]}]}]},{"type":"paragraph","content":[]}]},"id":"6e115913-2cd8-485a-ad8d-d105229831a1","label":"Interactive API Browser","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"type":"text","text":"curl \\\n-H \"Authorization: Bearer ${access_token}\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n    \"url\": \"https://somehost.com/fordel/show.php?myid=175\",\n    \"method\": \"GET\",\n    \"event_type\": \"hangup\"\n}' \\\n-X POST ${url}/extension/175/event/"}]}]},"id":"578cbcce-4df4-4af4-8a7a-34ef92b3bb38","label":"cURL Program","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"#!/usr/bin/python\n\nimport requests\n\nurl = f'{URL}/extension/175/event/'\nheaders = {\n    'Authorization': f'Bearer {ACCESS_TOKEN}',\n    'Content-Type': 'application/json'\n}\ndata = '''{\n    \"url\": \"https://somehost.com/fordel/show.php?myid=175\",\n    \"method\": \"GET\",\n    \"event_type\": \"hangup\"\n    }'''\nresponse = requests.post(url, headers=headers, data=data)\nprint(response.text)"}]}]},"id":"93199f00-50d0-449b-8392-f9e772c4a9f6","label":"In Python3","type":"tab"}]

System response:

Code Block

language	json

{
  "url": "https://somehost.com/fordel/show.php?myid=175",
  "method": "GET",
  "event_type": "hangup",
  "id": 74
}

If the script show.php on the side somehost.com looks like:

Code Block

language	php

<?php
error_log("------");
foreach ($_GET as $key => $value){
    error_log("$key => $value");
}
?>

then, after a call from the extension number 000*099 to the number 00010005, you may see in the web server log file the records of the form:

Expand

title	Expand

Code Block

[Thu Jul 06 17:03:59 2017]  ------
[Thu Jul 06 17:03:59 2017]  myid => 175
[Thu Jul 06 17:03:59 2017]  SubCallID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:03:59 2017]  EventTime => 1499349840250190
[Thu Jul 06 17:03:59 2017]  CalledNumber => 00010005
[Thu Jul 06 17:03:59 2017]  EventType => dial-out
[Thu Jul 06 17:03:59 2017]  CallerIDNum => 000*099
[Thu Jul 06 17:03:59 2017]  CallerExtensionID => 175
[Thu Jul 06 17:03:59 2017]  CallerExtension => 000*099@sip.domain
[Thu Jul 06 17:03:59 2017]  CallFlow => out
[Thu Jul 06 17:03:59 2017]  CallAPIID => 3584705177-31845fca-8562-4b7a-94cf-7b4036fd6d52
[Thu Jul 06 17:03:59 2017]  CallerIDName => Iggy Pop
[Thu Jul 06 17:03:59 2017]  CallStatus => CALLING
[Thu Jul 06 17:03:59 2017]  CallID => 31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:01 2017]  ------
[Thu Jul 06 17:04:01 2017]  myid => 175
[Thu Jul 06 17:04:01 2017]  SubCallID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:01 2017]  EventTime => 1499349842091175
[Thu Jul 06 17:04:01 2017]  CalledNumber => 00010005
[Thu Jul 06 17:04:01 2017]  EventType => answer
[Thu Jul 06 17:04:01 2017]  CallerIDNum => 000*099
[Thu Jul 06 17:04:01 2017]  CallerExtensionID => 175
[Thu Jul 06 17:04:01 2017]  CallerExtension => 000*099@sip.domain
[Thu Jul 06 17:04:01 2017]  CallFlow => out
[Thu Jul 06 17:04:01 2017]  CallAPIID => 3584705177-31845fca-8562-4b7a-94cf-7b4036fd6d52
[Thu Jul 06 17:04:01 2017]  CallerIDName => Iggy Pop
[Thu Jul 06 17:04:01 2017]  CallStatus => ANSWER
[Thu Jul 06 17:04:01 2017]  CallID => 31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  ------
[Thu Jul 06 17:04:05 2017]  myid => 175
[Thu Jul 06 17:04:05 2017]  SubCallID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  EventTime => 1499349846331075
[Thu Jul 06 17:04:05 2017]  CalledNumber => 00010005
[Thu Jul 06 17:04:05 2017]  EventType => hangup
[Thu Jul 06 17:04:05 2017]  CallerIDNum => 000*099
[Thu Jul 06 17:04:05 2017]  CallerExtensionID => 175
[Thu Jul 06 17:04:05 2017]  CallerExtension => 000*099@sip.domain
[Thu Jul 06 17:04:05 2017]  CallFlow => out
[Thu Jul 06 17:04:05 2017]  RecID => 175-31845fca85624b7a94cf7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  CallAPIID => 3584705177-31845fca-8562-4b7a-94cf-7b4036fd6d52
[Thu Jul 06 17:04:05 2017]  CallerIDName => Iggy Pop
[Thu Jul 06 17:04:05 2017]  Duration => 4239900
[Thu Jul 06 17:04:05 2017]  CallStatus => ANSWER
[Thu Jul 06 17:04:05 2017]  CallID => 31845fca85624b7a94cf7b4036fd6d52

"Extension Number” Section Resources

Expand

title	POST /extension/{extension_id}/event/

POST /extension/{extension_id}/event/

Add the extension number event

URL Options

Name	Type
extension_id	string

JSON Options

Name	Type	Mandatory
url	string	yes
event_type	string	yes
method	string	yes

Response Fields

Name	Type
url	string
method	string
event_type	string
id	long

Expand

title	GET /extension/{extension_id}/event/

GET /extension/{extension_id}/event/

Get the extension number event list

URL Options

Name	Type
extension_id	string

Response Fields

Имя	Тип
url	string
method	string
event_type	string
id	long

Expand

title	DELETE /extension/{extension_id}/event/

DELETE /extension/{extension_id}/event/

Delete all events of the extension number

URL Options

Name	Type
extension_id	string

Expand

title	PUT /extension/{extension_id}/event/{id}

PUT /extension/{extension_id}/event/{id}

Update the extension number event

URL Options

Name	Type
extension_id	string
id	integer

JSON Options

Name	Type	Mandatory
url	string	no
event_type	string	no
method	string	no

Response Fields

Name	Type
url	string
method	string
event_type	string
id	long

Expand

title	GET /extension/{extension_id}/event/{id}

GET /extension/{extension_id}/event/{id}

Get the extension number event

URL Options

Name	Type
extension_id	string
id	integer

Response Fields

Name	Type
url	string
method	string
event_type	string
id	long

Expand

title	DELETE /extension/{extension_id}/event/{id}

DELETE /extension/{extension_id}/event/{id}

Delete the extension number event

URL Options

Name	Type
extension_id	string
id	integer

Versions Compared

Old Version 5

New Version Current

Key

Description of Data Structures

Event

Event Data

Generation Features

Example

"Extension Number” Section Resources