Twitter Bots

by Allison Parrish

We’re going to create a simple Twitter bot that tweets automatically from a pre-written list of tweets. You don’t need to do any computer programming to get this to work, but there are some persnickety parts where you’ll need to follow instructions precisely. Some of the vocabulary will be a little strange—we’ll be talking about “keys” and “secrets” and “callbacks”—but don’t get too wrapped up in the terminology. You’re going to great! I know it.

Static Twitter Bots

The method we’re going to use to set up a Twitter bot uses Google Apps to store the text of the tweets you want to send and to automatically schedule tweets. This is great, because it’s free and (relatively) easy to set up. The main shortcoming of this method is that it can only make one kind of Twitter bot: the kind that just tweets from a pre-determined list. There’s no functionality here to (e.g.) respond to particular tweets, or to generate tweets on-the-fly in response to some external stimulus. For many purposes, the static approach is sufficient. If you need help getting started on a bot that does something more sophisticated, let me know!

What we’re doing here

At this point, you’ve probably scrolled down this page and seen just how complicated all of these instructions are. “Why is it so difficult to set up something as simple as a Twitter bot?” you say. It’s a fair question! There are a number of steps you have to undertake in order to be able to use the Twitter API (“application programming interface”) at all, for any purpose.

The reason for this, as I see it, is that Twitter (as an organization) walks a fine line: they want artists and programmers to be able to create useful utilities that work with their service, but they don’t want to make life easier spammers or other abusive agents. (They also don’t want anyone to cut into their advertising revenue, which is neither here nor there…) So when you’re going through the steps below, and inevitably messing up a bit (and then stoically recovering from messing up, naturally), just remember that the same difficulties you’re having are the difficulties that every potential Twitter spammer (or phisher, or anyone else engaged in blackhat hacking) faces.

In brief, the steps below are intended to accomplish the following:

  • Set up a distinct user for your bot.
  • Give that user credentials for accessing Twitter programmatically. For security reasons, you can’t just use a password to post tweets programmatically; you have to use funny things called “OAuth tokens.” These tokens can only be issued in the context of a Twitter “application.” (“Application” is just a word for “a virtual entity that issues credentials”—we’re not making an iPhone app here or anything.)
  • Give the user something to Tweet. (This goes in a Google spreadsheet.)
  • Tell the Google servers to automatically tweet your data on a schedule. (This process is all managed by scripts that I’ve written, but there’s a tiny bit of setup work that you’ll need to do to get it all squared away.)

Steps

So let’s get started! Below you’ll find a list of steps in detail. The Google spreadsheet you’ll copy in step one also has an abbeviated version of these instructions.

Before you proceed, you’ll need a Google account (with access to Google Drive) in order to complete this tutorial. Log into your Google account and follow the steps below.

1. Create a copy of the “Iterative Twitter Bot” spreadsheet.

Click on this link. This spreadsheet is the “master version” of the spreadsheet, which only I can modify. You’ll need to make your own copy! To do this, go to File > Make a copy.... Choose a name that will remind you later what you intend to do with the spreadsheet (e.g., something like “Iterative Twitter Bot for Fun Sandwich Names”).

Make a copy

If you want to make a second Twitter bot, just make a second copy of the spreadsheet.

2. Populate your spreadsheet with Tweets

The “Iterative Twitter Bot” spreadsheet has two sheets: “Setup” and “Tweets.” You can switch between the two using the tabs at the bottom of the screen, like so:

Setup, tweets; setup, tweets.

Switch to the “Tweets” sheet. This sheet contains a list of Tweets that your bot should send—one tweet per row (with the tweet text in the first column of the row). The sheet comes pre-populated with a Shakespeare sonnet. You’re going to want to delete the sonnet and then paste in your own tweets. The easiest way to do this is to compose your tweets in a text editor, with one tweet per line. Then select all of the cells in the sheet, press “Delete” (or Backspace) and paste in the tweets from your text file. It will look something like this:

My tweets

3. Get the Project Key

You’ll need a special value called a “Project Key” in order to get your Twitter bot to work. (This is a value required by Google so that Google and external services like Twitter can talk to each other.) Getting the project key is a bit tricky. You need to follow these steps:

  • Switch to the “Setup” sheet.
  • In the menu bar, select Tools > Script Editor.... A new browser tab will open.
  • In the new browser tab, select File > Project properties.... Select the value labelled “Project Key” and copy it to your clipboard.
  • Close this tab. Paste the value you just copied into the cell next to “Project Key” in the Setup sheet.

The whole process looks like this:

Project key

The “project key” in the animation above is not the same as the one you’ll see. You’ll have something that looks similar—a bunch of random letters and numbers—but is actually different, if you look closely.

Don’t worry about anything else you see in the Script Editor window—that’s all behind-the-curtains stuff. Your only goal in the Script Editor window is to get the Project Key. After that, you never need to open that window again. (Unless you want to investigate how the Twitter bot works!)

I’m having a problem!

If something weird happened and you didn’t see exactly what happened in the above animation, something may have gone wrong. Perform the following steps to troubleshoot.

  • First, make sure you’re working on a copy of the spreadsheet, not the original. If you’re looking at the original, the “Script Editor” menu item will be grayed out.
  • Try reloading the page. (For some reason, some script-related events don’t fire off right after you copy a spreadsheet; reloading the page should clear up this problem.)

