APIs (Application Programming Interfaces) are like a set of rules and protocols that allow different software programs to talk to each other and share data or functionality. Think of it like ordering food at a restaurant. You look at a menu (the API) that lists what is available, and when you place an order (make a request), the kitchen prepares your meal (the response) based on what you asked for.
APIs on PBXware are used for data delivery to users, enable users to interact with options and manipulate data within the PBXware.
Authentication with PBXware is achieved with API key, which can be set in Admin Settings → API Keys → Add New API Key. ‘Master Key’ comes by default, has all the permissions and cannot be deleted. New API key can be randomly generated or manually set to have minimum 10 random characters.
Steps to configure API key can be found on this link.
PBXware API uses GET and POST requests through HTTP protocol.
GET request is used to request data from the PBXware
POST request is used to send data to a server to create/update a resource
Responses to API requests can come in two different formats:
JSON – more compact and easier to read for humans
PHP – serialized response
By default, responses come in JSON format, although it can be specified with an argument apiformat.
APIs could be executed in different ways, but the most basic ones are:
CLI (Command Line Interface) with commands like curl, httpie
Application, such as Postman
Browser
CLI:
Postman:
Browser:
The primary argument that controls the API is the action argument. This argument is composed of three parts, which are separated by dots: application.object.method.
Application will always default to pbxware.
Example request format:
http://ip_address/?apikey=api_key&server=server_id&id=ext_id&action=application.object.method
ip_address - IP of the system you would like to request data from
api_key - API key created at PBXware → Admin Settings → API Keys
server_id - ID of the server/tenant
ext_id - ID of the extension
Following picture represents application.object.method. For every single object there is a list of specific methods that can be used, which can be found at PBXware → Admin Settings → API Keys → Documentation
Please note that IP, API key and action are required for request to be valid, while other keys are optional.
Examples:
Change values accordingly to create a successful API request.
Tenants list:
http://ip_address//?apikey=api_key&action=pbxware.tenant.list
Tenant add:
http://ip_address//?apikey=api_key&action=pbxware.tenant.add&tenant_name=API_test&tenant_code=777&package=1&ext_length=3&country=135&national=1&international=011
• package: Desired package for Tenant to use
• country: Country in which the PBXware system is located (for example: 135 - Bosnia and Herzegovina)
• national: National dialing code used to initialize calls in the same country
• international: International dialing code used to initiate international calls
All of the used keys are required for tenant to be added, others are optional.
Extensions list:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.ext.list
Extension add:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.ext.add&name=API_test&[email protected]&location=2&ua=50&status=1&pin=0000&incominglimit=1&outgoinglimit=1&voicemail=1&prot=sip&secret=TestTest1234!!
• location: 1 - Local; 2 - Remote
• ua: UAD used for the extension (for example: Generic SIP - 50; Yealink T41s - 196; Grandstream GRP2614 - 318 etc.)
• status: 1 - Active; 2 - Not Active
• incominglimit & outgoinglimit: set under Extensions Call Control options, how many simultaneous incoming/outgoing calls are allowed
• voicemail: 1 - Enabled; 0 - Disabled
• prot: SIP or IAX
All of the used keys are required for extension to be added, others are optional.
Extensions online:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.dashboard.ext_online
Disk usage:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.dashboard.disk_usage
CPU usage:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.dashboard.cpu
Memory usage:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.dashboard.memory
Downloading CDRs:
http://ip_address//?server=server_id&apikey=api_key&action=pbxware.cdr.download&start=start_date&end=end_date
‘Recording path’ can be obtained through this API call, which would serve further for call recordings download from the remote storage, since they cannot be downloaded from PBXware. However, Archiving must be set on Tenant in order for data to be retrievable via API call.
Enhanced Services
Each of Extensions Enhanced Services can be used to check its configuration or to edit it.
Read:
Caller ID:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.callerid.configuration
callerid can be changed to any of the Enhanced Services available.
Call Filters:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.callfilters.configuration
Do Not Disturb:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.dnd.configuration
Call Forwarding:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.callfwd.configuration
Directory / BLF List:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.blflist.configuration
Operation Times:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.extoperationtimes.configuration
Edit:
Caller ID:
http://ip_address//?server=server_id&id=ext_id&apikey=api_key&action=pbxware.ext.es.callerid.edit&callerid=7871&emergencycid=999&trunks=CCV5:MTv5&tcallerids=7777:8888&tprivacies=4:4&anums=0000:1111&alabels=Test:API&acodes=1:2
callerid: System/Network CallerID
emergencyid: Emergency CallerID
trunks: Name of the trunk for each CallerID
tcallerids: Desired CallerID for each trunk
tprivacies: Privacy set for CallerID (0 → anonymous, 1 → anonymous_id, 2 → anonymous_number, 3 → anonymous_number_id, 4 → none)
anums: Allowed list of CallerIDs
alabels: Labels for Allowed list of CallerIDs
acodes: Short Codes for Allowed list of CallerIDs
trunks and tcallerids; anums and alabels must match in size or error will be returned.
Additional information:
server & id values can be pulled from URL when positioned at the specific tenant/extension.
ua value is located when positioned on the desired UAD page on PBXware at URL.
package value can be obtained from URL when positioned on desired package, or via API call like:
http://ip_address//?apikey=api_key&action=pbxware.package.list
country value can be found at URL on Routes page when selected desired Country, or using API to fetch the value like:
http://ip_address//?apikey=api_key&action=pbxware.route.list
