APIs

From Taridium

Latest revision as of 13:52, 14 December 2010

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.