~.pbx.kazoo.name.~ Connection

~.pbx.kazoo.name.~ Connection #

The ~.pbx.kazoo.name.~ PBX connection provides a data collection service for the ~.pbx.kazoo.name.~ UCaaS/CPaaS platform.

The table below outlines the settings required when configuring a ~.pbx.kazoo.name.~ PBX connection:

Setting Description
Name A unique name to be able to easily identify the use of the connection.
API Key The API key to allow ~.Dimensions.~ to connect to ~.pbx.kazoo.name.~ and monitor the customer's communications.
Account ID The ~.pbx.kazoo.name.~ tenant Account ID for the customer.
Rest API REST API connection URL.
WebSocket API WebSocket connection URL
Country The location of the phone system connection. This is used to localise the telephone numbers for the connection.

Configuration Requirements #

The following requirements apply to ~.pbx.kazoo.name.~ PBX connections:

Item Requirement
Minimum Version 4.2
Numbering Plan ~.Dimensions.~ requires a unique numbering plan to be able to distinguish between devices and users. Device 'SIP Usernames' cannot be the same as any extension number (inc. Users extension/presence Id, call flows etc)
Users All ~.pbx.kazoo.name.~ users MUST have the following in order to be monitored correctly:
  • A valid and unique email address configured against their account
  • A Presence Id (used to show the user's number on reports)
In addition, in order to be able to login into the ~.Dimensions.~ portal, the user's username on ~.pbx.kazoo.name.~ must be their email address.
Agent Summary Filtering Agent status is not currently filterable by Queue. When filtering the Agent Summary report by Queue, all agents will be shown with their status for the corresponding date range of the report. Only call information can be filtered against a specific if required. This is due to the fact that specific queue information is not stored historically against agent status events.

API Key #

This API key is generated from the ~.pbx.kazoo.name.~ portal using the "Authentication" application. It allows ~.Dimensions.~ to connect to your ~.pbx.kazoo.name.~ installation.

Screenshot

Account ID #

The ~.pbx.kazoo.name.~ tenant Account Id is required for the specific customer on the ~.pbx.kazoo.name.~ platform. This allows ~.Dimensions.~ to uniquely identify this customer's users and calls on the ~.pbx.kazoo.name.~ platform. This can be found from the ~.pbx.kazoo.name.~ portal using the "Control Centre" application. Edit the Account Name and it is shown.

Screenshot

Where possible, an API key at the highest level should be used to allow ~.Dimensions.~ to monitor multiple customers through a single connection to ~.pbx.kazoo.name.~. This will reduce the load on the ~.pbx.kazoo.name.~ instance.

API Connections #

To connect to the ~.pbx.kazoo.name.~ platform, ~.Dimensions.~ requires access to the REST and WebSocket APIs. Please enter the URLs for these in the boxes provided.

Crossbar REST API URL

If you are usingui.zswitch.net, then the Crossbar (REST) ishttps://ui.zswitch.net

Document note
Remove the "/v2" from the end of the URL if it exists.

Blackhole WebSocket URL

If you are usingui.zswitch.net, then the Blackhole (WebSocket) iswss://api.zswitch.net:5443

Document note
Remove the "/v2" from the end of the URL if it exists.

ACDC Support

If using a version of ~.pbx.kazoo.name.~ which supports ACDC instead of Qubicle, Queue & Agent events can be monitored if the EDR socket is enabled. The same URL configured for Blackhole will be used to connect to the EDR socket.

DNS SRV #

~.Dimensions.~ supports DNS SRV records for both the Crossbar and Blackhole connections. when setting up your SRV records, the prefixes listed below must be used for each of the different connection types:

Connection Type DNS SVR Prefix
Crossbar REST API _crossbar._tcp
Blackhole WebSocket _blackhole._tcp
WebRTC _webrtc._tcp

Example Crossbar SRV Configuration The example below shows two SRV records for a Crossbar connection. more can be configured as required.

In the ~.Dimensions.~ PBX Template, the Crossbar would be configured tohttps://zone1.example.com .

\_crossbar.\_tcp.zone01.example.com.	1	IN	SRV	10 100 8443 apps001-ca.example.com.
\_crossbar.\_tcp.zone01.example.com.	1	IN	SRV	100 10 8443 apps001-fl.example.com.

Example Blackhole SRV Configuration

In the ~.Dimensions.~ PBX Template, the Blackhole would be configured towss://zone1.example.com .

\_blackhole.\_tcp.zone01.example.com.	1	IN	SRV	10 100 2096 apps001-ca.example.com.
\_blackhole.\_tcp.zone01.example.com.	1	IN	SRV	100 10 2096 apps001-fl.example.com.

Example WebRTC SRV Configuration

\_webrtc.\_tcp.zone01.example.com.	1	IN	SRV	10 100 5065 apps001-ca.example.com.
\_webrtc.\_tcp.zone01.example.com.	1	IN	SRV	100 10 5065 apps001-fl.example.com.
Document note
If using any of the ~.UcClient.~ softphones (Desktop, Mobile or CRM), an additional Outbound Proxy setting needs configuring on your reseller account. Please contact ~.Dimensions.~ support to have this setup.

~.pbx.kazoo.name.~ Platform Requirements/Restrictions #

Rate Limiting #

~.Dimensions.~ performs a number of queries and requests during its initial startup process when it is learning about the customer's ~.pbx.kazoo.name.~ instance. If the rate limits on the ~.pbx.kazoo.name.~ instance have been set too low, it is possible for this initial startup to fail. If this happening, a member of ~.Dimensions.~ support will be in contact with more information.

WebSocket Events #

~.Dimensions.~ requires the following events to be enabled on the WebSocket to allow all calls to be modelled and programming modifications to be tracked:

"data": {
	"call": [	
		"call.CHANNEL_CREATE.{CALL_ID}",
        "call.CHANNEL_ANSWER.{CALL_ID}",
        "call.CHANNEL_DESTROY.{CALL_ID}",
		"call.CHANNEL_HOLD.{CALL_ID}",
		"call.CHANNEL_UNHOLD.{CALL_ID}",
		"call.CHANNEL_BRIDGE.{CALL_ID}",
		"call.PARK_PARKED.{CALL_ID}",
		"call.PARK_RETRIEVED.{CALL_ID}",
		"call.PARK_ABANDONED.{CALL_ID}"
		][	
		"call.CHANNEL_CREATE.{CALL_ID}",
        "call.CHANNEL_ANSWER.{CALL_ID}",
        "call.CHANNEL_DESTROY.{CALL_ID}",
		"call.CHANNEL_HOLD.{CALL_ID}",
		"call.CHANNEL_UNHOLD.{CALL_ID}",
		"call.CHANNEL_BRIDGE.{CALL_ID}",
		"call.PARK_PARKED.{CALL_ID}",
		"call.PARK_RETRIEVED.{CALL_ID}",
		"call.PARK_ABANDONED.{CALL_ID}"
		],
	"conference": [ 
		"conference.command.{CONFERENCE_ID}",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.undeaf-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.deaf-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.unmute-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.mute-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.start-talking",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.stop-talking",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.del-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.add-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.unlock",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.lock",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.conference-destroy",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.conference-create",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.\*"
		][ 
		"conference.command.{CONFERENCE_ID}",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.undeaf-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.deaf-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.unmute-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.mute-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.start-talking",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.stop-talking",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.del-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.add-member",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.unlock",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.lock",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.conference-destroy",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.conference-create",
		"conference.event.{CONFERENCE_ID}.{CALL_ID}.*"
		],
	"fax": [	
		"fax.status.{FAX_ID}",
		"fax.object.{ACTION}"
		][	
		"fax.status.{FAX_ID}",
		"fax.object.{ACTION}"
		],
	"object": [
	"object.doc_created.account",
	"object.doc_created.callflow",
	"object.doc_created.device",
	"object.doc_created.faxbox",
	"object.doc_created.media",
	"object.doc_created.user",
	"object.doc_created.vmbox",
	"object.doc_created.fax",
	"object.doc_created.mailbox_message",
	"object.doc_created.call_recording",
	"object.doc_edited.account",
	"object.doc_edited.callflow",
	"object.doc_edited.device",
	"object.doc_edited.faxbox",
	"object.doc_edited.media",
	"object.doc_edited.user",
	"object.doc_edited.vmbox",
	"object.doc_edited.fax",
	"object.doc_edited.mailbox_message",
	"object.doc_edited.call_recording",
	"object.doc_deleted.account",
	"object.doc_deleted.callflow",
	"object.doc_deleted.device",
	"object.doc_deleted.faxbox",
	"object.doc_deleted.media",
	"object.doc_deleted.user",
	"object.doc_deleted.vmbox",
	"object.doc_deleted.fax",
	"object.doc_deleted.mailbox_message",
	"object.doc_deleted.call_recording"
	][
	"object.doc_created.account",
	"object.doc_created.callflow",
	"object.doc_created.device",
	"object.doc_created.faxbox",
	"object.doc_created.media",
	"object.doc_created.user",
	"object.doc_created.vmbox",
	"object.doc_created.fax",
	"object.doc_created.mailbox_message",
	"object.doc_created.call_recording",
	"object.doc_edited.account",
	"object.doc_edited.callflow",
	"object.doc_edited.device",
	"object.doc_edited.faxbox",
	"object.doc_edited.media",
	"object.doc_edited.user",
	"object.doc_edited.vmbox",
	"object.doc_edited.fax",
	"object.doc_edited.mailbox_message",
	"object.doc_edited.call_recording",
	"object.doc_deleted.account",
	"object.doc_deleted.callflow",
	"object.doc_deleted.device",
	"object.doc_deleted.faxbox",
	"object.doc_deleted.media",
	"object.doc_deleted.user",
	"object.doc_deleted.vmbox",
	"object.doc_deleted.fax",
	"object.doc_deleted.mailbox_message",
	"object.doc_deleted.call_recording"
	]
}

Crossbar API Requests #

The following Crossbar API requests are use by Dimensions:

General Usage

{CROSSBAR}/v2/api_auth,httpMethod=PUT
{CROSSBAR}/v2/websockets,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/api_key,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/descendants?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/users?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/users/{USERID},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/users/{USERID}/quickcall/{DESTINATION},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/users/{USERID}/presence,httpMethod=POST
{CROSSBAR}/v2/accounts/{ACCOUNTID}/devices?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/devices/{DEVICEID},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/devices/{DEVICEID}/quickcall/{DESTINATION},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/callflows?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/callflows?{Query String Filters},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/callflows/{CALLFLOWID},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/groups?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/groups/{GROUPID}?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/conferences?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/conferences/{CONFERENCEID},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/vmboxes?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/metaflows,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/storage,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/channels,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/channels/{CHANNELID},httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/channels/{CHANNELID},httpMethod=PUT
{CROSSBAR}/v2/accounts/{ACCOUNTID}/resources,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/qubicle_queues?paginate=false,httpMethod=GET
{CROSSBAR}/v2/accounts/{ACCOUNTID}/qubicle_queues/{QUEUEID},httpMethod=GET

~.UcClient.~ ACD Control

Used while controlling agent state from ~.UcClient.~ and Dashboard.

{CROSSBAR}/v2/accounts/{ACCOUNTID}/qubicle_recipients/status,httpMethod=POST,content={"data":{"recipient_ids":["{RECIPIENTID1}","{RECIPIENTID2}"]["{RECIPIENTID1}","{RECIPIENTID2}"]}}
{CROSSBAR}/v2/accounts/{ACCOUNTID}/qubicle_recipients/{USERID},httpMethod=POST
{CROSSBAR}/v2/accounts/{ACCOUNTID}/qubicle_recipients/{USERID}/status,httpMethod=POST

Presence Profile Control

Used when Presence Profiles are enabled on the ~.UcClient.~.

{CROSSBAR}/v2/accounts/{accountId}/users/{userId},httpMethod=PATCH
{CROSSBAR}/v2/accounts/{accountId}/callflows/{callFlowId},httpMethod=POST
{CROSSBAR}/v2/accounts/{accountId}/callflows/groups/{groupId},httpMethod=POST
{CROSSBAR}/v2/accounts/{accountId}/callflows/groups/{groupId},httpMethod=POST

ACDC Support on Open Source

Used if running Open source Kazoo using ACDC and EDR agent/queue events.

{crossbar}/v2/accounts/{accountId}/queues,httpMethod=GET
{crossbar}/v2/accounts/{accountId}/queues/{queueId},httpMethod=GET
{crossbar}/v2/accounts/{accountId}/queues/{queueId}/stats_summary,httpMethod=GET
{crossbar}/v2/accounts/{accountId}/agents/{recipientId}/status,httpMethod=GET
{crossbar}/v2/accounts/{accountId}/agents/{userId}/status,httpMethod=POST

Platform Restrictions #

The restrictions listed below apply to the latest version of ~.pbx.kazoo.name.~ supported.

Restriction Description
Call flow Tracking No call information can be collected via the web socket API for calls while they are in a call flow. Call tracking will begin once a call interacts with a user/device or Qubicle/CCPro Queue.
Voicemail Tracking Calls which are deflected to voicemail from a phone cannot be tracked as having gone to voicemail and will instead be modelled as not being answered. This is due to insufficient information being provided through the web socket API in order for the correct scenario to be modelled.
Announced Transfer Tracking Due to the way the call events are generated we recommend that any phones be configured for blind-transfer. If phones are not configured for blind-transfer and an attended transfer is hung up before it is connected, the call may not be modelled correctly. This is due to a limitation in FreeSWITCH.