N-Maronic / IVR-colonial-heritage

In this repository you can find all the necessary code and information regarding an IVR project at the Vrije Universiteit Amsterdam.

IVR colonial heritage

This is a project conducted in fulfillment of the requirements for the Honours Programme at the Vrije Universiteit Amsterdam, which is an excellence annotation to the VU Bachelor of Science degree in Computer Science.

About the project

The aim of this project is to use crowdsourcing techniques to tag objects from the colonial period exhibited in Dutch museums. We created a IVR (interactive voice response) system to gather information about colonial heritage objects that are originally from Ghana, and that are now exhibited in the Wereldculturen Collectie. We are using the Twilio platform, which offers a Voice API to create a personalized voice interface.

Build status

This project is still under development. More specifically, we are still working on including Dagbani as a language option for the survey.

Installation Guide

Note: We are assuming you have a valid Twilio account.

The next two sections show step-by-step how to set up the IVR. The first option is using Python and running on a webhook connected to your local machine. The second option, is using the Twilio Service, including functions and assets, which runs on the Node.js engine.

Python

Run the app locally following these steps:

1. Clone this repository and cd into it.
2. Install a virtualenv with

   pip install virtualenv

3. Create the virtual environment with

   virtualenv env

4. Activate the virtual environement with

   source env/bin/activate

5. Install the dependencies with

   pip install -r reqs.txt

6. Execute answer_phone.py with

   python3 answer_phone.py

7. In a new terminal run

   ngrok http 5000

   to create a Webhook to your locally running application. You can find more information about ngrok here
8. Copy-paste the ngrok link to your Twilio console

Now your server, and consequently your IVR, is up and running.

Node.js

1. Create a new Service in your Twilio Functions and Assets (documentation)
2. Copy-paste the JavaScript files from the Node.js folder in function files in your Twilio Functions and Assets (documentation)
3. Deploy your Service
4. Copy-paste the URL to your Twilio Console

Testing

Python

To check whether the Webhook correctly routes to your localhost, simply paste the ngrok URL in your browser of choice.

Both implementations

To test the voice application, simply call your Twilio number. The recordings of the call can then be found under 'Call Logs' on your Twilio console.

Retrieving recordings and transcripts

In order to store links to the recorded calls and the respective transcripts in a local spreadsheet, simply execute the 'retrieveCalls.py' file after the following steps:

1. Save your Twilio SID and authentication token in the twilio.env file to set the environment parameters
2. execute source ./twilio.env in the terminal