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:

    1.     // The dialog termination cause. "Normal" by default.
    2.     JsonValue cause = wrap("Normal");
    3.    
    4.    try {
    5.        // Play a prompt
    6.        InteractionTurn turn = newInteractionBuilder("hello").addPrompt(new SynthesisText("Hello World!")).build();
    7.        VoiceXmlInputTurn inputTurn = DialogueUtils.doTurn(context, turn);
    8.      
    9.        // Handling hangup or error events
    10.      if (hasEvent(CONNECTION_DISCONNECT_HANGUP, inputTurn.getEvents()))
    11.          cause = wrap("Hangup");
    12.      if (hasEvent(ERROR, inputTurn.getEvents()))
    13.          cause = wrap(inputTurn.getEvents().get(0).getMessage());
    14.   } catch (InterruptedException exception) {
    15.      Thread.currentThread().interrupt();
    16.       cause = wrap("Interrupted");
    17.   } catch (Exception exception) {
    18.       cause = ResultUtils.toJson(exception);
    19.   }
    20. 
    21.   // Build the JSON result returned to the calling application/context.
    22.   JsonObjectBuilder resultObjectBuilder = JsonUtils.createObjectBuilder();
    23.   resultObjectBuilder.add(CAUSE_PROPERTY, cause);
    24.   VariableDeclarationList variables = VariableDeclarationList.create(resultObjectBuilder.build());
    25. 
    26.   return new VoiceXmlExitTurn("result", variables);

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

The whole source code (with logging instructions) is available in a separate repository.

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>0.9.0</version>
    </dependency>
</dependencies>

Bootstrapping your First Application

Before you begin, you'll need:

• A VoiceXML Browser to execute your VoiceXML on
• A Servlet container such as Tomcat, Jetty, or JBoss, to serve the Rivr application

First, clone (or fork) our hello-world sample application:

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

Then create a web application archive (war):

cd rivr-hello-world
./gradlew 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