Getting Started

Overview

In essence, the Rivr Dialogue Engine (lets just call it Rivr from now on, shall we), is a simple Java library that abstracts the usual back and forth associated with client-server architecture such as one involving VoiceXML application development. The library is composed of two distinct layers: core and voicexml.

Core

Rivr core is where the magic happens. It provides low-level and rudimentary elements to have applications interact with a remote platform in a synchronous fashion way (like in continuation-based web servers), so that you, as a developer, can focus on your code instead of other surrounding distractions.

The engine itself is based on a single concept: turns. Output and Input turns are essentially interactions from a user and browser perspective respectively. More concretely, an output turn represents what the underlying platform executes (play prompts, collect digits or speech, etc.), while an input turn represents the result of the user interacting with the application (collected digits, speech recognition N-best results, events, etc.).

VoiceXML Driver

How are turns or interactions rendered depend solely on, what we call, the driver. For now, Rivr offers a driver for VoiceXML but nothing stops you to go ahead and write your own driver to interact with some other telephony/IVR platforms. Asterisk FastAGI? Twilio? Tropo? CCXML? Why not!

With Rivr, your dialogue not only happens to execute within its own thread, simplifying the development in the process, but also, moves away from the more traditional MVC paradigm. Hence, no session to manage, no template to deal with, and drastic gain in productivity.

As someone on the Rivr team likes to put it,

It's just code!

Hello World

Now let see some code:

try {
    // Play a prompt
    Message message = new Message("message", new SpeechSynthesis("Hello World!"));
    VoiceXmlInputTurn inputTurn = DialogueUtils.doTurn(message, context);

    // Handling hangup or error events
    List<VoiceXmlEvent> events = inputTurn.getEvents();
    if (events.isEmpty()) {
        status = "Normal";
    } else if (hasEvent(CONNECTION_DISCONNECT_HANGUP, events)) {
        status = "HangUp";
    } else if (hasEvent(ERROR, events)) {
        status = "PlatformError";
        VoiceXmlEvent errorEvent = getEvent(ERROR, events);
        resultObjectBuilder.add("eventName", errorEvent.getName());
        resultObjectBuilder.add("eventMessage", errorEvent.getMessage());
    } else {
        status = "Unknown";
    }
} catch (InterruptedException exception) {
    Thread.currentThread().interrupt();
    status = "Interrupted";
} catch (Throwable throwable) {
    status = "SystemError";
    context.getLogger().error("Error during dialogue execution", throwable);
    resultObjectBuilder.add("error", ResultUtils.toJson(throwable));
}

resultObjectBuilder.add("status", status);
VariableList variables = VariableList.create(resultObjectBuilder.build());

return new Exit("result", variables);

This snippet shows a full-fledged hello world application. Lines 3 and 4 are where the magic happens. Line 3 creates a message (an output turn), while line 4 executes it and returns an input turn. (Of course, there is a certain amount of boilerplate code, but every serious application needs some, right?)

Getting Rivr

As an open-source project, Rivr is published on Maven Central and available through the following dependency:

<dependencies>
    <dependency>
        <groupId>com.nuecho</groupId>
        <artifactId>rivr-voicexml</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

You can also pick the jar files from Rivr releases section on GitHub.

Bootstrapping your First Application

The following example comes from the Rivr cookbook

Before you begin, you'll need:

• Java JDK
• A VoiceXML Platform to execute your VoiceXML on
• A Servlet container such as Tomcat, Jetty, or JBoss, to host the Rivr application

First, clone our hello-world from the Rivr cookbook:

git clone -b hello-world https://github.com/nuecho/rivr-cookbook.git rivr-cookbook-hello-world

or download directly the archive

Then create a web application archive (war):

cd rivr-cookbook-hello-world

Then, on Unix:

./gradlew war

or on Windows:

gradlew.bat war

Once you have a war (build/libs), you're free to deploy that web application over any Servlet container.

On a cloud platform such as Heroku

heroku deploy:war --war <path_to_war_file> --app <app_name> 

Then, simply point your VoiceXML browser to this newly deployed VoiceXML application, assign a DID or extension, and off you go.

You can easily do so on Voxeo Evolution.

Go ahead and try it:

tel:+1-202-540-0982
skype:+990009369990097522
sip:9990097522@sip.voxeo.net