Extension Number Events (/extension/.../event/)

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/)". 

Description of Data Structures 

Event 

Name 

Type 

Mandatory 

Default Value 

Description 

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 

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 

Name 

Type 

Description 

EventType 

string 

Type of Event. Depending on the event type, the value may be dial-indial-outhangupanswer, 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-indial-outanswerhangup 

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 

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: 

POST /extension/@200/callback/ {   "dst_num": "+79817654321",   "src_num": [     "200"   ] }
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 ").

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.  

System response: 

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

System response: 

System response: 

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

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:  

"Extension Number” Section Resources 

POST /extension/{extension_id}/event/

Add the extension number event

URL Options

Name 

Type 

Name 

Type 

extension_id 

string 

JSON Options 

Name 

Type 

Mandatory 

Name 

Type 

Mandatory 

url 

string 

yes 

event_type 

string 

yes 

method 

string 

yes 

Response Fields 

Name 

Type 

Name 

Type 

url 

string

method 

string 

event_type 

string

id 

long 

GET /extension/{extension_id}/event/ 

Get the extension number event list 

URL Options 

Name 

Type 

Name 

Type 

extension_id 

string 

Response Fields 

Имя 

Тип 

Имя 

Тип 

url 

string

method 

string

event_type 

string

id 

long