APIs
From Taridium
Contents |
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. For security reasons IPPS is disabled by default. In order to enable IPPS, you need to to set the variable $cfg['IPPSEnabled'] to TRUE.
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.
HTTP GET Arguments and Polling
channel name of channel(s) (comma separated if merged results requested) This is the technology and the literal name of the channel as specified in the ipbx configuration.
useid force reply of channel name as first field in returned data
Example HTTP Requests:
http://127.0.0.1/ipps/channelinfo.php?channel=SIP/4003 http://myuser:pass@127.0.0.1/ipps/channelinfo.php?channel=SIP/4003,SIP/5011
Returned Errors
The following errors will be returned:
ERROR: NO CHANNEL SUPPLIED
If no channel 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
Returned Fields
Data will only be returned if calls are active. Otherwise expect either the channel name and/or the keyword down, depending on whether the useid GET argument has been set. Every line of the page body represents a channel. Data is returned as comma separated values. Some values are optional or depend on call status or other information.
CHANNEL_NAME: The supplied channel name in the format of Technology/Resource. This value is always returned if you are querying multiple channels and if the useid GET argument is set to 1.
CHANNEL_STATE: The status of the channel. This will always be returned and have any one of the following values: down, up, ring (caller channel) and ringing (callee channel).
CHANNEL_CLID_NUMBER: The caller ID number of the calling channel.
CHANNEL_CLID_NAME: The caller ID name of the calling channel.
CHANNEL_ACCOUNT_CODE: The account code for the current channel/call.
CHANNEL_UNIQUE_ID: The unique ID of the current call.
Sample Data
SIP/4002,down,,,, SIP/5011,ring,5007,John McManx,5007@default,1267042128.359
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://127.0.0.1/ipps/queueactive.php?queue_name=MC&res_cc=1 http://myuser:pass@127.0.0.1/ipps/queueactive.php?queue_name=MC&res_cc=1
NOTE: Although page render times have been established at levels below 30 milliseconds (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
Returned Fields
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.
URL Control and Click to Call
See the URL Control Module Module Section.
