Web Service Module

This module lets VoiceGuide communicate with HTTP and HTTPS Web Services.

Following request types can be used:

  • DELETE
  • GET
  • POST
  • PUT
  • UPDATE

Module supports setting of:

  • URL Address
  • Authentication 
  • Post Data
  • Headers

 

 

After issuing the request to the Web Service, VoiceGuide can:

  • Continue, without waiting for web service query to complete.
  • Wait until web service query completes.
  • Wait until web service query and sound file completes.

Continue, without waiting for web service to complete :
VoiceGuide will immediately continue down the "Success" path once the web service query was started successfully. If web service query could not be started successfully then the "Fail' path is taken. If the path that VoiceGuide should be following is not defined then VoiceGuide will hang up the call.

Wait until web service query completes :
VoiceGuide will wait until the web service query completes. Any sound files still playing when the web service query completes will be stopped.

Wait until web service and sound file completes :
VoiceGuide will wait until the web service completes and until the sound file playing completes.

 

Limiting maximum execution time

To limit the length of time the system waits for the web service to return, a Timeout Path should be defined. If the web service does not return before the timeout occurs the web service query will be terminated and the timeout path will be taken. The timeout value is in seconds and should be set to a value of 1 or higher.

 

Play Tab

If "Wait Until Web Service Completes" option is selected, the sound file specified in the Play tab will be played while the web service query is performed.

 

Using Result Variables

Before running the web service VoiceGuide will first see if there are any Result Variables specified within the web service's HTTP address (URI), Post Data, Headers etc. and if present then VoiceGuide will first replace them with their current values.

If the Result Variable is not defined then VoiceGuide will replace it with an empty string.

If after replacing the Result Variables in Data ad/or Headers the outcome points to a valid file then the contents of that file will be read in, any $RVs within that read in file contents replaced, and that result will then be used as the Data and/or Header for that Web Service interaction.

 

Returned Result Variables

Data retuned by Web Service is saved in Result Variables and made available for use throughout remainder of the call. The Result Variables created will depend upon the Web Service used, and whether data is returned in XML or JSON format, etc. Created $RVs will not all be saved in the Script's Log, so it is recommended to look at VoiceGide's vgEngine log (in VoiceGuide'S \log\ subdirectory) to establish what $RVs are created when a particular web service is called.

The following $RVs are always created:

$RV[ModuleTitle_Result_Code]
Returned Status code

$RV[ModuleTitle_Result_Desc]
Returned Status description

$RV[ModuleTitle_Result_Data]
Returned Data (all data returned, unparsed)

The Headers of the returned response are also saved as Result Variables. Again, please consult VoiceGide's vgEngine log (in VoiceGuide'S \log\ subdirectory) to establish what $RVs are createdwhen a particular web service is called.

 

Paths

The following are valid path options:

  • Success/Fail
  • HTTP Response Codes
  • Timeout

eg: The following HTTP Response Code paths are all valid:

on {200} goto [Say all went OK]
on {OK} goto [Say all went OK]
on {406} goto [Say trans not accepted]
on {Not Acceptable} goto [Say trans not accepted]

 

Script Examples

Sample script excerpts are provided in VoiceGuide's \Scripts\Web Service\ subdirectory. Script provided there demonstrate the use of the various HTTP request methods from within the VoiceGuide Web Service module.

 

Example : GET Request : Get Weather by ZIP code

Cdyne Corp. provides a web service that can be used to retrieve weather information at a particular ZIP code. The Web service can be called using the a HTTP GET request to the following URI:

http://wsf.cdyne.com/WeatherWS/Weather.asmx/GetCityWeatherByZIP?ZIP=[zip code]

eg:

http://wsf.cdyne.com/WeatherWS/Weather.asmx/GetCityWeatherByZIP?ZIP=10005

The response to this HTTP GET request is:

<?xml version="1.0" encoding="utf-8" ?>
<WeatherReturn xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ws.cdyne.com/WeatherWS/">
<Success>true</Success>
<ResponseText>City Found</ResponseText>
<State>NY</State>
<City>New York</City>
<WeatherStationCity>White Plains</WeatherStationCity>
<WeatherID>4</WeatherID>
<Description>Sunny</Description>
<Temperature>46</Temperature>
<RelativeHumidity>17</RelativeHumidity>
<Wind>NW16G26</Wind>
<Pressure>30.20F</Pressure>
<Visibility />
<WindChill />
<Remarks />
</WeatherReturn>

The following Result Variables would be created by VoiceGuide for this response:

$RV[Success] - "true"
$RV[ResponseText] - "City Found"
$RV[State] - "NY"
$RV[City] - "New York"
$RV[WeatherStationCity] - "White Plains"
$RV[WeatherID] - "4"
$RV[Description] - "Sunny"
$RV[Temperature] - "46"
$RV[RelativeHumidity] - "17"
$RV[Wind] - "NW16G26"
$RV[Pressure] - "30.20F"
$RV[Visibility] - ""
$RV[WindChill] - ""
$RV[Remarks] - ""

The above Result Variables can then be used for the remainder of the call.

 

Example : POST Request : Add Ticket to Zendesk

Zendesk (http://www.zendesk.com/) provides a HTTP REST API.

Following example shows show VoiceGuide's Web Service module can be used to add a new ticket to your Zendesk account:

NB. this POST request will require authentication, and hence would require that your own Zendesk account is set up first. The URL would need to be modified accordingly.

 

Example : POST Request to ASMX Web Service

Issuing a SOAP 1.2 POST request to an ASMX Web Service:

Then SOAP XML structures to use is displayed when the Web Services' ASXM URL is viewed in a web browser.

Most ASMX Web Services support SOAP 1.2 format. Issuing a SOAP 1.1 format POST request is only slightly different:

 

Password Security

If passwords need to be used to access the web service, it is recommended that entire VoiceGuide script is saved as a Protected Script.
This way the passwords will be encrypted and not readable unless the VoiceGuide script password is known.