Web Trigger is an alternative way to start a voice application over HTTP. 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 through Web Trigger. The process of doing that is roughly the following:

  • Create the Voice application in RVD.

  • Enable and configure Web Trigger feature for this application.

  • Configure Restcomm REST API access for the logged user in RVD.

Other features of Web Trigger include:

  • Secure your trigger using a custom token.

  • Provide additional HTTP parameters that are available as RVD application variables.

  • Set the 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 will establish a call between a Restcomm Client and an 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

  • Check Enable Web Trigger:

enable_web_trigger

Step 3 - Register your SIP client

You will need a 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 - Configure Web Trigger

Back to RVD, after enabling Web Trigger in Step 2 complete the configuration form so that it looks as follows:

web_trigger_form_completed

  • Fill To with client:alice. This should be the same as the client you registered to Restcomm in Step 3.

  • Fill From with 1234. This is the arbitrary caller id that will appear to Alice when she receives the call.

  • Fill Access token with ToPsEcReT. This is a secret token that will protect your Web Trigger from malicious users. Though RVD won’t require this field it’s VERY IMPORTANT to provide it.

  • Notice the suggested Web Trigger URL on the top of the form. We will use that on Step 6 - Build trigger URL.

If a warning about Restcomm API credentials appears at the bottom of the form the additional Step 5 is needed. link:[]

Step 5 - Provide credentials for Restcomm API access (once per operating user)

If you’ve already done this for the logged user you may skip this step.

As already noted, RVD relies on Restcomm Calls REST API to create the actual call between the application and the destination address. For that, RVD needs to know the credentials of the Restcomm Account that will make the call. In order 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. Typing the username and password you use to log into RVD will do.

  • Set Username to administrator@company.com

  • Set Password to whatever password you have set

* As of Restcomm 7.5.0 these credentials need to be configured separately for each different user that operates RVD. For older versions, an RVD-wide approach was used that posed various security issues and was abandoned.

Step 6 - Build trigger URL

You will now need to build the URL that will initiate the Web Trigger. The generic form of this URL is the following: http://HOST:PORT/restcomm-rvd/services/apps/APPLICATION_NAME/start?token=ACCESS_TOKEN

  • HOST and PORT depend on how you have set up and access restcomm.

  • APPLICATION_NAME is the name of the RVD application. In this case that would be TestWebTrigger. You will need to url-encode the name in case it contains any special characters like spaces etc.

  • ACCESS_TOKEN is the Access token specified in Step 4. In this case it would be ToPsEcReT.

RVD will also try to build the URL automatically. You may copy it from Web Trigger Configuration form in Step 4. It’s right under Web Trigger URL field.

Here is the URL used for this example:

Step 7 - Trigger the call

Everything has been set up. Time to test the trigger.

  • Using your web browser or your favourite HTTP client  make a GET request to the URL you built in Step 6. Your SIP client should ring!

  • Notice the caller ID in the incoming call. It should be set to 1234. That’s the From value we specified in Step 4.

  • Pick up the call. You should now hear the application and the typical RVD greeting: "Welcome to Telestax Restcom Visual Designer Demo".

Adding variables to the mix

Application behaviour can be further enhanced by adding parameters to your trigger URL and use them in your application. We will now personalize the greeting by passing caller firstname and lastname parameters.

  • Modify your TestWebTrigger project so that it looks as follows:

add_variables_to_the_mix

  • Modify the trigger URL by adding firstname and lastname custom parameters. It should look like the following:http://RESTCOMM_HOSTNAME:PORT/restcomm-rvd/services/apps/TestWebTrigger/start?token=ToPsEcReT&firstname=foo&lastname=bar

RVD will detect these additional parameters and create variables using the same name.

  • Point your web browser or  your HTTP client to the url above.

Your SIP phone should ring. Pick it up. You should now hear the personalized greeting: "Hello foo bar. Welcome to Telestax Restcom Visual Designer Demo !"

Override destination of the call

You can explicitly specify the destination of the call by adding the special to parameter to your URL. This won’t create an RVD variable but will change the destination of the call instead.

Bob should now receive the call.

Note on destinations

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 to parameters in the URL (or specify in Step 4 To field) for each of these types:

  • 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!
HTTP Basic Authentication

As of Restcomm version 7.7.0 support for HTTP Basic authentication has been added to WebTrigger. The mechanism works as an alternative to custom token authentication. In order to take advantage of it you’ll just have to provide your restcomm account credentials as an HTTP Authorization header.

Example

credentials

_administrator@company.com:RestComm

URL

http://RESTCOMM_HOSTNAME:PORT/restcomm-rvd/services/apps/TestWebTrigger/start

Headers

Authorization: Basic YWRtaW5pc3RyYXRvckBjb21wYW55LmNvbTpSZXN0Q29tbQ==
  • Note that there is no token URL parameter

  • You don’t need to supply the Access Token field in the WebTrigger form discribed in Step 4. In fact, you can have this field empty to disable token authentication.

  • You don’t need to supply credentials for Restcomm API access as decribed in Step 5. Skip this step.