Scripting

Scripting can be performed within the survey to extract details and send SMS messages.

Request Parameters

Scripting can be used within an SMS survey to extract for example respondent details. Request parameters available to survey script include:

• SMS_CLI - will find the respondent mobile number.
• SMS_InitialReply - if the survey is initiated with an initial reply (the respondent starts the survey by providing the answer to the first question), then this will find the reply.

For example:

Request["SMS_InitialReply"];

If the survey was started with shop 1234, then the method call will return 1234.

• SMS_SenderId – the SenderId (long number or short code) that the respondent sent the SMS message to. This can be used for example in a SendSMS script as the “from” parameter to force the SendSMS script extension to use the SMS provider associated with the SenderId when sending the SMS message. See the example below.

Sending an SMS Message from Within a Survey

You can trigger an SMS to be sent from a script within any survey where the SMS extension is enabled, even when the respondent is responding through a different channel. This is done through the PostRequest method:

var ext = Extension("SmsSurveyScript");
ext.PostRequest("SendSMS", p, ms);

where p is a Hastable with to (SMS recipient number), from (one of the Sender IDs configured for the company) and text (SMS text), and ms is the expiry time for the call from the survey script to the extension in milliseconds, defining the maximum time the survey script will wait for a reply from the Extension. The SMS will be sent via the SMS provider matching the Sender ID in from.

Below is an example of a SendSMS function using the PostRequest method and the Request parameters described above to trigger an SMS to be sent from a script in an SMS survey:

function SendSMS()
__{
____var ext = Extension("SmsSurveyScript");
____if(ext.IsValid)
____{
______var p = new Hashtable();
______p["to"] = Request["SMS_CLI"];
______p["from"] = Request["SMS_SenderId"];
______p["text"] = "hello world";
______var result = ext.PostRequest("SendSMS", p, 8000);
______if(result.IsValid)
______{
   ________return result["Status"];
______}
______return "Result is invalid";
____}
____return "Extension script name is invalid";
}

The capability to send SMS messages from within a survey can be very useful for example in a panel registration survey where you would like an extra step for the respondent to confirm their identity. You could ask for the respondent's mobile number, and send a pin code to their mobile and only accept registrations where the respondent types in the correct pin code.The procedure to do this is:

Assuming you have an account with one of the supported providers, and the provider is configured:

1. Enable the SMS survey extension on the survey.
2. Insert three open text questions; one for the generated precode ("pincode" – hidden), one for the mobile phone number ("phone"), and one for the respondent to type in the pincode ("verifypin").

Figure 1 - The questions added to enable verification of identity

1. In the "phone" question, insert the following script in the validation code (replace "XXXXXXXXXXXX" with the sender phone number of your SMS provider:

//Set pin code
var pin : String;
pin = Math.floor(Math.random()*10).toString()+
Math.floor(Math.random()*10).toString()+
Math.floor(Math.random()*10).toString()+
Math.floor(Math.random()*10).toString();
f("pincode").set(pin);

//Send pin code in email

var ext = Extension("SmsSurveyScript");
if(ext.IsValid)

__{
___var p = new Hashtable();
___p["to"] = f("phone");
___p["from"] = "XXXXXXXXXXXX";
___p["text"] = "Pin code; "+f("pincode");
___var result = ext.PostRequest("SendSMS", p, 8000);
___if(!result.IsValid)
____{
_____RaiseError();
_____SetQuestionErrorMessage(LangIDs.en,"SMS Sending failed.");
____}
__}
__else
__{
___RaiseError();
___SetQuestionErrorMessage(LangIDs.en,"SMS Sending failed. Extension script name is invalid");
}

1. In the "verifypin" question, insert the following script in the validation code to verify that the supplied pin matches the one sent in the SMS:

if(f("pincode").get()!=f("verifypin").get())
__{
___RaiseError();
___SetQuestionErrorMessage(LangIDs.en,"Invalid pin code.");
__}