Events on Extension Numbers

Owned by esnata (Unlicensed)
Last updated: Jun 30, 2021
5 min read

You are recommended to add a full set of events for all ordinary telephone extension numbers (type = phone):

  • dial-in — incoming call to the extension number that is the event sender

  • dial-out — outgoing call from the extension number that is the event sender

  • answer — picking up the handset at the extension number that is the event sender (perhaps, in some integration, this event will be irrelevant)

  • hangup — hanging up the call at the extension number that is the event sender.

For all special extension numbers (type = IVR or queue), you are recommended to add the "hangup" event only.

To display readiness of the queue agent to accept a call, the queue agent event data is used (available: the agent is ready to receive calls from the queue, logged_out: the agent will not receive calls from the queue). The event data may be used in real-time monitoring.

Options of Events used for Analysis

The complete list of event options and their detailed description are in the section "Extension Number Events".

Name

Type

Description

Name

Type

Description

CallerIDNum

string

Caller number that default used to log incoming calls (event flow – dial-in)

CalledNumber

string

Callee number:

  • in case of an incoming call (event flow – dial-in), it is the extension number, which the incoming call on this event was received to

  • in case of an outgoing call (event flow – dial-out), it is the external called number that default is used to log outgoing calls

CallerExtension

string

Extension number that is an outgoing call initiator (event flow – dial-out). It has the format client_prefix*internal_number_name@PBX_domain_name, you should specify only the client_prefix*internal_number_name

CalledDID

string

Call source (the public number of the called subscriber, which the call got to the PBX through); if it is available, you must send it, because it is fixed in integration

Bridged

string

This option indicates whether the call was accepted globally within the entire PBX by the extension number user. If the call was accepted by an employee, then bridged = yes, if not, then bridged = no (no ordinary extension number answered to the incoming call). This option is transmitted only in “hangup” events from special extension numbers such as IVR and Queue

Transfered

string

This option takes the value yes (the outgoing call was caused as a result of forwarding), it is relevant only for outgoing calls (flow events – dial-out) that are corresponding to the call of the “answer” and “hangup” events

RemoteNumber

string

It may be present only in the "dial-in" event flow and indicates the external number, which this call is related to. It is used to understand what external number was connected when the call had been transferred from one extension number to another using transfer commands #1 and *2; in such situations, it is used instead of CallerIDNum when logging the call

CallBackID

string

Identifier of the callback (the outgoing call initiation ID via API). It is added if the call is generated on behalf of some extension number, but the connection occurs between the external number and some other number or an extension number other than the extension number initiated the call. For example, when a call order script in a site connects the number entered into it with the client PBX voice menu

Duration

integer

Call duration for each individual SubCallID, in microseconds

RecID

string

If call recording is switched on for the extension number, then its identifier is contained here. It is equivalent to record_uuid. Using this identifier, you can get the record file. It is meaningful for the "hangup" event only

CallStatus

string

Call status. A successful call has CallStatus=ANSWER, unsuccessful calls have the status CallStatus=CANCEL (canceled by the caller), CallStatus=BUSY (the called number is busy). Such calls should not go to the external system as successful.

Logging Call Data

All events of ordinary extension numbers for "dial-in" and "dial-out" events are analyzed and, in case of the "answer" event, they are logged by the "hangup" event and by SubCallID (instead of CallID) as separate calls. Thus, it is possible to divide the call within the PBX into separate call legs — before the transfer and after it and log them as separate calls.

Unanswered incoming calls are logged by presence of the option Bridged=no in the "hangup" events from the voice menu and queues. You should remember that Bridged=yes always indicates a successful incoming call. Its data should be recorded when analyzing "dial-in" events within their own SubCallID values.

Adding/Deleting Events on Extension Numbers

To maintain an up-to-date list of events on the extension numbers, it is recommended to send requests for adding/deleting events at the time when an administrator writes/changes the correspondence of users to their extension numbers in the integration settings. In this case, you cannot delete or update events that are not related to this integration, since the user may have several other active integrations.

The event quantity on one extension number according to standard tolerances is 16. Therefore, if it is impossible to add an event, you should inform the user of this information so that the user either deletes unused events on the extension number or sends a request to the PBX administrator to expand the limit of events on the extension numbers

Filtering Events Received form PBX

To configure filtering of events received from the PBX, you are recommended to read the subsection "Event Data (EventData)".

If you need to record only the external calls (to/from an external number), then you need to exclude from processing:

  • the events related to calls from one extension number to another:

    • in the CallerNum field: the extension number in the format [0-9]{3,6}*[0-9]{2,4}

    • in the CalledNum field: the extension number in the format [0-9]{3,6}*[0-9]{2,4}

  • the events related to internal forwarding:

    • in the Transfered field: "yes"

    • there is the CalledExtensionID field with a numeric ID

    • there is the CallerExtensionID field with a numeric ID

Event Example

The URL in the event could be: http://myintegration.com:8080/cid/807/queue/33334
where 807 — is the serial number of the Ringme application for this integration. In the future, this number may be used to filter out all events related to this user in the integration server log;
queue — is the type of extension number where the event URL is set. Setting different URLs allows you to conveniently separate events of different types of the extension numbers (phone, queue or IVR);
33334 — is the Extension ID that simplifies event analysis.

However, from a security point of view, it is better not to create such URLs for the events in commonly used integrations, because you can use such a URL for bulk sending of the events to other users, by selecting the client_id and extention_id. It is recommended to specify a URL like this: http://myintegration.com/ext-event/f2a8vdrfae0s1ku5d2rj3iximjf3twyz
where ext-event is the event type;
f2a8vdrfae0s1ku5d2rj3iximjf3twyz — is a unique identifier that exactly matches the extension number entry in your integration extension number table.

 

← Application Authorization and Integration Start Event Logic on Extension Numbers→