Action URL

Action URLs are essentially HTTP requests which are triggered by events. These URLs carry some action information (like a command and related parameters) within the URL, the headers and body to the receiving party which can then take action on it accordingly. For example, an event like “making a call” can trigger an action URL which informs a remote entity (say a billing system) that a call was made and also, who made the call to whom and for how long. Upon receiving the information, the billing system could log it for billing, for example.

The focus is on property management systems like hotel environments, but can also be used in other environments such as call centers and CRM Integration.

 

Outgoing Action URLs

The user can define almost any kind of HTTP request for each event. That way, the user is not tied to a specific protocol but can prepare messages (URLs, headers, body) based on the receiving system’s requirements by simply filling in the required message and using specific system variables to be filled in by the system.

    • Go to your selected domain in the PBX web interface.
    • Click on Action URL under Advanced as shown above.
    • Enter the Username and Password (if required) and the Address of Server of the system that will receive the action urls.
    • Press Save.

Configuring the Event Messages

Now that the credentials are saved, the user can prepare the action url messages triggered by the different events.

    • Click on the icon as shown, to expand the message settings for a specific event like: making a call, setting up wakeup call, clearing wakeup call, missing a wakeup call, setting dnd, clearing dnd, room cleaned, calling a set emergency number.

  • Enter the settings: Method, URL, Encoding, Additional Headers and Message Body according to the requirements of the receiving system for that event.
  • Use system variables in braces which will be filled in by the system. For example:
    • {address} : Replaced by the address of the remote system that the user entered in the Address of Server above.
    • {room}: Replaced by the extension that triggered the event e.g. the extension making the call etc.
    • {from}: Replaced by the “From:” field of a call.
    • {to}: Replaced by the “To:” field of a call.
    • {duration}: Replaced by the duration of a call.
    • {wakeuptime}: Replaced by the wakeup time (in 24 hour format) which has been set by the user through the phone using the wakeup service (*62) feature.
    • {emergencynumber}: Replaced by the set emergency number that was dialed.

    Note: To use braces {} within the message, like JSON example shown, use escape character \ like \{ or \} in order to distinguish it from system variables.

  • Repeat the same process for each event for which you want to create a specific message.
  • Press Save.
  • Now when a particular event is triggered, the corresponding http request – based on the method, url, encoding, headers and body values stored for that event – will be sent to the specified address.
  • That way, the receiving system, like a property management system, can act according to the message.

Note: The room cleaned event will be triggered when the room cleaned star code (which can be set on the Star Codes page of the domain, the default is *57) is dialed.

Incoming Action URLs

Incoming action urls are fixed. The command is in the URL and the body contains the parameters in JSON format.

To send an action url to the pbx:

Use the Method: PUT

URL: http://pbx.com/rest/domain/domain_name/room/extension_number/command

Body: It is in JSON format and depends on the command.

 

Action URLs for Specific Commands

checkin

For checkin into a hotel for example, this command can setup the extension (room) in the PBX according to the guest. It can setup the guest’s name, email, a dial plan can be chosen to allow/disallow outgoing calls, setup credit for calls, resync or reboot the phone etc.

    • Method: PUT
    • URL: http://pbx.com/rest/domain/domain_name/room/extension_number/checkin

Explanation: pbx.com is the address of the PBX. The domain_name is the name of the domain where the phone is registered, the extension_number is the extension of the phone in the room for the guest and checkin is the command.

Example: http://pbx.company.com/rest/domain/pbx.company.com/room/455/checkin

    • Body: { “parameters” : [ { “name” : “param1_name”, “value” : “param1_value” }, { “name” : “param2_name”, “value” : “param2_value” } ] }

Explanation: The body is in JSON format. If the body contains a predefined parameter as shown, the PBX will set the value of that parameter for that specific extension number given in the URL. It is an array of name, value pairs. The name gives the parameter name to change and the value gives what it should be set to.

Example: { “parameters” : [ { “name” : “name”, “value” : “last,first” }, { “name”:”email”, “value” : “abc@company.com” }, { “name”:”dialplan”, “value” : “allow trunk calls” }, { “name”:”credit”, “value” : “50” }, { “name”:”check-sync;reboot=true”, “value” : “” } ] }

That will checkin and set all the values given: name is the guest’s name (last name then comma then first name), email, dialplan (for example setting it to allow trunk calls or not), credit is amount for outgoing calls, and check-sync;reboot=true will reboot the phone to represent the new values. The phone can also be re-synched without reboot with reboot=false.

It is not necessary to give all the parameters during checkin. As explained above, only the parameters present will be set. Say, you only want to set the name, email and dialplan on checkin and nothing else, then just include those parameters.

checkout

This command will reset the extension (room) in the PBX. It also allows you to set some specific parameters after the reset, like: dialplan, resync or reboot the phone etc.

    • Method: PUT
    • URL: http://pbx.com/rest/domain/domain_name/room/extension_number/checkout

Explanation: pbx.com is the address of the PBX. The domain_name is the name of the domain where the phone is registered, the extension_number is the extension of the phone in the room for the guest and checkout is the command.

Example: http://pbx.company.com/rest/domain/pbx.company.com/room/455/checkout

This will reset the extension 455. No message body necessary in the message. The name, email address etc. will be removed.

    • However, If you do want to set some parameters along with checkout, like dialplan or re-sync the phone, you can include those parameters in the body of the message along with the checkout command, just like with checkin command shown above.
    • Body: { “parameters” : [ { “name” : “param1_name”, “value” : “param1_value” }, { “name” : “param2_name”, “value” : “param2_value” } ] }

Example: { “parameters” : [{ “name”:”dialplan”, “value” : “disallow trunk calls” }, { “name”:”check-sync;reboot=true”, “value” : “” } ] }

setdnd

This command will turn on the DND of the extension (room) in the PBX.

    • Method: PUT
    • URL: http://pbx.com/rest/domain/domain_name/room/extension_number/setdnd

Example: http://pbx.company.com/rest/domain/pbx.company.com/room/455/setdnd

  • No message body necessary in the message.

cleardnd

This command will turn off the DND of the extension (room) in the PBX.

    • Method: PUT
    • URL: http://pbx.com/rest/domain/domain_name/room/extension_number/cleardnd

Example: http://pbx.company.com/rest/domain/pbx.company.com/room/455/cleardnd

  • No message body necessary in the message.

setwakeup

This command will set the wakeup service of the extension (room) in the PBX and set the wakeup time. The PBX will make a wakeup call to the extension on the set time.

    • Method: PUT
    • URL: http://pbx.com/rest/domain/domain_name/room/extension_number/setwakeup

Example: http://pbx.company.com/rest/domain/pbx.company.com/room/455/setwakeup

    • Body: { “wakeuptime” : “14:32”}

Explanation: The wakeup time is given in the 24 hour format. That is when the extension will be called for wakeup service.

clearwakeup

This command will clear the wakeup service of the extension (room) in the PBX.

    • Method: PUT
    • URL: http://pbx.com/rest/domain/domain_name/room/extension_number/clearwakeup

Example: http://pbx.company.com/rest/domain/pbx.company.com/room/455/clearwakeup

  • No message body necessary in the message.