APIs

From Taridium

Revision as of 02:06, 8 December 2009 by Webmaster (Talk | contribs)
Jump to: navigation, search

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
Personal tools
Namespaces
Variants
Actions
Toolbox