Web Trigger is an alternative way to start a voice application. It allows establishing a call between an RVD application and a destination address using a simple HTTP request. Any RVD Voice application can be configured to be started using Web Trigger. The process of doing that is roughly the following:

  • Create a Voice application in RVD.

  • Enable and configure Web Trigger feature for this application.

  • Start your application by making a request to the WebTrigger URL.

Other features of Web Trigger include:

  • Custom authentication using an application-specific token.

  • Initialization of RVD variables by using HTTP parameters.

  • Control caller identifier that will be presented to the callee.

Web Trigger relies on the Restcomm Calls REST API to do the actual work. You can find more information on how a call between an RCML application and a destination address is established at Restcomm API – Calls.

In the following example we will create a sample application that, when trigerred, will establish a call between a Restcomm Client and the application and execute it.

Step 1 - Create the Voice application
  • Log into RVD and create a new project named TestWebTrigger.

No need to change anything yet. If you don’t know what RVD is and how to create an application please have a look at RVD Basic Tasks first.

Step 2 - Enable Web Trigger

In the project menu, click on Web Trigger:

show_web_trigger_form

Then, check Enable Web Trigger:

web_trigger_enable

Step 3 - Register your SIP client

You will need a registered destination address to receive the triggered call. Fire up your favourite SIP client and register to your Restcomm instance as alice. Default password is 1234.

Step 4 - Trigger a call

Using your favorite REST client make a call to the WebTrigger URL. You can copy it from the configuration form:

copy_web_trigger_url

Before making the request you need to specify a destination for the call in the to parameter. You may use the client you just registered. The destination goes in the to parameter of the request:

http://this:8080/restcomm-rvd/services/apps/APdc8c1eea063d4a85b64a5bebda8e8c04/start?to=client:alice

Notice client: prefix in the to parameter.

Also, WebTrigger supports Basic HTTP authentication. Use your restcomm account credentials in order to authenticate. In this example we will use administrator@company.com / RestComm.

Here is the cURL command to make the request:

$ curl -X GET --user 'administrator@company.com:RestComm' 'http://this:8080/restcomm-rvd/services/apps/APdc8c1eea063d4a85b64a5bebda8e8c04/start?to=client:alice'

In addition to specifying the destination of the call, the caller ID may also be specified (optional) using the from parameter. Here is the how the trigger URL will look like when the caller ID is set to bob:

.../start?to=client:alice&from=bob

At this point you should be able to trigger a call to your registered client and listen to your application.

Authenticate with application-specific tokens

In case you don’t want to reveal your account credentials to the user of the trigger you can use an alternative form of authentication that relies on custom application-specific tokens. To enable it you will need to define an arbitrary security token in the configuration form and then use it in the request that will trigger the call. If the tokens match the request will be accepted.

Here is the configuration form with the application access token set to MyTopSeCrEt.

specify_application_access_token

Since there are no Basic HTTP authentication headers involved you may easily trigger the call by typing the WebTrigger URL directly in the browser:

http://this:8080/restcomm-rvd/services/apps/APdc8c1eea063d4a85b64a5bebda8e8c04/start?to=client:alice&token=MyTopSeCrEt
Before giving it a try make sure that you have configured Restcomm API credentials in RVD settings.
Call source and destination overrides

There can be cases when the destination or the source of a WebTrigger call should be locked down to a fixed value and not be controlled from the request. In order to do that overrides can be provided in the configuration form as follows:

source_dest_overrides

Now, the to and form parameters in the HTTP request will be ignored and values in the form will be used instead.

Configure Restcomm API access credentials

In order to use application-specific tokens Restcomm API credentials should be configured in RVD settings. RVD relies on Restcomm Calls REST API to create the actual call between the application and the destination address. For that, it needs to know the credentials of the Restcomm Account that will make the call.

To supply these credentials:

  • Click on the top right gear icon as illustrated bellow:

show_ide_settings_profile_form

This will bring up the IDE Settings form for the logged user:

ide_settings_profile_form_complete

Supply the credentials of the Restcomm account that will be used to create the call.

  • Set Username to the restcomm username on whose behalf the calls will be made. In this tutorial we used administrator@company.com

  • Set Password to the AuthToken of your account displayed in Dashboard.

Adding variables

Application behaviour can be further enhanced by adding parameters to your trigger URL. All additional parameters will be converted to RVD variables and can be used in your application.

Bellow is a personalized greeting of the application using firstname and lastname variables.

add_variables_to_the_mix

This application will use the firstname and lastname parameters from a trigger URL like the following:

http://this:8080/restcomm-rvd/services/apps/APdc8c1eea063d4a85b64a5bebda8e8c04/start?to=client:alice&firstname=nick&lastname=the+greek
Variable scope

In the example above firstname and lastname parameters defined in the url will result in creating module-scoped RVD variables. This means that the variables will be available only in the first module execution. To make them last for the whole application lifecycle the 'User parameter scope' option in Advanced configuration options should be set to Application as illustrated below.

application_scoped_variables

Destination address syntax

Throughout this tutorial we have only used client destinations for the call. Restcomm Calls REST API and consequently RVD WebTrigger support four different types of destination address. Any of these types can be used as a destination address. Here are some example values you can use as destinations either directly in the URL to parameter or as overrides in the configuration form.

  • client

    • client:alice

    • client:bob

  • sip

    • sip:bob@192.168.1.39:5060

  • conference

    • conference:2233

  • number

    • +1234598323

Make sure you url-encode these values if you specify the to destination in the trigger URL!