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

Anatomy of a Rivr Application