> For the complete documentation index, see [llms.txt](https://docs.plumvoice.com/insight/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plumvoice.com/insight/data-integration/subdialog-integration.md).

# 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                                                                |

{% hint style="info" %}
**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.
{% endhint %}

### **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.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.plumvoice.com/insight/data-integration/subdialog-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.