Call Congress

A simple flask server that connects calls between citizens and their congress person using the Twilio API.

The server handles two cases:

Incoming phone calls

Each new campaign's Twilio phone number needs to be configured to point to:


The user will be prompted to punch in their zip code, the server will locate their members of congress using the Sunlight Labs locate data, and dial them.

Web-initiated connection calls

These calls are made from a web form where the user enters their phone number to be connected to Congress (will be prompted for zip code):


or a specific member of congress:


or to member(s) based on zip code:


Required Params:

Optional Params: (either or)

Campaign Configuration

Currently stored in /data/campaigns.yaml, each campaign has the following optional fields. Defaults are given by the default campaign.

Messages: Can be urls for recorded message to play or text for the robot to read. Text can be rendered as a mustache template. The following messages are the defaults and will be inherited by new campaigns unless overwritten.

Overriding the default behaviors with a Google Spreadsheet

Using the optional overrides_google_spreadsheet_id, each campaign can specify a remote Google Spreadsheet to pull in for state-specific overrides. This allows you to change the campaign's default behaviors on a per-state basis. Currently the following features are supported:

To get an idea of how this works, see this example spreadsheet.

Specifically, the Google Spreadsheet must be public, and published (note the distinction) and the first row must contain column labels in bold-faced and with exactly the precise text as specified here:

  1. State
  2. Target Senate
  3. Target House
  4. Target House First
  5. Optional Target Individual first (lastname)
  6. Optional Extra First Call Name
  7. Optional Extra First Call Number

Account Keys

The app uses environment variables to store account keys. For development you will need to set:

and for production:

Development mode

To install locally and run in debug mode use:

# create ENV variables
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt

python app.py
# for testing twilio, need internet-visible urls to do call handling
ngrok -subdomain="1cf55a5a" 5000

When the dev server is running, the demo front-end will be accessible at http://localhost:5000/demo.

Unit tests can also be run, using:

python test_server.py

Production server

To run in production:

# create ENV variables
# open correct port
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
# initialize the database
python models.py
# run server - will charge real $ and connect real calls
foreman start

Updating for changes in congress

Just download the latest data from Sunlight Congress API using:

cd data && make -B
git commit data/districts.csv data/legislators.csv