Versions Compared

Old Version 2

changes.mady.by.user esnata

Saved on

compared with

New Version 3

changes.mady.by.user esnata

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

You can test API methods in the API online browser page on the interactive API browser page and without writing any code
Some of the resources described in on the page may not be available by default due to the type of application type (see Application Creation and Authorization)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
titleExpand

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 messageincoming message; 

  • message-out: outgoing messageoutgoing message; 

  • voicemail: voice message is  voice message is received 

method 

string 

yes 

 

Request method 

  • GET 

  • POST  

Event Data 

Expand
titleExpand

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 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 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 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 using incoming call rules 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 following call initiation (callback) is used: 

Code Block
languagejson
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"). 

Info

События 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 httpsside https://somehost.com/ who owns the event if the events are generated from different extension numbers.  

…

…

…

System response: 

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

…

…

…

System response: 

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

…

…

…

System response: 

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

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

Code Block
languagephp
<?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
titleExpand
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
titlePOST /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
titleGET /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
titleDELETE /extension/{extension_id}/event/

DELETE /extension/{extension_id}/event/ 

Delete all events of the extension number 

URL Options 

Name 

Type 

extension_id 

string

Expand
titlePUT /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
titleGET /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
titleDELETE /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