Implementing a subdialogue

To implement a subdialogue is not different from implementing a normal dialogue except that it must end with the <return> VoiceXML element instead of <exit>, <disconnect>. To generate a <return>, our dialogue simply need to return a Return. The return can either return named values (JavaScript values) or a VoiceXML event.

Our dialogue ask for two numbers:

Dialogue.java:

try {
    int number1 = askNumber(context);
    int number2 = askNumber(context);

To return those numbers as well as their sum, we prepare a VariableList:

Dialogue.java:

VariableList returnValues = new VariableList();
returnValues.addWithExpression("number1", String.valueOf(number1));
returnValues.addWithExpression("number2", String.valueOf(number2));
returnValues.addWithExpression("sum", String.valueOf(number1 + number2));

We need to be careful with variable declarations. Here, since we have numbers, we don't quote the values. The caller will receive JavaScript numbers, not strings. The resulting VoiceXML will be something like:

    <var name="number1" expr="12" />
    <var name="number2" expr="10" />
    <var name="sum" expr="22" />

We can now pass the VariableList in the Return:

Dialogue.java:

//return the values
return new Return("return", returnValues);

We also show here how to return an event by using the other constructor. Event name is passed in the second parameter and message (optional) is passed in the third parameter:

Dialogue.java:

} catch (Exception exception) {
    //return an event
    return new Return("return", "rivr.cookbook.error", exception.getMessage());
}

Here's a sample VoiceXML document invoking the subdialogue:

main.vxml:

<?xml version="1.0" encoding="UTF-8"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">

  <form id="test">
    <subdialog name="twoNumbers" src="dialogue">
      <filled>
        <prompt>
          First number is
          <value expr="twoNumbers.number1" />
          , second number is
          <value expr="twoNumbers.number2" />
          and their sum is
          <value expr="twoNumbers.sum" />
          .
        </prompt>
      </filled>
    </subdialog>
  </form>
</vxml>

To try the example, the VoiceXML platform initial URL should be http://<yourhostname>:8080/rivr-cookbook/main.vxml

---

Running this example

You can download or browse the complete code for this example at GitHub.This is a complete working application that you can build and run for yourself.

You can also clone the Rivr Cookbook repository and checkout this example:

git clone -b subdialogue-implementation git@github.com:nuecho/rivr-cookbook.git

Then, to build and run it:

cd rivr-cookbook

./gradlew jettyRun

The VoiceXML dialogue should be available at http://localhost:8080/rivr-cookbook/dialogue

To stop the application, press Control-C in the console.