What does Rivr buy me? Part 2

The previous post explored some benefits regarding the use of Rivr, the Java VoiceXML API. Let’s continue to look at more of these advantages.

More compact representation of dialogue

With proper method extraction, your dialogue can look compact and simple. You can get the overview of the whole dialogue such as:

public VoiceXmlLastTurn run(VoiceXmlFirstTurn firstTurn,
                            VoiceXmlDialogueContext context) {

    Credentials credentials = askUserCredentials(context);
    if (!authenticateUser(credentials)) {
        return new Exit("exit-unauthorized");

    Operation operation = askTypeOfOperation(context);
    transferToAgent(context, operation);

    return new Exit("exit-success");

You can drill-down in any method to get more details. Any IDE will let you do this easily:

Credentials askUserCredentials(DialogueContext context) {
    String accountNumber = askAccountNumber(context);
    String pin = askPin(context);
    return new Credentials(accountNumber, pin);

This gives you a feel of how you could organize you code and your dialogue.

Supports revision control system, parallel development

Since Java source files can be put in source control, as well as other dialogue-related resources such as grammars and prompts, everything can be put into a revision control system such as Git, Mercurial or Subversion. Developers can thus work in parallel and because they understand the syntax of the artifacts they manipulate, they can resolve a merge conflict, something not feasible in the diagram world.

Better integration with business logic

Graphical tools offer various pre-packaged back-end interface facilities (Database requests, SOAP request, XML HTTP request, etc). The problem is that they are limited and not flexible enough. For instance, authentication mechanisms can be lacking, you may be forced to specify a WSDL location which may not exist in your development environment or you may not be able to stub your back-end. Moreover, you may already have your back-end client library available in Java making the provided back-end access node totally irrelevant, just adding more noise to the project.

With Rivr, it’s easy to create a back-end abstraction and have regular and stub implementations. This is how things are typically done in Java and this makes the integration seamless. Everything is still done in Java. No need to add anything else.

Support for automated test suites

Automated dialogue testing is one of the most interesting feature of Rivr. While in normal mode the dialogue is driven by a servlet, where InputTurn are created based on the VoiceXML platform responses, testing can be done by providing some test cases acting as provider of InputTurn, thus simulating inputs of the caller and the VoiceXML platform. The Rivr Cookbook shows an example where JUnit is used to perform a complete coverage test of the callflow. This is a very powerful tool helping increasing application quality and making the application more resilient.

Better debugging facilities

With Rivr, you debug the application as a whole. You simply place breakpoints in the Java code. You can thus trace problems at different levels: interaction details, callflow logic, back-end logic. Debugging dialogues with unit tests is another typical way to find the cause of a problem.

Rivr also dumps every interaction details (OutputTurns and InputTurns) into a Java-side logger. So you no longer need to look at logs on different servers to figure out what’s happening.

Java developer friendly

Rivr allows Java developers to be more efficient. They don’t spend their time trying to layout diagrams (auto-layout doesn’t work, right?) or trying to circumvent a limitation in the GUI. They simply code the callflow. Rivr is a more natural way to implement callflows for a Java developer than any other approach.

The fact that Rivr is a Java library makes it easier for new developers to join IVR development projects. No need to learn a complex tool, the API is something that can be picked up rapidly.

Lower risks in development projects and maintenance

Rivr is just a library, it isn’t a design-time tool. You are less likely to break your currently working application by integrating a new version of Rivr than by upgrading your new IVR graphical tool to the latest version. Besides, you can always compile and run your applications against older versions of Rivr if it works correctly. By comparison, upgrading a graphical tool is a “can’t-go-back” decision.

Rivr helps reduce the project’s risks by starting development immediately. No need to wait for the VoiceXML platform to be ready of the tools to be deployed on developer workstations.

Rivr isn’t in your way

Rivr is designed for a focused task: development and execution of VoiceXML dialogues. There is no decision made for you as how you should connect to your enterprise back-end, how alarms are triggered, how applications should be packaged or how it should be deployed across your different environments.

Rivr doesn’t impose any convention of any kind. You are free to organize your project structure as you see fit.


Rivr is an elegant and powerful solution for VoiceXML IVR development, bringing benefits to the developers as well as the organization. To find out more about Rivr, you can take a look at the Java API documentation or read the Getting Started article. Rivr also has a discussion group which is open for everybody, feel free to join and ask questions.

What does Rivr buy me? Part 1

In the previous post, we’ve given you an overview of how Rivr works. We’ve seen that in order to realize an IVR dialogue, the developer simply needs to exchange various turns objects through the Rivr API.

Whether you are a Java IVR developer, a Java architect or a technical decision-maker, you should consider the following benefits of using Rivr:

Smooth learning curve

Learning Rivr is easy. You can begin by running a working example from the Rivr Cookbook. When compared to VoiceXML, Rivr has a smaller number of concepts. You can gradually explore features by looking at other examples and explore the API.

Simple tool set

Rivr only requires you to have 2 jar files. You probably already have your Java IDE and that’s all you need to develop your IVR application with Rivr. Since Rivr artifacts are pure Java code, you already have the tools for debugging, documenting, testing, reviewing, storing, sharing, packaging, verifying, building and refactoring. Rivr leverages all your Java tools and practice.

Vendor lock-in avoidance / portability

If you are unsure about a long-term commitment towards a VoiceXML vendor, Rivr can ease the switch to another platform. Since, as opposed to some graphical environments, the generated VoiceXML doesn’t target a specific VoiceXML platform, developing your IVR applications with Rivr is a strategy to protect your investment. Nevertheless, Rivr allows you to exploit any platform-specific extension if they need to be used. If you use any platform-specific extension, migrating to another platform only means finding another way to achieve the same result with the new platform.


A Rivr dialogue is just a regular Java method in which the developer performs calls on the dialogue channel in order to interact with the VoiceXML platform. To make a fully functioning application, you only need to write one single Java class, create a web.xml as you would do for any web application and your are ready to go. An application can thus be as small as required. By contrast, approaches where projects are generated from a graphical tool can make the simplest project huge and any newcomer can easily get lost in this jungle of generated (and mostly unused) artifacts, not being able to distinguish what parts are provided by the tool and what parts are application-specific.

Simplicity can also be observed at run-time. If you need to take a look at them, the generated VoiceXML documents are actually easy to understand. Since Rivr generates small focused VoiceXML documents, it’s easy to figure out what happens when the application runs. Each time an event occurs, it is sent back to the application. So you don’t need to figure out what has happened on the VoiceXML platform since the dialogue logic is implemented on the Java side. Most of the time, a simple look at the logs is enough to explain the observed behaviour.

Power and flexibility

Rivr comes with a predefined set of OutputTurns: speech-recognition and DTMF interactions, recording, call transfers (blind, consultation, bridge), subdialogue calls, messages (using audio files or speech synthesis) and client-side Javascript execution. With these primitive actions, you can do virtually everything you could do if you were authoring VoiceXML documents directly. If for some reason you wish to add other primitives to this built-in palette, Rivr allows it. Simply create a new class for an OutputTurn and specify how VoiceXML should be generated for this kind of turn. It is also possible to subclass an existing turn and tweak the VoiceXML generation. If you want to add proprietary extensions of your VoiceXML platform, you can use those customization mechanisms. So you can’t really get trapped; there is always a way to code your way out.

Better abstractions

Since everything is done on the Java side, it is much easier to create abstractions. For example, you can make an abstract base class for some kind of dialogue and add specific implementations which share a common dialogue logic. This illustrates that you can reuse your OOP skills in dialogue design.

Another idea: create a method that takes two dialogues as input: a collection dialogue and a confirmation dialogue. The method will invoke the collection dialogue and will then call the confirmation dialogue if necessary. This is dialogue composition. Think of all abstractions mechanisms in Java and use them in the design of your dialogues.

Better modularity and reusability

Dialogues can be placed in various methods within various classes. Reusable parts of the dialogue can be extracted into methods (static or not, as you like). The only constraint is that this method should have access to the DialogueContext, which can be solved by passing the latter to the method.

With such simple mechanisms, it’s easy to build a large library of reusable dialogue components.

Better integration in build and deployment process

Building a Rivr application simply means to compile the Java code and create a WAR (or an EAR). This is probably something you already do if you have in-house Java web development. So nothing new here, Rivr will fit nicely in your release engineering process. No need to figure out a way to integrate artifacts generation into an existing automated build process or using error-prone practice like relying on developers to manually trigger code generation from the diagrams.

Deployment process across different environments is as simple as deploying the web application on the appropriate web application server. Rivr isn’t tied to anything else.

Cleaner data flow and control flow

Vendors often sell graphical tools by pretending that “no developer skills are needed”. However, when you try to draw a callflow, you soon realize that you will need to deal with variables and flow control sooner or later.

Variable handling in graphical tools is usually a mess. They are defined here and there, they are global (they apply for all the diagram, and sometimes for sub-routine diagrams as well). What makes things worse is that diagrams don’t show them. You have to use many clicks on each box in order to figure out what happens to these variables. In short, you can’t follow you data flow. With Rivr, the data flow is clean because we are relying on a real programming language for that. The Java lexical scoping lets programmers declare and use variables where appropriate. When looking at code, it’s easier to follow assignments to variables.

Control flow blocks in graphical tools make simple things complicated. You need to edit the box to enter conditions, then you need to add arrows pointing to appropriate actions, add labels on the arrows, and add actions. If you are accustomed to use a programming language, you know that everything mentioned above can fit in a few lines of codes. Using Rivr, the control flow of your dialogue is simply expressed with the control flow mechanisms of Java (if/else, switch, for/foreach/do/while, try/catch/finally).

The fact that Rivr fixes the flow problems is the inspiration for its name (river, flow).

In the next post, we’ll look at more good reasons to use Rivr.

A (better) introduction to Rivr

[This post is a contribution of Jean-Philippe Gariépy, lead software developer at Nu Echo.]

In August 2013, Nu Echo announced Rivr, a new open-source Java dialogue engine for VoiceXML. At that moment, the API wasn’t yet frozen and we were expecting feedback before releasing our first stable version. Since that moment, we’ve been working on cleaning up the API, making it more intuitive. We’ve also added more documentation and a set of self-contained examples, the Rivr Cookbook. Being satisfied with the current state of Rivr, we released the 1.0.0 version. This version is ready for production-grade applications. We plan to leave the API compatible for all 1.0.x upcoming versions.

What is Rivr?

In a nutshell, Rivr is a Java library for making IVR applications for VoiceXML platforms. Rivr uses Java servlets to exchange VoiceXML documents between the VoiceXML platform and the application, each document being generated on-the-fly by Rivr. Instead of using the traditional, less powerful state machine abstractions, the developer implements the callflow by the means of a regular Java program. The developer never manipulates VoiceXML directly.

How does it work?

When you write a dialogue with Rivr, you write a Java method that will be invoked by the controller. The controller is usually the DialogueServlet but it can also be a unit test. In this method, whenever you need to perform a VoiceXML action (e.g. play a message, perform speech or DTMF recognition, transfer a call or record a message), you create an OutputTurn object and send it down to the DialogueChannel via the doTurn() method. The latter method will block the dialogue thread until the dialogue channel receives an InputTurn from the controller. Then, the thread will unblock and the method will return the InputTurn to the dialogue. There is no need to be concerned about the complete HTTP round-trip occurring between the servlet and the VoiceXML platform. You just need to call a method and deal with the result, this feels mouch more like a regular library API than a heavy framework.

A dialogue starts with a FirstTurn, then it’s just a series a exchanges of OutputTurns (actions to be run on VoiceXML platform) and InputTurns (the results of those actions) until the dialogue terminates with a LastTurn:

public LastTurn run(FirstTurn firstTurn, DialogueContext context) {
    OutputTurn question1 = ...;
    InputTurn response1 = doTurn(question1, context);

    //do something with the response

    OutputTurn question2 = ...;
    InputTurn response2 = doTurn(question2, context);
    //do something with the response

    //repeat as needed, then provide a dialogue result

    LastTurn dialogueResult = ...;
    return dialogueResult;


  ---------------------         -----------------        ------------------------
  | VoiceXML platform |         |    Servlet    |        | Application dialogue |
  ---------------------         -----------------        ------------------------
            |                           |                            |
            |    First HTTP request     |                            |
            |-------------------------->|       First Turn           |
            |                           |--------------------------->|
            |                           |       wait()               |
            |                           |--------------------------->|
            |                           |                            |
            |                           |       Output Turn          |
            |                           |<---------------------------|
            |                           |       wait()               |
            |    VoiceXML document      |<---------------------------|
            |<--------------------------|                            |
            |      results (HTTP)       |                            |
            |-------------------------->|       Input Turn           |
            |                           |--------------------------->|
            |                           |       wait()               |
            |                           |--------------------------->|
            |                           |                            |
            |                           |       Output Turn          |
            |                           |<---------------------------|
            |                           |       wait()               |
            |    VoiceXML document      |<---------------------------|
            |<--------------------------|                            |
            |      results (HTTP)       |                            |
            |-------------------------->|       Input Turn           |
            |                           |--------------------------->|
            |                           |       wait()               |
            |                           |--------------------------->|

            |                           |                            |
            |                           |        Last Turn           |
            |                           |<---------------------------|
            |    VoiceXML document      |                            |
            |<--------------------------|                            |
            |                           |                            |

In the next blog posts, we’ll discuss the many benefits of Rivr. Stay tuned!

Rivr 1.0 is out!

RivrYou may have already noticed but Rivr,  the Java dialogue engine for VoiceXML applications that we open-sourced last summer, has reached the 1.0 milestone. Thanks to Nu Echo’s dedicated team, this version is now the perfect tool for your communications application development, adding:

  • Stability. We fixed a number of issues.
  • A cleaner, more consistent API. We polished many parts of the original API.
  • Support for more VoiceXML platforms.
  • And, more importantly, extensive documentation in the form of Javadoc comments and a great cookbook that illustrates API usage for most use cases.

With this release, organizations can now rely on a rock-solid alternative to develop their call center or communications applications using the tools that better fit their corporate culture. Some of the largest banking institutions in Canada trust Rivr for the development of all their call center applications. Why not you?

As Nikos Patsis, CEO of VoiceWeb, says: “Rivr truly tackles a yet to be addressed space in the VoiceXML development landscape. It’s refreshing.” So wait no more, give Rivr a try!

The Rivr Cookbook

Back in August, when we launched Rivr, our open-source Java dialogue engine for VoiceXML, we knew one thing was sorely lacking: good documentation. We recently addressed this shortcoming with a complete cookbook containing several recipes.

The recipes

Rivr has a lot to offer. Just looking at a few examples like the Hello World application, however, may not be sufficient to truly appreciate its salient features. The Rivr cookbook fills this gap by focusing on the most common tasks one wants to achieve with it.

The cookbook is divided into 5 sections:

  1. A few sample applications (just one for now).
  2. Output turns, or how you play prompts and collect input from users, transfer calls, etc.
  3. How platform-specific features can be expressed (attached data, etc.).
  4. Integration aspects, like how to write JUnit tests or integrate with dependency injection frameworks (Spring and the like).
  5. Miscellaneous recipes.

By mastering these recipes, developers will be much better equipped to tackle more challenging voice applications.

Of course, cookbooks are always works in progress. So expect other recipes to be added in the upcoming months.