Do you want your voice to be heard? Then you should call your elected officials and make sure they know what issues are important to you. Government contact information is available over at USA.gov, but there is a better way to get connected. Use CallCongress.
Call (888) 491-2262
Callers are prompted to select from the names of their senators and representatives. With just one press on the keypad, the caller is connected directly to the office of the selected official. Go ahead and give it a try.
- Ruby – My favorite programming language. It’s dynamically typed and maximizes programmer happiness.
- Sinatra – A super simple framework for building web applications in Ruby.
- Builder – A Ruby library for creating XML documents.
- Sunlight Congress API – Easy access to data on elected officials, including phone numbers.
- Heroku – Easy hosting for Ruby applications (free for small applications).
- Twilio – An API for building voice and SMS applications.
How it Works
I hacked together CallCongress in just a few hours with a minimal amount of code. The main application logic is just 35 lines.
0. Setup and Declaring Routes
I included a few things, grabbed an API key from the environment, and then declared routes for the POST method on four patterns (“/”, “/people”, “/nozip”, and “/dial”). We’ll walk through each of the routes next.
1. Dialing In
I purchased a number and set the Voice Url to “http://callcongress.heroku.com” from within my Twilio account dashboard. Each time someone calls the number, Twilio issues an HTTP POST request to the Voice URL. You can read more about the Twilio Request in our documentation. When the application receives the HTTP POST from Twilio a match is found and the block we defined is executed.
This “welcome” builder template is called and generates TwiML to respond to Twilio with. I use the <Say> verb to speak to the caller using text to speech before <Redirect>ing to “/people” which initiates another Twilio Request to the application while the caller is on the line.
2. Searching the Sunlight Congress API
When the application receives the request to “/people” the following block is executed. The request from Twilio contains the optional parameter FromZip for most calls that are placed from a phone in the United States. FromZip is based off of the phone number itself, and is a good indicator of where the caller is registered to vote. Passing FromZip to the “Sunlight::Legislator.all_in_zipcode” method returns an Array of the legislators that are relevant. The Sunlight Congress API Ruby gem makes this a breeze. At this point “@members_of_congress” contains all of the names and phone numbers of the relevant legislators and the “people” builder template is invoked. In the event that no FromZip is available, the request is redirected to “/nozip”.
“@members_in_congress” is made available within the “people” builder template. There is a simple <Say> to prompt the caller to select who they want to call followed by the use of <Gather> to collect input from the keypad. Nested in the <Gather> we create one <Say> for each representative to speak the name of and a which key to press to select while listening for input. Once the caller presses a key, Twilio will make a request to “/dial”, the specified action url.
3. Connecting to the Selected Official
The request to “/dial” includes a Digits parameter which indicates which key was pressed. Here we use the key press to set @member to the official selected by the caller before invoking the “dial” builder template.
The “dial” builder template contains a connecting message in a <Say> verb to speak the name of the selected official back to the caller and before making the connecting call. To make the connection we use the <Dial> verb with the phone number. At this point the caller would is connected directly to the office of the selected legislator for a conversation about important issues.
4. No FromZip
In the case that there is no FromZip available the caller is routed to the Congressional switchboard in Washington, DC. The number is hard coded in the “nozip” builder template.
CallCongress is Open Source and Easy to Use
I released all the code for CallCongress under the MIT License, you can find it all over at GitHub. You can run it yourself and connect it to your own Twilio numbers.
Many thanks to the fine folks over at the Sunlight Foundation for putting together such a useful API. They’ve got a lot of handy projects. Sunlight Foundation is a non-profit, so you might consider donating a few bucks to help make government transparent and accountable.
Sunlight Congress API
The Sunlight Labs Congress API provides methods for obtaining basic information on Members of Congress, legislator IDs used by various websites, and lookups between places and the politicians that represent them. The primary purpose of the API is to facilitate mashups involving politicians and the various other APIs that are out there.
Anyone can use the Sunlight Labs Congress API, all it takes is a 15 second sign-up so that we can keep track of how many people are using the API and have a way to get in contact with you should there be any changes or API related news.