The story of Mockingjay began during a subway ride in January 2013 when Brian Abelson and I were brainstorming ways to keep track of elected officials’ stances on gun control for an app being built at my then-newsroom, the Daily Beast. At the time, a widely-discussed measure on background checks and a possible assault weapons ban was going through Congress and we wanted to monitor whether it had the votes.

One way, we thought, would be to monitor each rep’s Twitter feed and log when they mentioned a few key terms such as “firearm,” “gun rights,” “newtown” etc. Combined with a “Find your representative” feature, we could display the latest news on each rep far faster then one person could keep up. While we were at it, we thought, why not open up the whole pipeline? Let it live outside the app. Meet the users where they are. That sort of thing. @YourRepsOnGuns was born. It follows a Twitter list and retweets its members when their tweets match a given Regular Expression pattern. @YourRepsOnGuns uses the following configuration:

{
    "bot_name": "reps-on-guns",
    "list_owner": "cspan",
    "list_name": "members-of-congress",
    "count": 200, // How many tweets do you want to return each time the script runs 
    "regex": "(gun safety)|(firearm)|(assault weapon)|(theydeserveavote)|(gunviolence)|(gun control)|(gun violence)|(nra )|( gun )|(^guns )|( guns )|(^gun )|(AWB)|(2nd ammendment)|(gun show)|(handgun)|(right to carry)|(2nd amend)|(second ammendment)|(second amend)|(brady campaign)|(carry permit)|(concealed weapon)|(sandy hook)|(sandyhook)|(sandy hook)|(newtown)|(sikh temple shooting)|(gabrielle giffords)|(gabby giffords)|(newtown massacre)|(2ndammend)|(2ndammendment)"
}

Design and Features

We decided to have it monitor a Twitter List—as opposed giving it a list of handles—two reasons. The first was you only have to make one API call instead of potentially hundreds. Twitter handles assimilating all the various accounts into one neat feed. And since Mockingjay stores the ID of the most recent tweet each time it runs, you only request tweets from where you left off. This is especially useful if your bot tweets a false positive (e.g. “The Newton Centre Station diner has great corned beef.”) since you can undo the retweet and your bot won’t try to retweet it again the next time it runs.

The second reason was we could either use an existing Twitter List, such as the members-of-congress list maintained by C-SPAN, or, if we wanted to point it at a list we maintained, we could add or remove those members without having to modify any code. In other words, the task of updating the bot could be done by someone without technical skills. Since Mockingjay is meant to be run on a five-minute cronjob, the script will use the new settings the next time it runs.

Rising from the Ashes: Election 2014

One of the things that made @YourRepsOnGuns so interesting for us was it gave readers a daily way to follow a newsworthy topic even if the daily news didn’t rise to the level of a full article. In addition to the “what does this story mean for the country?” versus “what does it mean for me?” of a story—the near and far views—we could provide a “long view” of an evolving issue. Interactive news is well positioned to deliver on this type of timeframe as well since these projects often require more investment upfront have a longer tail of utility.

This thinking about speed and time investment is a big influence on our planning here at the multimedia team at Al Jazeera America (AJAM). We try to do projects that we’re fairly certain will keep being useful as larger waves of the news cycle unfold. That’s translated from simple Ebola trackers to experimenting with interactive videos that pull latest campaign finance figures for your state and mapping the years-long humanitarian crisis of Syrian refugees.

About a year after Brian and I made @YourRepsOnGuns, the team here at AJAM was thinking about what we could add to our site’s election coverage. The bot needed a couple of upgrades since its initial launch but the idea of using it to continually monitor issue-related political discussion was a good fit.

We used the opportunity to do some repairs and release the version of Mockingjay you see today.

We built three bots @AJAMPotBot, @AJAMEnergyBot and @AJAMImmgratnBot. Using the Sunlight Foundation’s Politwoops list of Twitter handles as a starting off point as well as their record of who was running for what, we assembled a Twitter List of 858 candidates and pointed our bot fleet at them with these lists of keywords.

We embedded their feeds on our issue pages and were able to add livelier content than any human could deliver.

Who Bots the Bots?

In keeping with the spirit that someone non-technical could monitor these bots, you can configure Mockingjay so that it’s easily monitored via Twitter. Its retweet function returns an object that tells you how many new tweets it saw since last it ran, how many matched and whether the bot retweeted or not. We hooked this output up to our reporter Twitter bot @ajamrobots, which lets anyone check in on the status and health of all bots in the fleet. Here’s an example output from the immigration bot:

Or, if there is an error, it passes off the error text so you can see why it failed before jumping in and figuring out the problem.

Why Use Twitter?

One popular choice for bot status reporting and deployment commands in many newsrooms is to use Slack. We haven’t set up Slack, or similar vendor, for our team mostly out of security concerns—we don’t feel super comfortable sending our communication elsewhere. Since most folks are already on Twitter and have some system for monitoring it daily, this integration met folks where they already were..

More Resources

If you’re interested more in keeping track of what what elected officials are saying, the Statement library from the Upshot, which records reps’ RSS feeds from press releases and other official statements, is definitely worth a gander.

If you end up using Mockingjay, certainly let us know at @ajamviz!

• Share on Twitter
• Share on Facebook