Getting Started

Overview

In essence, the Rivr Dialogue Engine (lets just call it Rivr from now on, shall we), is a simple Java library which abstract 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 distant platform in a synchronous fashion way (continuations), 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.

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 happen 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 lets see some of such code:

    MDC.put(DIALOG_ID_MDC_KEY, context.getDialogueId());

    mDialogLog.info("Starting dialogue");

    JsonObjectBuilder resultObjectBuilder = JsonUtils.createObjectBuilder();
    try {
        InteractionBuilder interactionBuilder = new InteractionBuilder("hello");
        interactionBuilder.addPrompt(new SynthesisText("Hello World!"));
        InteractionTurn turn = interactionBuilder.build();
        VoiceXmlInputTurn inputTurn = DialogueUtils.doTurn(context, turn);
        if (VoiceXmlEvent.hasEvent(VoiceXmlEvent.CONNECTION_DISCONNECT_HANGUP, inputTurn.getEvents()))
            throw new HangUp();
        if (VoiceXmlEvent.hasEvent(VoiceXmlEvent.ERROR, inputTurn.getEvents()))
            throw new PlatformError(inputTurn.getEvents().get(0).getMessage());
    } catch (InterruptedException exception) {
        Thread.currentThread().interrupt();
    } catch (Exception exception) {
        mDialogLog.error("Error during dialogue", exception);
        JsonUtils.add(resultObjectBuilder, CAUSE_PROPERTY, ResultUtils.toJson(exception));
    }

    VariableDeclarationList variables = VariableDeclarationList.create(resultObjectBuilder.build());
    mDialogLog.info("Ending dialogue");

    return new VoiceXmlExitTurn("result", variables);

This snippet features a full-fledged hello world application. Not much but it is a start that we hope will be truly enlightening to you, Java developer.

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.1</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