Feature Phone

Overview

To accommodate participants without access to a "smart" device with browsing capabilities, Malasakit also provides a feature phone frontend where participants can call a number to leave their responses. This document outlines how this frontend works.

Twilio

We use Twilio's programmable call service to handle incoming calls. Twilio exposes a toll-free number that participants call. Then, Twilio will request instructions over HTTP from a server running Malasakit; these instructions are written in TwiML, Twilio's custom markup language, and the Twilio client acts like a well-behaved browser (for example, accepts cookies). Twilio will then execute these instructions for the caller by playing messages or waiting for input. This instruction fetch and execute loop continues until either the caller or Malasakit terminates the connection. As far as Malasakit is concerned, the feature phone frontend is just another HTTP application.

Setup

After registering for a Twilio account, you will need to acquire a phone number from the console, and configure your balance (Twilio bills calls by the minute). (Be aware that there may be odd edge cases for the country you are deploying in. For example, some numbers may only receive domestic calls.)

Next, select the target number. Under "a call comes in", select "webhook", with the address set to http://<origin>/<path>/feature-phone/irb-notice/prompt/ and the method set to HTTP POST. Similarly, "primary handler fails" should be set to "webhook", with address http://<origin>/<path>/feature-phone/error/ and method HTTP POST. Change to https as needed. The <path> typically includes the language code, as well as any other prefixes. For example, http://opinion.berkeley.edu/pcariv2/tl/feature-phone/irb-notice/prompt/. This provides Twilio with the entry point (where Twilio should look for the first instructions) and the error endpoint (where to find the instructions that gracefully handle any errors).

Note that the language code in the URL determines what language will be used. To avoid branching (and further complexity), the language cannot be changed during a call. Instead, you would have one number per language.

Administration

See the docstring documentation for the feature phone model structure. In summary, most feature phone objects (recording, question, etc.) have web frontend analogs (called related objects). Typically, there is a one-to-one mapping from a feature phone object (implements knowledge about recordings) to a web frontend object (phone-agnostic, since responses can also be submitted via the website).

All web frontend question instances can be exported to the feature phone using the "use questions for feature phone" admin action. This generates a copy of each question in each language in the feature phone "questions" table. Feature phone question translation may need to be done manually.

In the reverse direction, you can transcribe ratings and comments by accessing the web frontend related object, and setting its fields appropriately. There is also an admin action "download a ZIP file of all recordings" to export all selected recordings in the admin site.

Finally, instructions (analogous to static template text) can be modified from the admin site as well.