How Resistbot Makes It Simple and Consistent to Write to State Lawmakers

Resistbot has delivered more than ten million letters to elected officials thanks to two design tenets:

• It’s simple: text resist to 50409
• It’s consistent: the same instructions apply nationwide

Almost immediately after launch, the feature requests started to roll in to be able to contact state legislators, in addition to Congress. It took well over a year to build, but we did it!

Before Resistbot, It Was Real Complicated to Contact State Government

Let’s say you’re a voter in Pittsburgh and want to write a message of support for Gov. Wolf’s 21st century voting reform plan to the Governor and your Representative and Senator in the Pennsylvania General Assembly. You would have to go to 11 different websites*, enter your address 3 times, and send 1 fax!

The goal was to eliminate all these steps, so all you have to do is text “state” to 50409. Resistbot will find your state legislators and governor and deliver your message like magic.

This is a game changer: now any influencer or advocacy group can say “text ‘state’ to 50409” to mobilize constituents around a bill under consideration in state government.

Challenge One: State Legislatures Are Inconsistent

To Resistbot users it’s magic — and behind the scenes, state legislatures are awesome and complicated.

Some state legislatures have a consistent web form for all members, which is great. Some legislators make their email address public, which is pretty good too. And regrettably, many lawmakers still only publicize a fax number or postal mail address. To cover everybody, we needed to support web forms, email, fax, and postal mail.

State legislatures are also all over the place in representational structure. In most states, one person is represented by one state senator and one state representative. But many states are unique. For example:

• A person in unicameral Nebraska is represented by one Senator only.
• A person in Vermont is represented by one Representative and up to six Senators.
• A person in New Hampshire has up to 10 Representatives in some House districts and may also be represented by one or more Representatives in “floterial” districts which subsume multiple normal districts.
• A person in Puerto Rico is represented by two Senators from their Senate district, 14 Senators elected at-large, one Representative from their House district, and 11 Representatives elected at-large. (There are especially many Senators because of Puerto Rico’s unique guarantee of minimum legislative minority representation.)

Challenge Two: Open Data Is Fragmented

Before 2019, all of Resistbot’s database of Congressional representatives was hard-coded and maintained by hand. This was untenable as the transition to the 116th Congress approached. We also knew we could never maintain a database of 7500 state legislators and contact info by hand.

We decided to leverage existing open data sources, which allowed us to keep Resistbot up to date while improving open data. There is no single free source that covers all levels of government, so we needed a way to pull from a bunch of sources: Open States, UnitedStates.io, Contact Congress. We also introduced our own open-source repository of web contact form configurations for governors and state legislatures.

Challenge Three: Resistbot Needed a Generalized Data Model

Resistbot previously assumed that a user has two US Senators reachable by web form, one US Representative reachable by CWC, one governor reachable by fax or postal mail, and that’s it.

Now, a user in Maryland would have also three state Delegates and one state Senator contactable by web form and email.

We needed to create a general database of all a user’s state and federal representatives, support writing to any or all of them, and deliver the message in the fastest manner possible.

Discovery: a Database of Officials and How to Contact Them

We implemented Discovery to bring all elected officials and how to contact them into one generic data model.

First, we needed to collect all elected officials in one place. Every hour, we pull the latest lawmaker data from Open States and UnitedStates.io. We made an admin interface for overwriting any field, like fax numbers or Twitter handle (in addition to contributing updates upstream where possible; one exception is most elected official databases store only one fax number, but it’s important for Resistbot to cycle through all of an official’s fax numbers). We also used the Discovery admin interface to manually add information on governors. Eventually we would love to pull in more types of officials, like city and county lawmakers!

Next, we taught Discovery how to contact every official. The best way to contact an official is with their official web contact form, so an amazing crew of Resistbot volunteers scoured governor and state legislatures for web contact forms, teaching Resistbot how to use 73 contact forms for governors and state legislative chambers. (The trickiest part was the state legislative chambers — it can be very tricky to automatically choose the correct state legislator in some states, so we introduced metaprogramming in the contact form configurations to accommodate an entire legislative chamber with one configuration.) These are all open-source in our new contact-officials repo. Every hour, Discovery pulls them in, and also pulls from contact-congress, which covers all US Senators’ web contact forms.

Finally, Discovery’s API exposes officials per user, best delivery method per official, and delivery method details per official and delivery method.

Example With Engineering Gossip : )

Let’s say we text `state` to Resistbot from Braddock, PA. After we type our message:

1. Resistbot asks service Messenger to send the message to PA state government officials for House district 34 and Senate district 43.
2. Messenger asks Discovery who those officials are. Discovery returns Rep. Lee, Sen. Costa, and Gov. Wolf. Messenger enqueues three messages in the ingress SQS queue.
3. Pathfinder reads from the ingress SQS queue and for each message, asks Discovery which delivery method is best for delivering to the specific official. For example, the best delivery method for Rep. Lee is the official PA House web contact form, so Discovery returns ‘web_form’. Pathfinder therefore adds this message to the ‘web_form’ SQS queue. (There is one queue for each possible delivery method: ‘web_form’, ‘cwc’, ‘email’, ‘fax’, ‘mail’.)
4. Mercury grabs the message for Rep. Lee, fires up a headless browser, downloads the delivery method details for ‘web_form’ delivery method from Discovery, then follows the steps therein to fill in the user’s message and contact information and confirm the message was sent. (Each delivery method queue has its own consumer; the message to Sen. Costa will end up in the ‘fax’ queue, from which Gemini will send the message to Twilio using the ‘fax’ delivery method details from Discovery.)

Now It’s Up to You!

Text state to 50409, or to Resistbot on Twitter, Messenger, or Telegram and make your voice heard in state government!

And we would also love your engineering help with the next round of bold engineering projects.

• Make it possible to write to your city council!
• Implement a flow to Run For Something!
• Teach Resistbot how to smartly categorize the topic of a user’s message!

Email us to get started! Join all of us who made state reps happen in Resistbot: Chris Nardi, Jason Putorti, Matthew Coleman, Jesse Peters, Jason Cachia, Jason Katz-Brown.

In addition to donating to Resistbot, consider supporting Open States with a donation as well. For more than a decade, Open States has done tireless work scraping state legislature websites to produce an incredibly valuable open database of the people and bills of our state legislatures.

* Give or take, with these steps :)

1. Google “pennsylvania find my legislator”, click https://www.legis.state.pa.us/cfdocs/legis/home/findyourlegislator, enter your address, solve a captcha
2. Click “Rep. KIM”, click mail icon, click “Email me”, enter address, email address, phone number, and write your message.
3. Click “Sen. DiSANTO”, fire up your fax machine, write your name and message on a letter, fax it to (717) 783–3722
4. Google “contact governor wolf”, click https://www.governor.pa.gov/contact, click “Online Form”, enter address, email address, phone number, and write your message.