APIs

From Taridium

(Difference between revisions)

Jump to: navigation, search

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.

APIs

From Taridium

Latest revision as of 13:52, 14 December 2010

Contents

ipbx APIs

Database API/ODBC

IPPS Interfaces

IPPS Authentication and SSL Access

IPPS Channel State Interface

HTTP GET Arguments and Polling

Returned Errors

Returned Fields

Sample Data

IPPS Queue Interface

Specific Configuration Variables

HTTP GET Arguments and Polling

Returned Errors

Returned Fields

Sample Data

CTI Integration

URL Control and Click to Call

Personal tools

Namespaces

Variants

Views

Actions

Search

Toolbox

@@ Line 1: / Line 1: @@
 == ipbx APIs ==
-ipbx offers a number of ways to interact programmatically with your phone system.
+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|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 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 ===
@@ Line 34: / Line 102: @@
 'restricted' no lookup will be performed.
+==== HTTP GET Arguments and Polling ====
-==== 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)
@@ Line 55: / Line 108: @@
 Queues Configuration.
-'''res_cc''' optionally can be set to 1 - whether to resolve country codes
+'''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://127.0.0.1/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
+   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
-microseconds (10 concurrent calls) on a 1GHz Intel Celeron processors, It is suggested
+milliseconds (10 concurrent calls) on 1GHz Intel Celeron processors, It is suggested
 to poll this dataset no more than every 3 seconds.
@@ Line 79: / Line 132: @@
    Only applicable if authentication username and/or password has been set
-==== Fields Supplied ====
+==== Returned Fields ====
 Data will only be returned if calls are active. Otherwise expect a 0 length page
@@ Line 87: / Line 140: @@
 '''UNIQUE_CALL_ID''': unique call ID assigned to call
-Always supplied
+''Always supplied''
 '''CALLER_ID''': if available the caller ID as passed by the telephone company
-Only supplied if available
+''Only supplied if available''
-'''COUNTRY_NAME''': only available if caller ID is availabel
+'''COUNTRY_NAME''': only available if caller ID is available and enabled via GET argument ''res_cc''
-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
+''Always supplied''
 '''ENTERED''': time when entered the call queue
-Always supplied
+''Always supplied''
 '''WAITED''': how long hold time was
-Only available if call has STATUS: CONNECTED
+''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
+SIP/592 - ''Only available if call has STATUS: CONNECTED''
 ==== Sample Data ====
@@ Line 120: / Line 171: @@
    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|CTI Module Section]].
+== URL Control and Click to Call ==
+See the [[End-User_URL_Control_API|URL Control Module Module Section]].