APIs

From Taridium

Contents 1 ipbx APIs 2 Database API/ODBC 3 IPPS Interfaces 3.1 IPPS Authentication and SSL Access 3.2 IPPS Channel State Interface 3.3 IPPS Queue Interface 3.3.1 Specific Configuration Variables 3.3.2 HTTP Get arguments and polling 3.3.3 Returned Errors 3.3.4 Fields Supplied 3.3.5 Sample Data 4 CTI Integration

ipbx APIs

ipbx offers a number of ways to interact programmatically with your phone system. If you are looking at basic computer telephony integration, for example with a 3rd party CRM application, check the CTI Module pages.

Database API/ODBC

Please contact Taridium for a complete database documentation.

IPPS Interfaces

IPPS allows applications to interact with ipbx using simple URLs.

IPPS Authentication and SSL Access

if any of the following system variables are set, you will need to send basic HTTP authentication to perform queries against the IPPS interfaces:

 $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

IPPS Channel State Interface

The IPPS channel state interface provides a HTTP(S) data source that lists requested channel states.

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.

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 and indicates 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 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 available 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

CTI Integration

See the CTI Module Section.