End-User URL Control API

From Taridium

Revision as of 17:37, 10 October 2009

This optional ipbx module is installed under Advanced Setup → Modules. Registered modules are displayed with registered module.

The URL control module allows you to control certain user settings via a simple URL. It also allows you to initiate a call (call origination) to your extension and bridge the call to any destination reachable within your default user settings (or custom extensions).

Do not expose this functionality on the public internet! If your server is reachable via a public IP address, make sure you take the appropriate precautions to prevent abuse.

Enabling URL Control

This assumes that you have the URL Control module installed. See Optional Modules

Log into the end user panel e.g. http://mypbx/user and enable URL Control under the Features section. Once enabled the system will automatically generate a 6 character key that identifies the user/extension. You can also, optionally specify an IP address that will identify the user/extension instead of the key.

Action Commands

Examples on how to use URL control:

Call Forwarding

• http://mypbx/user/c/?key=OB94AU&fwd=1 to switch call forwarding on
• http://mypbx/user/c/?key=OB94AU&fwd=0 to switch call forwarding off
• http://mypbx/user/c/?key=OB94AU&fwdnr=5550000 to set the call forwarding number to 555-0000 - This will automatically enable call forwarding.

Follow Me Toggle

• http://mypbx/user/c/?key=OB94AU&follow=1 to switch follow-me on
• http://mypbx/user/c/?key=OB94AU&follow=0 to switch follow-me off

Voicemail Toggle

• http://mypbx/user/c/?key=OB94AU&vm=1 to switch voicemail on
• http://mypbx/user/c/?key=OB94AU&vm=0 to switch voicemail off

Call Number (Click to Call)

• http://mypbx/user/c/?key=OB94AU&call=5550000 to call number 555-0000 - Numbers should be specified without spaces, dots, brackets etc. and in the same way as you would dial a number from an on-system phone.

If you specify an authorized client IP address you can omit the key argument. E.g. http://mypbx/user/c/?call=5550000

Caller ID Control (ipbx 2.0.5-g and higher)

Optionally specify an arbitrary caller ID for the second call leg using the cid parameter. You can either specify a number or a number and name:

 Number: 12345
 Name and Number John Doe <12345>

Please consider correct URL encoding of above examples:

 http://mypbx/user/c/?keyOB94AU&call=5550000&cid=John+Doe+%3C12345%3E

Return Values

Return values are simple text strings that reply with the result of the requested action. They can either start with the ERROR or OK keyword, followed by a short explanation.

Error Values

 ERROR: AUTHENTICATION FAILED

Returned if authentication fails (invalid key) or IP address cannot be matched.

 ERROR: FAILED PLACING CALL

Returned if the call could not be placed successfully. See also notes below on placed calls. The default timeout for first leg calls is 30 seconds.

Successful Values

 OK: UPDATED FORWARDING SETTINGS

The forwarding settings have been updated successfully.

 OK: UPDATED FOLLOWME SETTINGS

The followme settings have been updated successfully.

 OK: UPDATED VM SETTINGS  

The voicemail settings have been updated successfully.

 OK: CALL PLACED

The call has been placed successfully. Returned once the first leg of the call, to the user, has been placed successfully. Note this value will also be returned if the second leg of the call fails. The second leg call progress will be indicated on the phone of the caller.

HTML Output

URL Control can also return a simple HTML call progress page by setting the progress argument to 1. E.g. http://mypbx/user/c/?call=5550000&progress=1 - HTML output will pause until the successful/failed status is returned.

Successful Call

 » User 4002
 » Placing call to 4012...
 » Call completed!
 » Wait for party to pickup

Failed Call

 » User 4002
 » Placing call to 4012...
 » Call failed!

Generic Authentication

While URL Control can be used in an dedicated user context one can also use plain HTTP authentication to place arbitrary calls from any extension to another. This applies only to the call functionality and cannot be used for any other commands, since there is no specific user associated to the login. There is no need to use the key argument or come from a specific IP address. See Call Number (Click to Call).

The following system configuration variables are applicable:

 $cfg['IPPSUser'] // the variable that sets the username
 $cfg['IPPSPassword'] // the variable that sets the password
 $cfg['IPPSDPContext'] // optional dialplan (if not set inside will be used)

Example using URL Control with HTTP authentication:

 http://user:password@mypbx/user/c/?user=12345&call=5550000