Do you like Twitter bots? I know I sure do. I like following them, and I like making them. I also like introducing my students to bots as one way to do creative things in a networked digital context. That's way, back in 2013, I cobbled together a simple tool built on a Google Spreadsheets that lets anyone create a simple bot without having to write any code. There are many other ways to make a Twitter Bot, but I like this approach for its clarity and hopefully its accessibility for non-programmers to start understanding how to think about language through programming.
Today, I'm releasing an upgraded and much improved version of that tool. I've been calling it "SSBot", but I welcome your suggestion for a better name. This blog post contains the instructions for setting up that tool, but the steps are also included in the spreadsheet. I hope they're clear enough in that form as well, but this blog post will include images to help explain some parts.
Some Caveats
There are many varieties of Twitter bots -- some can engage in conversations with users, process images in interesting ways, or interact with live data sources. The SSBot tool is somewhat limited in this regard and it currently cannot:
- pull live data from a realtime API
- respond to users
- post images
That said, you can still do quite a lot with this bot engine if you approach it creatively and thoughtfully. Mark Marino's Terms of Service Bot and @TheHigherDead (by Chuck Rybak) are good examples of what you can do with some careful attention to syntax.
Furthermore, it's worth noting that using this SSBot to make a Twitter bot is something you undertake at your own risk. Using it doesn't guarantee that you won't violate Twitter's terms of service and get banned. Darius Kazemi's recommendations for basic Twitter bot etiquette are also good to keep in mind.
Finally, as I'm not really a programmer, please be aware that while SSBot does work, it might not work well. If you find a bug, let me know and I'll try to fix it. Likewise, if you feel like improving it in some way, great! Please feel free to do so.
Improvements over Version 0.3
If you used the earlier version of SSBot, you will be interested to know that this latest version closes some gaps in the first version and extends it in some hopefully useful ways:
- fixes the bug whereby using certain characters ( *, !, ), (, [, ] $ ) would cause the Twitter authorization to break
- adds "select from columns" or "select from rows" options so you can use whichever best matches your source data
- adds a simple Markov-chain text generation type
- adds a method for integrating with a TAGS archive to make an _ebooks-style bot from an existing account(s)
- with the "select from columns" method, one can now precompose thousands of tweets
To accomplish all of this, the setup now requires an additional step or two, but I think it's still pretty easy.
Upgrading from Version 0.3
If you're upgrading your bot from version 0.3 (and you will need to because version 0.3 uses the soon to be deprecated OAuthConfig, you can use the same Consumer Key and Consumer Secret you've already set up. Make your new sheet, then skip to the second part of Step 3 below and proceed as directed.
To set up your content, use the new "Select from Rows" sheet to hold your vocabulary.
On to the instructions.
General Setup Instructions
The following steps are general for any type of bot you want to create. To get started, make a copy of this spreadsheet, then proceed through the steps below.
Step 1: Create a Twitter account for your Bot
Go to Twitter.com and sign up for a new account. You can always change the name later, but to make the next steps go smoother, go ahead and confirm the account with an email address and do some of the basic profile setup. For the email address, I like to use the "+something" trick whereby adding "+something" after your name in a Gmail address (as in, "zach.whalen+something@gmail.com") will force Twitter to see that as a distinct email address, but you will still get that email in your inbox.
You'll need to verify your email address and a mobile phone number. This is a pain, but it's what Twitter requires now. If you already have a mobile number associated with a different Twitter account, you'll have to disconnect that one first. You can always re-arrange those associations later, but the bot account does need to have a mobile number while you're setting it up.
Enter your account name in your Spreadsheet under Step 1.
Step 2: Create a Twitter App for your Bot
This application ("app") is the method that your spreadsheet will use to talk to Twitter. It's possible to use Apps for multiple bots or accounts -- in fact, this is how they're designed -- but I like to make one for each bot account so that if one gets suspended the others aren't necessarily in jeopardy at the same time.
Go to apps.twitter.com and hit the "Create New App" button there. Fill out the form to give your app a name, description, and website. These can be quite simple and can always be changed later. The app's name needs to be unique, so you can name it the same it based on your bot.
Leave the "Callback" field blank for now. If you get an Error message saying that you must first add a mobile phone number to your profile, then you should do that now.
Step 3: Complete App Setup and Enter Keys into the Spreadsheet
You App has four tabs: Details, Settings, Keys and Access Tokens, and Permissions. Under Details, make sure that the app's access level is set to "Read and Write", and if not, change that under the Permissions tab.
Under the Keys and Access Tokens tab, use the button to "Create my access token." This will authorize your app to interface with your account. (I know, it seems redundant.)
Then, copy and paste the Consumer Key (API Key) and Consumer Secret (API Secret) from that tab into the green cells under Step 3 in your spreadsheet. (Note: The Consumer Key and Secret are not the same thing as the Access Token and Access Secret.)
Step 4: Locate your Google Spreadsheet's "Project Key"
This is your spreadsheet's unique ID within Google. To find yours, first open "Tools -> Script Editor..." to bring up the Script Editor. In the Script Editor, open "File -> Project Properties", and locate your "Project key" in the table that you'll see there.
Copy and paste that Project key into the green cell under Step 4.
Step 5: Add "Callback" Value to Twitter App
After completing Step 4, the red cell under Step 5 should automatically change to include your Project key as part of a URL. If not, or if you accidentally delete it, the URL follows a simple formula:
https://script.google.com/macros/d/_<YOUR PROJECT KEY>_/usercallbackGo back to your Twitter app's Settings tab and paste that URL into "Callback URL" field.
Step 6: Select a Data Sheet and Generate a Preview of its Output
Select a data sheet from the drop down under Step 6, and from the "Bot" menu in your Spreadsheet, select "Generate Preview". (Each of the four options has specific setup instructions below, but they're all pre-populated with sample content for this setup step.)
Switch to the "Preview Output" sheet to see 15 sample tweets generated from the selected data sheet. You can edit these data sheets to your own content now, or you can wait until the rest of the setup is complete.
Generating this preview will require you to authorize the scripts in this spreadsheet, so you should agree to grant it permission if prompted.
Step 7: Test Twitter Authorization
You're almost done! From the "Bot" menu above, select "Send a Test Tweet". If everything has been set up correctly, you should see a popup inviting you to authenticate your app with your Twitter account. It's pretty easy. Follow the link, click authorize, then close the new tab when it says. "Success!"
Re-run Send a Test Tweet, and check your timeline. Hopefully it worked!
Step 8: Set Post Timing
Decide how often you want your bot posting, and select an option from the dropdown under Step 8. Unfortunately, these are the only options, and the actually timing is to some extent subject to Google's whims. You won't, for example, be able to specify your bot to post at exactly 10:34 every day.
Step 9: Start it up!
If everything has gone well so far and your data sheet is populated with your content, then you're ready to start sending out tweets. Select "Start Posting Tweets" from the Bot menu in your spreadsheet. If ever you decide to stop your bot, then use the "Stop Posting Tweets" option under the Bot menu.
You can change the data sheet selection and edit the data sheet contents without stopping the tweeting. It will simply use the updated setting whenever it next attempts to send a tweet. You will, however, have to stop and restart the posting if you want to change the timing.
"Select from Rows" and "Select from Columns" Setup
These two data sheets are the same, just oriented differently. Each is populated with a nursery rhyme to give you a sense of how it's going to build the tweet. If you're upgrading your bot from my SSBot version 0.3, you'll want to use "Select from Rows" to paste in your vocabulary from the earlier sheet.
If you want to make a bot that posts randomly from pre-composed messages, use the "Select from Columns" and paste all of your messages into a single column.
You're welcome to add notes or labels to the surrounding rows or columns. For both of these sheets, the script just expects the first potential value (or top-left value) to be in cell B5, so just make sure your tweetable text starts there.
"Markov" Setup
This data input sheet scans in the text it finds in cell B5 and following and then generates tweets by running them through a very simple Markov chain algorithm. The included corpus in this sheet is the entire text of Sense and Sensibility, so run "Generate Preview" to see the sort of thing it's capable of.
You can include any text you want, quite a lot of it, and it can occupy as many rows as it needs to following B5. Just note that this algorithm takes a little longer than the others to generate each tweet.
"*_ebooks" Setup
The _ebooks setup is a little more specialized, and a little less reliable at this point. It has it's own set up steps which are hopefully pretty easy to follow:
In a nutshell, it's basically the same Markov algorithm that the other sheet uses, but it uses the archive sheet from a TAGS archive for its content. So if you want to generate Markov nonsense based on a specific user's tweets, set the search parameter in your TAGS archive to, for example, "from:zachwhalen".
You do have two additional options you can set in the _ebooks setup: whether or not to exclude hashtags and mentions. Darius's recommendations for bot etiquette state that a bot should not use things like event hashtags because that could potentially derail or distract from people who are actually using that hashtag in good faith. I agree with this principle. On the other hand, hashtags are also used to express certain flavors of irony or other sentiments ("#blessed #happy #tcot"), and that sentiment is probably an important part of the language you want to capture in your bot.
It's up to you, but I still think it's safer to just exclude hashtags. Maybe in a future version I'll let you specify only certain hashtags to strip out.
Mentions (@'s) are also excluded by default, but can be re-enabled. Again, it's generally considered bad form to annoy people with your bot, and unsolicited @'s can be annoying. Too many unsolicited mentions will also get your account suspended, as I learned with @ClearCongress.
But if you really want to leave them in, then you are welcome to do so at your own risk.
And that's all there is to it. Again, I'm not a particularly good programmer, so you may find that something here doesn't work. In that case, let me know and I can try to fix it. Similarly, if you can think of ways to improve it, please tell me!
I do have some more ideas planned that I may yet implement, and if I do so, I'll probably do some version tracking with github or find some other way to release it. Until then, consider this still a quick and dirty solution to getting started with a Twitter bot and creative computing more broadly.
And finally, if you do get this working, please tell me about your bot! I'm trying to keep a list so I can maybe inform you about future upgrades or bug fixes.
Word Count: 2186