APIs
From Taridium
Contents |
ipbx APIs
ipbx offers a number of ways to interact programmatically with your phone system.
Database API/ODBC
Please contact Taridium for a complete database documentation.
IPPS Interfaces
IPPS allows applications to interact with ipbx using simple URLs.
IPPS Queue Interface
The IPPS queue interface provides a HTTP(S) data source that lists all active queue calls and optionally attempts to resolve the country code prefix to the country's name.
Specific Configuration Variables
$cfg['DomesticNumberMaxLen'] maximum length for numbers considered local/domestic
$cfg['DefaultCountryID'] default country ID/Name when ['DomesticNumberMaxLen'] is reached
Notes on country name resolution
If a caller ID is available and the minimum length for international caller IDs is not reached the system will default to a pre-set country name. Country name resolution is expected to work on a 'best effort' basis, since Caller ID data passed by telephone carrier is often incomplete or non-existent. If the information is non-numeric. E.g. 'unknown', 'private' or 'restricted' no lookup will be performed.
Authentication and SSL access
if any of the following variables are set, you will need to send HTTP authentication:
$cfg['IPPSUser'] string - IPPS username as set in config
$cfg['IPPSPassword'] string - IPPS password as set in config
$cfg['IPPSRequireSSL'] boolean - TRUE or FALSE - whether to enforce HTTPS protocol
HTTP Get arguments and polling
queue_name name of queue(s) (comma separated if merged results requested) This is the literal name of the call queue as specified in the ipbx Queues Configuration.
res_cc optionally can be set to 1 - whether to resolve country codes
Example HTTP Requests:
http://213.156.130.88/ipps/queueactive.php?queue_name=MC&res_cc=1 http://myuser:pass@213.156.130.88/ipps/queueactive.php?queue_name=MC&res_cc=1
NOTE: Although page render times have been established at levels below 30 microseconds (10 concurrent calls) on a 1GHz Intel Celeron processors, It is suggested to poll this dataset no more than every 3 seconds.
Returned Errors
Currently only the following errors will be returned:
ERROR: NO QUEUE NAME SUPPLIED If no queue name is supplied
ERROR: SSL QUERY REQUIRED Only applicable if $cfg['IPPSRequireSSL'] has been set to TRUE
ERROR: AUTHENTICATION FAILED Only applicable if authentication username and/or password has been set
Fields Supplied
Data will only be returned if calls are active. Otherwise expect a 0 length page body. Every line of the page body represents a call in the selected queue. Data is returned as comma separated values. Some values are optional or depend on call status or other information.
UNIQUE_CALL_ID: unique call ID assigned to call Always supplied
CALLER_ID: if available the caller ID as passed by the telephone company Only supplied if available
COUNTRY_NAME: only available if caller ID is availabel Only supplied if available via CALLER_ID and match and enabled via GET argument res_cc
STATUS: can be one of the following: WAITING or CONNECTED Always supplied
ENTERED: time when entered the call queue Always supplied
WAITED: how long hold time was Only available if call has STATUS: CONNECTED
AGENT: SIP or IAX2 channel that is handling the call. Channel data has the format of TECHNOLOGY/CHANNEL_NAME. Most commonly this would look something like this: SIP/592 - Only available if call has STATUS: CONNECTED
Sample Data
1236606951.132,99532356420,Georgia,WAITING,09:55:51,, 1236606991.135,99532356420,Georgia,CONNECTED,09:56:31,3,SIP/4002 1236607029.138,448450043606,United Kingdom,CONNECTED,09:57:10,1,SIP/4002 1236607156.144,792074279,Switzerland,CONNECTED,09:59:16,2,SIP/4002 1236607198.147,444557400,Switzerland,WAITING,09:59:59,, 1236607198.147,444557400,Switzerland,CONNECTED,09:59:59,6,SIP/4002 1236607246.150,688677809010,Tuvalu,CONNECTED,10:00:46,2,SIP/4002 1236607333.153,6596489564,Singapore,CONNECTED,10:02:13,2,SIP/4002 1236607363.156,12124611807,North America and Caribbean,CONNECTED,10:02:43,1,SIP/4002
