CityVoice is a place-based call-in system to collect community feedback on geographic entities (like vacant properties) using the simple, accessible medium of the telephone.
Using CityVoice in your city
CityVoice is an open source project, and we'd love for you to use it yourself!
To use CityVoice, there are three main steps:
Following this documentation, a semi-technical user — someone with experience using a terminal or command prompt — who has an idea of what kind of survey they would like to run should be able to get CityVoice up and running in a relatively short amount of time (less than a day).
Using the recommended deployment instructions below, the tech cost (hosting and other services) should run you about $50 per month.
If you have problems using CityVoice, please open an issue here on GitHub and let us know what problems or difficulties you encountered in as much detail as you can.
Making a CityVoice survey
What you'll need to make a CityVoice survey:
- A set of locations (for example, properties or neighborhoods) that callers will call in about or from
- A set of 2-5 questions that you want to ask callers
- Agree/disagree questions
- A voice message question
- A microphone (for example, using a laptop or phone) to record mp3 audio files
The exact steps for making and setting these up in CityVoice are in the "Making a Survey" document.
Deploying the app
Before deploying, here are the third-party services that are either required or easiest to use.
Twilio — telephone API1. (Required)
First, you'll need a paid Twilio account and phone number:
If you're new to Twilio, you'll have to add $10 in credit (the minimum) to your account to get started. This will be more than enough for CityVoice, which required $1/month for the phone number and 1 cent per call minute (~ $2/month in total).
Heroku — application hosting2. (Recommended)
Heroku is an easy and cheap (~$50/month) way to host your CityVoice instance.
If you have experience with Ruby on Rails, you can alternately deploy to any infrastructure that supports a Rails 4 application and Postgres.
Deploying on Heroku
To follow the below instructions, you will first need to install the Heroku toolbelt on your computer.
Below are example instructions for deploying to Heroku. The process will be similar for other platforms (e.g., Amazon EC2, Red Hat OpenShift).
First, clone the application:
$ git clone firstname.lastname@example.org:codeforamerica/cityvoice.git
Go into the repo folder:
$ cd cityvoice
Create a Heroku app:
$ heroku create
Set the secret token:
$ heroku config:set SECRET_TOKEN=`python -c 'import uuid; print uuid.uuid4()'`
Take the CSV and mp3 files content you created in the "Making a CityVoice survey" section, put them in their destination folders (
/app/assets/audios/) and add and commit them into the repo.
$ git add data/ app/assets/audios/ $ git commit -m "Add customized CSVs and audio files for my deployment"
Next, push the code to Heroku:
$ git push heroku master
Migrate the database:
$ heroku run rake db:migrate
Load the locations and questions:
$ heroku run rake import:locations $ heroku run rake import:questions
Add an additional web dyno so that the app never sleeps (this is necessary so the app always answers when people call in):
$ heroku ps:scale web=2
To configure your number on Twilio's site, log in and go to your "Numbers" page. Then click on the phone number you bought.
In the 'Voice' area, put your deployed application's URL followed by
/calls in the 'Request URL' field and select
HTTP POST from the dropdown.
For example, for an app at http://my-cityvoice-instance.herokuapp.com:
CityVoice also has a number of optional features you can set up:
Outreach and Marketing
Effective outreach might be the most important piece to making your use of CityVoice a success. Here are some tips from past CityVoice uses that might be helpful:
Physical, prominent, and persistent calls to action are very useful. For example, a large sign in a park that's there for two months is much better than a poster on a bulletin board with 20 other posters or a mass email.
Promotion, outreach, and media campaigns around the application are incredibly important. Without an effective campaign no one will know or care about the project.
The application is really built to ask questions about locations. Although it can work in other situations, it works best when tied to specific places.
If you've used CityVoice before and have additional ideas, let us know! Click here and describe your experience with doing CityVoice outreach.
For developers - local setup
If you're a software developer and would like to work on CityVoice, this section will get you up and running.
CityVoice is a Ruby on Rails 4 application and uses Postgres as its database (other databases may work, but are untested).
To get started with development, clone the repo and cd into the directory:
$ git clone email@example.com:codeforamerica/cityvoice.git $ cd cityvoice
Use Bundler to install dependencies:
$ bundle install
To get the application set up for local development, first copy database.yml:
$ cp config/database.yml.example config/database.yml
Then, edit it for your local Postgres installation and run:
$ rake db:reset db:test:prepare
Next, load some sample data:
$ rake import:locations $ rake import:questions
Tests are written in RSpec, and can be run as normal:
$ rake spec
Twilio Local Setup
In order to set up Twilio for local development, you'll need a way to connect Twilio to your local machine. The easiest way for this to happen is to install ngrok.
ngrok http 3000 to open a tunnel:
$ ngrok 3000 Tunnel Status online Version 1.6/1.5 Forwarding http://xxx.ngrok.com -> 127.0.0.1:3000 Forwarding https://xxx.ngrok.com -> 127.0.0.1:3000 Web Interface 127.0.0.1:4040
Log into your Twilio application, open up your phone number and change the Voice Request URL to the your ngrok address with
/calls at the end. For example:
POST from the dropdown next to the URL box.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
License and Copyright
Copyright 2013-2014 Code for America, MIT License (see LICENSE.md for details)