End-User URL Control API
From Taridium
(→Generic Authentication) |
(→Generic HTTP Authentication) |
||
| (30 intermediate revisions not shown) | |||
| Line 1: | Line 1: | ||
This optional ipbx module is installed under '''Advanced Setup''' → '''Modules'''. Registered modules are displayed with '''registered module'''. | 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). | + | 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). Three types of authentication are available depending on your application: |
| - | [[Image:warning.gif]] 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. | + | # Key based authentication (user associated) |
| + | # IP address based authentication (user associated) | ||
| + | # Generic HTTP authentication (click to call only) | ||
| + | |||
| + | |||
| + | {| align="center" style="text-align:center; width:500px; border: 1px solid #CFCFCF; padding:3px;" | ||
| + | |[[Image:warning.gif]] 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. | ||
| + | |} | ||
| Line 17: | Line 24: | ||
=== Call Forwarding === | === Call Forwarding === | ||
| + | |||
| + | Call Forwarding allows you to enable and disable call forwarding for the authenticated extension. Note that is is only applicable if there is a forwarding destination configured. All forwarding settings as configured in the [[End User Panel]] are applicable. | ||
| + | |||
* http://mypbx/user/c/?key=OB94AU&fwd=1 to switch call forwarding on | * 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&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 | + | * 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 === | === Follow Me Toggle === | ||
| + | |||
| + | Follow Me Toggle allows you to enable and disable follow me for the authenticated extension. Note that is is only applicable if there is at least one follow me destination configured. All follow me settings as configured in the [[End User Panel]] are applicable. | ||
| + | |||
* http://mypbx/user/c/?key=OB94AU&follow=1 to switch follow-me on | * 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 | * http://mypbx/user/c/?key=OB94AU&follow=0 to switch follow-me off | ||
| + | |||
=== Voicemail Toggle === | === Voicemail Toggle === | ||
| + | |||
| + | Voicemail Toggle allows you to enable and disable the voicemail box for the authenticated extension. All voicemail settings as configured in the [[End User Panel]] are applicable. | ||
| + | |||
* http://mypbx/user/c/?key=OB94AU&vm=1 to switch voicemail on | * http://mypbx/user/c/?key=OB94AU&vm=1 to switch voicemail on | ||
* http://mypbx/user/c/?key=OB94AU&vm=0 to switch voicemail off | * http://mypbx/user/c/?key=OB94AU&vm=0 to switch voicemail off | ||
| + | |||
=== Call Number (Click to Call) === | === 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. | + | * Example: 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 | 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==== | |
| - | + | ''available as of ipbx 2.0.5-g and higher'' | |
| - | Number: 12345 | + | 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: |
| - | Name and Number John Doe <12345> | + | |
| + | Number: ''12345'' | ||
| + | Name and Number: ''John Doe <12345>'' | ||
| + | |||
| + | If you want the call to appear as ''unknown'' to the called party, simply set the '''cid''' variable to ''unknown''. Note that the first call leg caller ID will be the number to be dialed. | ||
Please consider correct URL encoding of above examples: | Please consider correct URL encoding of above examples: | ||
http://mypbx/user/c/?keyOB94AU&call=5550000&cid=John+Doe+%3C12345%3E | http://mypbx/user/c/?keyOB94AU&call=5550000&cid=John+Doe+%3C12345%3E | ||
| + | |||
| + | Further click to call settings can be configured under [[Advanced_Setup:_Configuration#Click_to_Call|Advanced Setup]]. | ||
== Return Values == | == Return Values == | ||
| Line 70: | Line 95: | ||
=== HTML Output === | === 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. | + | URL Control can also return a simple HTML call progress page by setting the '''progress''' argument to '''1''' (text) or '''2''' (graphic). E.g. http://mypbx/user/c/?call=5550000&progress=1 - HTML output will pause until the successful/failed status is returned. |
'''Successful Call''' | '''Successful Call''' | ||
| Line 85: | Line 110: | ||
» Call failed! | » Call failed! | ||
| - | == Generic Authentication == | + | == Generic HTTP Authentication == |
| - | While URL Control can be used in | + | While URL Control can be used in a 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/authentication. There is no need to use the '''key''' argument or come from a specific IP address. See [[End-User_URL_Control#Call_Number_.28Click_to_Call.29|Call Number (Click to Call)]] for details on IP address based authentication. |
| + | |||
| + | {| align="center" style="text-align:center; width:500px; background-color:#FDCBCB; border:none; padding:3px;" | ||
| + | |Do not under any circumstances use these URLs directly in your publicly exposed web pages. A simple HTML analysis could allow a hacker to bridge two arbitrary phone lines. | ||
| + | |} | ||
The following system configuration variables are applicable: | The following system configuration variables are applicable: | ||
| + | $cfg['IPPSEnabled'] // set this variable to TRUE to use HTTP authentication | ||
$cfg['IPPSUser'] // the variable that sets the username | $cfg['IPPSUser'] // the variable that sets the username | ||
$cfg['IPPSPassword'] // the variable that sets the password | $cfg['IPPSPassword'] // the variable that sets the password | ||
| - | $cfg['IPPSDPContext'] // optional dialplan (if not set '''inside''' will be used) | + | $cfg['IPPSDPContext'] // optional dialplan context where the extension should be looked up (if not set '''inside''' will be used) |
Example using URL Control with HTTP authentication: | Example using URL Control with HTTP authentication: | ||
http://user:password@mypbx/user/c/?user=12345&call=5550000 | http://user:password@mypbx/user/c/?user=12345&call=5550000 | ||
| + | |||
| + | When using Generic HTTP Authentication the '''context''' variable can be passed for a custom dialplan context. This will default to '''inside''' or to the value set for $cfg['IPPSDPContext']. If required the '''user''' parameter can also be specified as channel such as user=SIP/4002 instead of an extension. | ||
Latest revision as of 14:10, 12 March 2012
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). Three types of authentication are available depending on your application:
- Key based authentication (user associated)
- IP address based authentication (user associated)
- Generic HTTP authentication (click to call only)
 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.
|
Contents |
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
Call Forwarding allows you to enable and disable call forwarding for the authenticated extension. Note that is is only applicable if there is a forwarding destination configured. All forwarding settings as configured in the End User Panel are applicable.
- 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
Follow Me Toggle allows you to enable and disable follow me for the authenticated extension. Note that is is only applicable if there is at least one follow me destination configured. All follow me settings as configured in the End User Panel are applicable.
- 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
Voicemail Toggle allows you to enable and disable the voicemail box for the authenticated extension. All voicemail settings as configured in the End User Panel are applicable.
- 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)
- Example: 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
available as of 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>
If you want the call to appear as unknown to the called party, simply set the cid variable to unknown. Note that the first call leg caller ID will be the number to be dialed.
Please consider correct URL encoding of above examples:
http://mypbx/user/c/?keyOB94AU&call=5550000&cid=John+Doe+%3C12345%3E
Further click to call settings can be configured under Advanced Setup.
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 (text) or 2 (graphic). 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 HTTP Authentication
While URL Control can be used in a 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/authentication. There is no need to use the key argument or come from a specific IP address. See Call Number (Click to Call) for details on IP address based authentication.
| Do not under any circumstances use these URLs directly in your publicly exposed web pages. A simple HTML analysis could allow a hacker to bridge two arbitrary phone lines. |
The following system configuration variables are applicable:
$cfg['IPPSEnabled'] // set this variable to TRUE to use HTTP authentication $cfg['IPPSUser'] // the variable that sets the username $cfg['IPPSPassword'] // the variable that sets the password $cfg['IPPSDPContext'] // optional dialplan context where the extension should be looked up (if not set inside will be used)
Example using URL Control with HTTP authentication:
http://user:password@mypbx/user/c/?user=12345&call=5550000
When using Generic HTTP Authentication the context variable can be passed for a custom dialplan context. This will default to inside or to the value set for $cfg['IPPSDPContext']. If required the user parameter can also be specified as channel such as user=SIP/4002 instead of an extension.
