DTMF recognition options

This example shows how to tune DTMF recognition. The parameters describe here are explained in detail in the VoiceXML specification, Section 6.3.3 and Appendix D - Timing Properties / DTMF Grammar

Let's start by having a grammar accepting a DTMF string between 5 and 10 digits long.

Dialogue.java:

GrammarItem dtmfGrammar = new GrammarReference("builtin:dtmf/digits?minlength=5&maxlength=10");
DtmfRecognition dtmfRecognition = new DtmfRecognition(dtmfGrammar);

Now let's configure the inter-digit time-out, i.e. the maximum pause duration between the input of two consecutive digits before the input is considered finished.

Dialogue.java:

dtmfRecognition.setInterDigitTimeout(Duration.seconds(2));

Another option you can configure is the DTMF term char, i.e. the DMTF key the caller can press in order to terminate the input. This is the DTMF equivalent of the Enter key. So the user can press the DTMF term char once the input is done, not having to wait for the inter-digit time-out.

Dialogue.java:

dtmfRecognition.setTermChar("*");

The last parameter is term time-out, i.e. the time given to enter the term char once when no other character can be accepted (in our exemple, after the 10th digit). The idea is to put a value for term time-out that is shorter than inter-digit time-out value.

Dialogue.java:

dtmfRecognition.setTermTimeout(Duration.milliseconds(800));

The DtmfRecognition can now be used to build the Interaction. Note that the time-out specify here (2 seconds) is the no-input time-out (or simply timeout in the VoiceXML terminology):

Dialogue.java:

Interaction interaction = interaction("get-dtmf")
        .addPrompt(new SpeechSynthesis("Type a number between 5 and 10 digits long."))
        .build(dtmfRecognition, Duration.seconds(5));

You can then perform the DTMF recognition by executing the turn:

Dialogue.java:

VoiceXmlInputTurn inputTurn = DialogueUtils.doTurn(interaction, context);

Logger logger = context.getLogger();
if (inputTurn.getRecognitionInfo() != null) {
    JsonArray recognitionResult = inputTurn.getRecognitionInfo().getRecognitionResult();
    //Extracting the "interpretation" of the first recognition hypothesis. 
    String number = recognitionResult.getJsonObject(0).getString("interpretation");
    logger.info("Number entered: " + number);
} else if (VoiceXmlEvent.hasEvent(VoiceXmlEvent.NO_INPUT, inputTurn.getEvents())) {
    logger.info("Timeout.");
} else if (VoiceXmlEvent.hasEvent(VoiceXmlEvent.NO_MATCH, inputTurn.getEvents())) {
    logger.info("No-match.");
}

---

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 dtmf-options 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.