GraphIVR

A Graph-based Interactive Voice Response (IVR) System

Introduction

The application configures an interactive voice response (IVR) system based on a directed property graph. This application allows you to build complex phone trees by arranging nodes and edges on a graph. An advantage of this approach is that it allows less technical users to manipulate the phone tree without needing to interact with the underlying application code.

The application is written entirely in XQuery 3.1 and the graph query language Cypher.

Requirements

• BaseX, an open-source XML database with a built-in HTTP server.
• Neo4j, an open-source graph database.
• Twilio, a cloud-based communications company with support for voice calls.

Installation

• Download the BaseX HTTP War and upload it to either a Tomcat or Jetty server. If you need an easy way to host BaseX, you may want to try out Servint's Jelastic PaaS, which makes hosting Java applications very straightforward.

• After you install BaseX on a server

  • Make sure to change the admin password and, if desired, update the WebDav and REST passwords in the web.xml file.
  • Create a database by sending a put command to BaseX's REST endpoint containing on the name of the database in the URL ; if you 'graphivr' as the name of the database, the PUT request would be http://localhost:8984/rest/graphivr.
  • Finally, you also need to add support for mixupdates in the web.xml file by adding this XML snippet:

  <context-param>
      <param-name>org.basex.mixupdates</param-name>
      <param-value>true</param-value>
  </context-param>

• Provision a telephone number with Twilio. If you do not already have a Twilio account, you will need to create one. After you have created your account, click on Buy a Number from the Twilio console. After you have provisioned the number, click on Manage your Incoming Phone Numbers and select your new number. Set a web hook for your incoming voice calls to the base-url of your website + "/node"

  

• Set up Neo4j on an HTTP server. You may want to consider using a managed Neo4j host such as Graphene. After you have set up Neo4j, make sure that you copy the connection string (with user name and password) for the Cypher endpoint.

• Clone this repository and upload the three XQuery libraries (graphivr-api.xqm, graphivr-neo4j.xqm & graphivr-web.xqm) to the WEB-INF directory of your Basex HTTP Server. Change the connection string in graphivr-neoj.xqm (i.e. declare variable $graphivr-neo4j:endpoint as xs:string := ) to your Neo4j connection string.

Graph Model

GraphIVR allows you to configure your IVR by manipulating a Neo4j graph. For instance, a simple phone tree may be modelled in Neo4j as follows:

There are three type of nodes in the graph: Choice, Record, and Terminus. A Choice node presents callers with branching options in the graph. A Record node allows callers to record information. A Terminus node ends the call. There is only a single type of edge in the graph: Key. A Key edge allows callers to traverse from one node to the next based on a keypad entry.

Choice nodes must have at least one Key edge. The diagram below illustrates the available properties for Choice nodes and Key edges. The required properties for Choice nodes are "name," "say," and "id." The "play" property is optional. If a "play" property is present, GraphIVR will play the recorded sound at the indicated URL instead of speaking the phrases in the "say" property.

Record nodes must have one and only one Key edge. The edge should provide instructions about how to terminate the recording. The required properties of Record nodes are "name" and "id." A "say" or "voice" property should not be placed on Record nodes.

Finally, a Terminus node ends the call. A terminus node must have only incoming edges and no outgoing Key edges. As with Choice edges, The required properties for Terminus nodes are "name," "say," and "id." The "play" property is optional. Normally, a Terminus node should contain a message indicating that call will be coming to an end.

Privacy

This application does not provide any privacy protections. It is not intended to function as a standalone application, but as a component of an encompassing system. By default, the application produces a public RSS feed with the personal information of every caller. Please do not use in production without securing users' privacy and security.

Credits

This project arises from Dr. Ifeoma Nwankwo's (PI) Wisdom Working Group. Please credit this project in any citations or downstream uses of this software.