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

Description of Data Structures

Event

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

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

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:

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

Если при этом внутренний номер “200” является владельцем звонка и осуществляет вызов на самого себя, то для оптимизации не будет событий вызова самого внутреннего номера. Например, соединение внутреннего номера "200" с номером "+79817654321" от имени внутреннего номера "200" инициирует "dial-out" с "200" на "+79817654321" (не будет "dial-in" с "200" на "200" и "dial-out" с "200" на "200").

События message-in и message-out доступны только для внутренних номеров типа “phone”

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:

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

…

System response:

{
  "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:

<?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

[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

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

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

DELETE /extension/{extension_id}/event/

DELETE /extension/{extension_id}/event/

Delete all events of the extension number

URL Options

Name	Type
extension_id	string

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

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

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