Web Trigger Overview
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 ../api/calls-api.adoc#calls.
In the following example we will create a sample application that, when trigrred, will establish a call between a Restcomm Client and the application and execute it.
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.
In the project menu, click on Web Trigger:
Then, check Enable Web Trigger:
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.
Using your favorite REST client make a call to the WebTrigger URL. You can copy it from the configuration form:
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:
Notice client: prefix in the
Also, WebTrigger supports Basic HTTP authentication. Use your restcomm account credentials in order to authenticate. In this example we will use firstname.lastname@example.org / RestComm.
Here is the cURL command to make the request:
$ curl -X GET --user 'email@example.com:RestComm' 'http://this:8080/visual-designer/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
from parameter. Here is the how the trigger URL will look like when the caller ID is set to bob:
At this point you should be able to trigger a call to your registered client and listen to your application.
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.
Since there are no Basic HTTP authentication headers involved you may easily trigger the call by typing the WebTrigger URL directly in the browser:
|Before giving it a try make sure that you have configured Restcomm API credentials in RVD settings.|
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:
form parameters in the HTTP request will be ignored and values in the form
will be used instead.
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:
This will bring up the IDE Settings form for the logged user:
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 firstname.lastname@example.org
Set Password to the AuthToken of your account displayed in Dashboard.
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
This application will use the firstname and lastname parameters from a trigger URL like the following:
In the example above
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.
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.
|Make sure you url-encode these values if you specify the to destination in the trigger URL!|