4. Create a Twitter application

At this point, you need to create a Twitter application. This is easier than it seems at first. Go to this page and log in to your Twitter account. (You do have a Twitter account, right? If you don’t, sign up for Twitter real quick and then come back here when you’re done.) Click on the “Create a new app” button in the upper right-hand part of the screen.

You’ll see a form that looks like this:

Create an app

Fill out this form. The values you use for the “name,” “description” and “website” fields aren’t important; no one will ever see these except for you (and maybe someone at Twitter if someone complains about your bot). The “name” field needs to be globally unique, so put in something distinctive. (“Test app” isn’t going to cut it.)

The only tricky field is “Callback URL.” This needs to be a very particular URL that is associated with your Google Apps spreadsheet. To get the value to put in this field, go back to your spreadsheet and select Bot > Get Callback URL from the menu. An alert window will appear; copy the URL in the window. The process will look like this:

Callback URL

The completed Twitter application form will look something like this:

Completed application

Agree to the Terms and Conditions, then click “Create Your Twitter Application.”

5. Copy your app tokens to the spreadsheet

There are two “tokens” or “keys” that we need from the Twitter application. These are essentially two randomly generated strings that uniquely identify your application. They’re needed for your bot to function. (Because these keys identify your application, don’t share them with anyone!) You can get these keys by going to the application whose keys you want in the Twitter Application management interface. (If you just completed the step above, you’ll already be in the right place.)

Select the “Keys and Access Tokens” tab. You’ll see something that looks like this:

Keys and tokens

The two strings you’re after are the “Consumer Key” and the “Consumer Secret.” I’ve blacked out the “Consumer Secret” in the illustration above (don’t share these values with anyone, remember?), but my consumer secret looks a lot like yours: a seemingly random string of letters and numbers.

Copy the value for “Consumer Key.” Switch to a browser window with your bot’s spreadsheet open and paste the value into the field labelled “Consumer Key.” Do the same thing for “Consumer Secret.” It’s very important that you copy these values exactly, without any missing or extra characters. Your spreadsheet should now look like this (again, I’ve blacked out my consumer secret):

Keys in place

Great work! We’re almost there.

5. Create a new Twitter account for your bot

Now you need to create a new Twitter account for your bot. The tweets in your bot spreadsheet will be sent as this user. Sign out of your personal Twitter account and then create a new account. Note that your new Twitter account must have a unique e-mail address, so you may not be able to use the same e-mail address for your Twitter bot account as the one you use for your personal account. Try the tricks here to re-use one Gmail account for multiple Twitter accounts, or just sign up for a new free e-mail account with a different service.

(Note: you don’t have to go through the whole “follow these users!” rigamarole. After you get past the initial account creation step, just enter https://twitter.com/ into your browser’s location bar. I won’t tell Twitter that we’ve figured this out if you won’t.)

Important: For the next step (the “Authorization” steps), stay logged into Twitter as your bot account. If you go through the “authorization” step logged in to your personal Twitter account, the tweets will be sent from YOUR account instead of your bot’s, which is probably not what you want!

6. Authorize your bot

Now we need to “authorize” your bot account to use your Twitter application. To do this, select Bot > Authorize from the menu. You’ll see a dialog box appear; it will display a URL. Copy this URL and open it in a new browser window. When it asks you to authorize the application, click “Authorize app.” The entire process will look like this:

Authorize

Close the window that says “Success!” and go back to your spreadsheet.

If you have any problems along the way, try the following:

  • In your bot’s Twitter settings, go to “Apps” and revoke authorization for your application. Then perform the steps above again.
  • In your spreadsheet, go to Bot > Clear Auth and then repeat the steps above.

7. Send a test tweet

Now the spreadsheet should be able to send tweets! To test this out, go to Bot >Send test tweet. If everything is going well, nothing will happen in your spreadsheet… but if you look at your bot’s Twitter account, a tweet should appear!

Test tweet

(Did I spell “pumpernickel” right? I don’t even know and I’m too high on bots to bother looking it up! What a time to be alive.)

If the test tweet did not appear, then something went wrong. Click on Tools > Script Editor... and then View > Logs for some hints about what went wrong. Ensure that you got the values for the Project Key, Consumer Key and Consumer Secret exactly right. Also: try using Bot > Clear Auth and then repeating the authorization step.

7. Schedule tweets

The “Interval (minutes)” value in the “Setup” sheet controls how often your bot will tweet. The value for this field must be one of the following:

  • 1, 5, 10, 15, or 30
  • Or a multiple of 60 (60, 128, 180, etc.)

I recommend setting this to 1 at first, just to check to see if your bot is working properly, and then backing off to something more reasonable (like 120).

To start your bot’s automated tweeting process, go to Bot > Start tweeting. You should start seeing tweets showing up in your bot’s account after some amount of time has passed.

Conclusion and further reading

And… that’s all there is to it! You are officially a botmaker. Please contact me if you have problems or questions.

You can also peruse these other botmaking resources, many of which inspired the approach I took in this tutorial: