Subdialog Integration

The subdialog question type allows users to add custom VoiceXML to their surveys.

Data Transmission

When encountering a subdialog question, data is submitted as multipart/form-data to the subdialog URL. The data submitted includes the following:

Required

Type

Name

Description

Yes

string

ani

ANI of the caller taking the survey

Yes

string

dns

DNIS the caller called to reach the survey

Yes

string

lang

Language code for the language in which the call is being taken

Yes

string

session_id

Unique id for the session of the caller taking the survey

Yes

string

questions

JSON encoded, zero-indexed array of question text from the survey. The question and answer arrays are parallel arrays.

Yes

string

answers

JSON encoded, zero-indexed array of question answers from the call session. The question and answer arrays are parallel arrays.

No

file

__comment_{some_id}

WAV files of any recorded comments via the comment question type

Note: When a file is present in the POST data, users will see 'file://__comment_{some_id}' stored in the answers JSON array. To access this file in the subdialog question, users need to use that name set to save the file from the $_FILES array, or their language equivalent.

Handling Audio Files

When a subdialog question type is placed after a comment question type on a phone survey, the recorded comment is submitted to the subdialog question type as expected. To process the audio file, users first need to detect the audio file. To accomplish this, review the answers array for answers that match the format 'file://__comment_{some_id}'. When encountering an answer in this format, check the $_FILES array, or the language equivalent, to locate the uploaded file and process it accordingly.

Per-Page Data Submission

For other questions to send data to a subdialog question, those questions must be on the same page as the subdialog question. For example, if a survey has 5 questions on one page and the next page contains the sudbialog question, then those 5 questions will not be included in the data posted to the subdialog. This is important to keep in mind when designing surveys to ensure that subdialog questions are placed properly.

Subdialog Response

By default, if the subdialog does not return any data, then the answer for the subdialog question is stored as an empty value. To return a value to be stored as the answer to the subdialog question, this can be done by returning a single variable named 'result'.

The following subdialog sample returns 'it worked' as a single variable, which is saved as the answer for the subdialog question.

<?xml version="1.0"?>
<vxml version="2.0">
<form>
<block>
<var name="result" expr="'it worked'"/>
<return namelist="result"/>
</block>
</form>
</vxml>