Web Trigger Overview
Web Trigger is an alternative way to start a voice application. It allows establishing a call between an Visual Designer application and a destination address using a simple HTTP request. Any Visual Designer 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 Visual Designer.
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 Visual Designer variables by using HTTP parameters.
Control caller identifier that will be presented to the callee.
In the following example we will create a sample application that, when trigrred, will establish a call between aClient and the application and execute it.
Log into Visual Designer and create a new project named TestWebTrigger.
No need to change anything yet. If you don’t know what Visual Designer is and how to create an application please have a look at Visual Designer 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 yourinstance 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 youraccount credentials in order to authenticate. In this example we will use firstname.lastname@example.org / mypass.
Here is the cURL command to make the request:
$ curl -X GET --user 'email@example.com:mypass' '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:
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 tokensAPI credentials should be configured in Visual Designer settings. Visual Designer relies on 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 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 theaccount that will be used to create the call.
Set Username to theusername 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 Visual Designer 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
Visual Designer 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.
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!|