LobbyPhone

I built a thing: text your US postal address to (520) 200-2223 and get a text back with your state & federal legislative rep phone numbers.

— John Emerson (@backspace) November 20, 2016

I built an SMS bot! Here’s the story: I’ve been looking at bots for advocacy and have been keeping a short list of inspiring SMS projects including TXTMob, Crises Text Line, mRelief, Planned Parenthood’s Teen Q&A line, and others. I’ve poked around the Twilio API. And then came this message on the Progressive Exchange email list:

Subject: ISO "find your elected officials" by text

I have to think this exists -- is there a simple "text KEYWORD to THIS NUMBER" that will return the names and phone numbers of your elected officials? Congress and state?

Jesse

Turns out it does not exist — so I wired it up and announced it on the list. The response has been super positive.

In the last few weeks, around 3,000 people have texted the bot and folks have been sharing screenshots of their results on Twitter and Facebook.

Here’s how it works: Plivo receives a text message at a phone number and sends a POST to a Node.js script I’m running on a server. My script geolocates the postal address using the Google Maps API and then send the resulting latitude and longitude to the Google Civic API for the names and numbers of representatives. The script then formats the resulting data and then sends back out a text message through Plivo.

There are a few fail-safes: when Google Maps can’t geolocate an address I fall back to the MapQuest API, and when Google Civic does not return state legislators I fall back to the Sunlight Foundation’s OpenStates API.

The vast majority of users are sending ZIP codes instead of postal addresses, which makes finding reps a little complicated. ZIP code boundaries do not always align with electoral district boundaries, and more than one district may overlap a given ZIP. Google Civic seems pretty strict and does not return potentially incorrect information, so if you just send it a ZIP code it may not return state-level reps at all. OpenStates is more forgiving, though may not be as up-to-date. When I geolocate a ZIP code, I get it’s center point and see what district that point is in.

Some folks have been cautious about sharing their personal info. I keep the data for 24 hours for debugging and Plivo logs the numbers to bill me for usage. I absolutely will not share or sell people’s personal information.

It was a strange, disembodied experience building an “app” with no graphical front-end and no content management system on the backend. The design here is all in the tone and formatting of the text.

Here are a few things I learned:

• SMS is limited — not just the number of characters, cellphone carriers put actual rate limits on SMS. You can’t send messages too quickly or send too many in a day or carriers will flag you as a spammer.
  
  
• If you do want to send higher volumes of messages, you have to license a short code. I always thought these were for memorability and fewer digits to type into your phone, but it really is a two-tiered content system for pay: licensing an short code number runs from $500 to $1,000 per month but buys you much more throughput. When you see those ads about sending a KEYWORD to a short code number it’s probably because that short code number is being shared by more than one service.
  
  
• SMS messages can fail silently. This is not like email where you get a verbose error bounced back at you. While Plivo has decent logs about delivery, some messages just never went through and I never found out why.
  
  
• It’s surprising there’s no RESTful API for iMessage, which seems like one workaround for SMS limits. Googling around, I found some folks using AppleScript to hook into iMessage, and in the latest iOS other iPhone apps can use some iMessage features, but it seems like there’s an opportunity here to do more. I suppose Apple may be worried about spam, as well.
  
  
• It’s strange paying a la carte per SMS when you can get a cheap cellphone with an unlimited text messaging plan. Plivo charges $.0035 per 160 characters to send a text message, and the legislator names and phone numbers take two of those units. Incoming SMS messages are free, though it’s $0.85 / month to reserve a phone number. If one wanted to use one of those unlimited data plans, perhaps one could hook up a GSM modem to a networked laptop, though you’d still be up against those SMS rate limits.
  
  

In any case, the source code of my bot on GitHub if you’re inclined, though it’s ugly and there’s some nested callback hell that could use some serious refactoring. But it works and is running now and is bringing people delight and power. Which is pretty satisfying.