© 2013 Plum Group, Inc. All rights reserved.
The subdialog question type allows you to insert custom VoiceXML into your phone surveys, enabling you to process data as it is entered into a survey and respond with customized prompts. You can also use it to insert more complex automated dialogue in the middle of your phone survey.
Knowledge of VoiceXML is required to utilize the subdialog type. The Plum Survey phone component runs on a Plum-hosted VoiceXML platform. For a full reference of VoiceXML as related to Plum Voice's platform, as well as a tutorial to get you started in coding in VoiceXML, please see our Plum d.e.v. documentation.
For a walk-through of how to use this question type, see Section 2.19 of the Survey Design tutorial.
All answers received so far on the current page, along with their corresponding question texts, are POST'ed to the subdialog URL along with the ANI (caller ID) of the respondent. The variables are in the format of answers_0, answers_1, answers_2 ... and question_texts_0, question_texts_1, question_texts_2..., and finally ani. The encoding type for the POST request will be multipart/form-data, because some of the answers may consist of recorded audio files with a Internet media type of audio/basic; these are 8 kHz, 8-bit mu-law-encoded headerless WAV files that the web server hosting your subdialog may choose to save and process.
The subdialog you provide should return one variable called result, which will be stored as a string value for the question's answer.
When adding this question, the default value is the URL for our sample subdialog. This sample subdialog performs a simple operation on the data it receives: it adds up the number of "yes" answers, speaks this value in a prompt, and then returns this number back to the survey as its result.
We are providing the code for our sample subdialog so that you can have a reference implementation to build your own. If you are using PHP, the following code could easily serve as a template for your own subdialog; just replace the code that handles the incoming $_POST variables. For other languages and architectures, any script that outputs valid VoiceXML that returns a result in response to an HTTP POST will work. A static VoiceXML file can also serve as a subdialog.
UPDATE (7/01/09): An advanced question option for Advanced Skip Logic has been added to the subdialog type, the details of which can be found in Section 6.4 of the Survey Design Tutorial.
<subdialog> in the survey calling a subdialog at http://survey.plumvoice.com/ws/sample-subdialog.php
<!-- Plum Survey VoiceXML for your survey... -->
<form>
<var name="answers_0" expr="'yes'"/>
<var name="question_texts_0" expr="'Are you satisfied with your service?'"/>
<var name="answers_1" expr="'no'"/>
<var name="question_texts_1" expr="'Was this your first visit?'"/>
<var name="answers_2" expr="'yes'"/>
<var name="question_texts_2" expr="'Did you find everything you needed?'"/>
<var name="answers_3" expr="'yes'"/>
<var name="question_texts_3" expr="'Would you return to our store?'"/>
<var name="ani" expr="'6177123000'"/>
<subdialog name="sub" src="http://survey.plumvoice.com/ws/sample-subdialog.php" namelist="ani answers_0
answers_1 answers_2 answers_3 question_texts_0 question_texts_1 question_texts_2 question_texts_3"
method="post" enctype="multipart/form-data"/>
<block>
<!-- we save sub.result to your response data -->
</block>
</form>
<!-- Our VoiceXML for your survey continues... -->
<return> from sample subdialog back to the survey
<var name="result" expr="'3'"/>
<return namelist="result"/>HTTP Request generated by the survey's <subdialog> element to the sample subdialog at http://survey.plumvoice.com/ws/sample-subdialog.php
POST /ws/sample-subdialog.php HTTP/1.1
Host: survey.plumvoice.com
User-Agent: curl/7.10.6 (i686-redhat-linux-gnu) libcurl/7.10.6 OpenSSL/0.9.7a ipv6 zlib/1.1.4
Pragma: no-cache
Content-Length: 962
Content-Type: multipart/form-data; boundary=----------------------------79cdb4241583
------------------------------79cdb4241583
Content-Disposition: form-data; name="answers_0"
yes
------------------------------79cdb4241583
Content-Disposition: form-data; name="question_texts_0"
Are you satisfied with your service?
------------------------------79cdb4241583
Content-Disposition: form-data; name="answers_1"
no
------------------------------79cdb4241583
Content-Disposition: form-data; name="question_texts_1"
Was this your first visit?
------------------------------79cdb4241583
Content-Disposition: form-data; name="answers_2"
yes
------------------------------79cdb4241583
Content-Disposition: form-data; name="question_texts_2"
Did you find everything you needed?
------------------------------79cdb4241583
Content-Disposition: form-data; name="answers_3"
yes
------------------------------79cdb4241583
Content-Disposition: form-data; name="question_texts_3"
Would you return to our store?
------------------------------79cdb4241583--HTTP Response generated for the sample subdialog's <return> back to the survey
HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 23:50:16 GMT
Server: Apache/1.3.34 (Unix) PHP/5.2.0 mod_ssl/2.8.25 OpenSSL/0.9.7a
X-Powered-By: PHP/5.2.0
Transfer-Encoding: chunked
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
SURVEY APP SAMPLE SUBDIALOG
This is a sample subdialog for use with a 'subdialog (phone only)' question in a survey.
(c) 2008 Plum Voice
-->
<vxml version="2.0">
<form>
<block>
<prompt>
You answered... yes... to <value expr="'3'"/> questions on this page.
</prompt>
<var name="result" expr="'3'"/>
<return namelist="result"/>
</block>
</form>
</vxml>sample-subdialog.php:
<?php
/*************
* SURVEY APP SAMPLE SUBDIALOG
* This script demonstrates how to make a subdialog for use with a 'subdialog (phone only)' question in a survey.
* (c) 2013 Plum Voice
*************/
header("Content-type: text/xml");
echo("<?xml version=\"1.0\"?" . ">\n");
$yescount = 0;
foreach($_POST as $postname=>$postvalue) {
if (substr($postname, 0, 8) == "answers_") {
if ($postvalue == "yes") { $yescount++; }
}
}
?>
<!--
SURVEY APP SAMPLE SUBDIALOG
This is a sample subdialog for use with a 'subdialog (phone only)' question in a survey.
(c) 2013 Plum Voice
-->
<vxml version="2.0">
<form>
<block>
<prompt>
You answered... yes... to <value expr="'<?= $yescount ?>'"/> questions on this page.
</prompt>
<var name="result" expr="'<?= $yescount ?>'"/>
<return namelist="result"/>
</block>
</form>
</vxml>