HTTP Call Barring API

This API is intended to allow flexible call barring setting changes on the ComX PBX via HTTP. The external specification is described here are for integration with 3 rd party

applications or custom scripts. The term 'barring' means to block an extension from making an outgoing call

The security implications of web-accessible information retrieval must be carefully considered in each particular implementation environment.

Note that this feature is DISABLED by default and must be enabled as follows:

Edit the file /etc/commagui/control.properties, change: com.farsouthnet.comma.driver.control.ControlConfiguration.enabled = false

to

com.farsouthnet.comma.driver.control.ControlConfiguration.enabled = true , and then restart the GUI.

Http BASIC authorization is used for security. The authorisation credentials must be separately maintained using the /etc/commagui/control.htpasswd file on the Com.X.

This file is updated from the Com.X shell as follows:

sudo htpasswd -b /etc/commagui/control.htpasswd <username> <password>

To delete a user, use the following command:

sudo htpasswd -D /etc/commagui/control.htpasswd <username>

The username/password may be embedded in the call URL by adding before the

pbx_ip as follows: http://username:password@pbx_ip/...

By default, the username admin, password C@11Me which is accepted for any extension. It is advised to change this password using the above command.

Obtaining list of extensions

GET http://pbx_ip/commagui/control/extlist

Response e.g. : {"data":["2222","3000","1111","1000"]}

The url listed above will return a full list of extensions in JSON format.

pbx_ip: The IP address or name of the Com.X PBX on the local network

Obtaining list of PIN codes

GET http://pbx_ip/commagui/control/pinlist

Response e.g. : {"data":["123","456","789"]}

The url listed above will return a full list of pin codes in JSON format.

pbx_ip: The IP address or name of the Com.X PBX on the local network

Enabling / Disabling Call Barring on individual extension

For testing purposes,use Google Chrome in conjunction with extension “Simple REST Client” or "Postman". This will provide you with the ability to perform very simple GET, POST, PUT and DELETE methods on a specified test URL.

HTTP Call barring is accomplished through a simple POST as follows:

POST http://pbx_ip /commagui/control/exts/ext_no/settings

{"displayName":"ext_no","barring":"value"}

Response: 200 – OK, 400 – Bad Request

In the URL listed above we are setting the 'barring' field based on the specified individual extension. The parameters highlighted in italics are explained below

pbx_ip: The IP address or name of the Com.X PBX on the local network

ext_no : The specified extension number

value: A boolean value which is either 'true' or 'false'

Example Usage 1:

POST http://192.168.0.173/commagui/control/exts/101/settings

{"displayName":"101","barring":"true"}

Returned: 200 - OK

The above URL will cause the 'barring' setting on extension number 101 to be set to 'true'. Now whenever extension 101 dials out it will be barred and an audible tone will

be played back to the user “access denied” . Note that internal calls (i.e. Extension to extension) will not be barred.

Enabling / Disabling Call Barring via Outbound Route PIN

Call barring can also be achieved by specifying a particular PIN code, as configured in PIN sets:

POST http://pbx_ip /commagui/control/pins/pin_no /settings

{"displayName":"pin_no","barring":"value"}

Response: 200 – OK, 400 – Bad Request

In the URL listed above we are setting the 'barring' field based on the specified

individual extension. The parameters highlighted in italics are explained below

pbx_ip: The IP address or name of the Com.X PBX on the local network

pin_no: The specified pin number

Value: A boolean value which is either 'true' or 'false'

Example Usage 1:

POST http://192.168.0.173/commagui/control/pins/1234/settings

{"displayName":"1234","barring":"true"}

Response; 200 – OK

The above URL will cause the 'barring' setting associated with pin '1234' to be set to 'true'. This pin will now be barred on any outbound route.

Changing the Extension Friendly Name / Display Name

POST http://pbx_ip /commagui/control/exts/ext_no/settings

{"displayName": " text "}

Response: 200 – OK, 400 – Bad Request

In the URL listed above we are setting the 'barring' field based on the specified

individual extension. The parameters highlighted in italics are explained below

pbx_ip: The IP address or name of the Com.X PBX on the local network

text: The specified friendly name

The displayed name or friendly name of a particular extension may need to be changed to suite the customers needs. To do this simply change the text field in the URL listed above to change the 'displayName' setting.

Example Usage 1:

POST http:// 192.168.0.173/commagui/control/exts/101/settings

{"displayName": " A.N Other Name ","barring":"true"}

Response: 200 - OK

The above URL will change the displayed name of that particular extension.

Checking settings on an individual extension

GET http://pbx_ip /commagui/control/exts/ext_no/settings

Response: {"displayName":"text","barring":"value"}

This is more generalised approach that will return all of an individual extension's settings in JSON format.

pbx_ip: The IP address or name of the Com.X PBX on the local network

text: The specified friendly name

Value: A boolean value which is either 'true' or 'false'

Checking settings on an individual PIN

GET http://pbx_ip /commagui/control/pins/pin _no/settings

Response: {"barring":"true"}

This is more generalised approach that will return all of an individual PIN's settings in JSON format.

pbx_ip: The IP address or name of the Com.X PBX on the local network

pin_no: The specified pin number

Get System Information

GET http://pbx_ip/commagui/control/sysinfo

Response: { “serialNumber”: “value”}

Will return the serial number of the system in JSON format.

pbx_ip: The IP address or name of the Com.X PBX on the local network

Value: Serial number requested