Tutorial: creating a Twitter bot

TL;DR

Although it sounds like a lot of effort, creating a Twitter bot is actually really easy! This tutorial, along with some simple tools, can help you create Twitter bots that respond when they see certain phrases, or that periodically post a tweet. These bots work with Markov chains, which can generate text that looks superficially good, but is actually quite nonsensical. You can make the bots read your favourite texts, and they will produce new random text in the same style!

All code is available on GitHub

The examples on this page use a custom Python library, written by Edwin Dalmaijer (that’s me). This library is open source, and available on GitHub for free. You are very welcome to download and use it, but I would like to kindly ask you to not use it for doing evil stuff. So don’t start spamming or harassing people!

• GitHub page
• Direct download (.zip)

Step 1: Create a Twitter account

This is an easy step, no code here yet. Simply follow the instructions to create a new Twitter account.

• Go to Twitter’s sign-up page.
• Fill out all details, and make sure to include your phone number. This is a requirement for remote access, and you will need that to make the Twitter bot work.

Step 2: Create a Twitter app

Not all Twitter accounts are created equal. You will need developer access to yours, if you want to use it via a Python script.

• Go to apps.twitter.com
• Click on the ‘Create New App’ button.
• Fill out the details on the form. You have to give your app a name, description, and website (this can be a simple place holder, like http://www.example.com)
• Read the Developer Agreement, and check the box at the bottom if you agree. Then click on the ‘Create your Twitter application’ button.

Step 3: Keys and access tokens

This is an important step, as you will need the keys and access tokens for you app. They allow you to sign in to your account via a Python script.

• After creating your new app, you were redirected to its own page. If you weren’t, go to apps.twitter.com and click on your apps name.
• On the app’s page, click on the ‘Keys and Access Tokens’ page.
• At the bottom of this page, click on the ‘Create my access token’ button.
• Make sure you make note of the following four keys, as you will need these later. (Just leave the tab open in your browser, or copy them to a text file or something. Make sure nobody else can access them, though!)

Getting a Python Twitter library

Before being able to log into Twitter via Python, you need a Python wrapper for the Twitter API. There are several options out there, and I haven’t excessively researched all of them. This guide will go with Mike Verdone’s (@sixohsix on Twitter) Python Twitter Tools library, which is nice and elegant. You can also find its source code on GitHub.

• If you don’t have it already, you need to install setuptools. Download the ez_setup.py script, and run it with the Python installation you want to have it installed in.
• BONUS STEP: If you don’t know how to run a Python script, read this step. On Linux and OS X, open a terminal. Then type cd DIR and hit Enter, but replace DIR by the path to the folder that contains the ez_setup.py script you just downloaded. Next, type python ez_setup.py and hit Enter. This will run the script that installs setuptools. On Windows, the easiest thing to do is to make a new batch file. To do this, open a text editor (Notepad is fine). Now write “C:\Python27\python.exe” “ez_setup.py” on the first line, and pause on the second line. (Replace “C:\Python27” with the path to your Python installation!) Save the file as “run_ez_setup.bat“, and make sure to save it in the same folder as the ez_setup.py script. The .bat extension is very important, as it will make your file into a batch file. Double-click the batch file to run it. This will open a Command Prompt in which the ez_setup.py script will be run.
• After installing setuptools, you can use it to easily install the Twitter library. On Linux and OS X, open a terminal and type easy_install twitter. On Windows, create another batch file, write “C:\Python27\Scripts\easy_install.exe” twitter on the first line, and pause on the second line. (Replace “C:\Python27” with the path to your Python installation!)
• If you did everything correctly, the Twitter library should now be installed. Test it by opening a Python console, and typing import twitter. If you don’t see any errors, that means it works.

Setting up

Time to get things ready for your Twitter bot script. You need to things: a dedicated folder to store things in, and the markovbot Python library. The markovbot library is written by me, and you can easily grab it off GitHub. You’re also very welcome to post any questions, issues, or additions to the code on GitHub.

• Create a new folder, and give it a name. In this example, we will use the name ‘TweetBot’ for this folder.
• Go to the markovbot GitHub page.
• Click on the ‘Download ZIP’ button, or use this direct download link
• Unzip the ‘markovbot-master.zip’ file you just downloaded.
• Copy the ‘markovbot’ folder into the ‘TweetBot’ folder.

Getting data

To establish a Markov chain, you need data. And lots of it. You also need the data to be in machine-readable form, e.g. in a plain text file. Fortunately, Project Gutenberg offers an excellent online library, with free books that also come in the form of text files. I’m talking about . (Please do note that Project Gutenberg is intended for humans to read, and not for bots to crawl through. If you want to use their books, make sure you download and read them yourself. Also, make sure that you have the right to download a book before you do it. Not all countries have the same copyright laws as the United States, where Gutenberg is based.)

• Download a book of your choice, for example Sigmund Freud’s Dream Psychology. Make sure to download the utf-8 encoded text file! (At the bottom of the list.)
• Copy (or move) the text file you just downloaded to the ‘TweetBot’ folder, and name it ‘Freud_Dream_Psychology.txt’.

Writing your script

You should have everything now: A Twitter account with developer’s access, a Twitter library for Python, the custom markovbot library, and some data to read. Best of all: You’ve organised all of this in a folder, in precisely the way it is described above. Now, it’s finally time to start coding the actual Twitterbot!

• Start your favourite code editor, and open a new Python script.
• Save the script in the ‘TwitterBot’ folder, for example as ‘my_first_bot.py’.
• Start by importing the MarkovBot class from the markovbot module you need:

• I’m assuming you are familiar enough with Python that you know what importing a library means. If you are not, maybe it’d be good to read about them.
• The next step is to initialise your bot. The MarkovBot class requires no input arguments, so creating an instance is as simple as this:

• The next step is important! Before he can generate any text, the MarkovBot needs to read something. You can make it read your Freud example book.
• The bot expects you to give him a full path to the file, so you need to construct that first:

• At this point, your bot is clever enough to generate some text. You can try it out, by using its generate_text method. This takes one argument, and three (optional) keyword arguments (but only one of those is interesting).
• generate_text‘s argument is the number of words you want in your text. Let’s try 25 for now.
• generate_text‘s interesting keyword argument is seedword. You can use it to define one or more keywords that you would like the bot to try and start its sentence with:

• That’s cool, but what about the Twitter part? Remember you generated those keys and access tokens? You’ll need them now:

• Replace each set of empty quotes (”) with your own keys and tokens (these should also between quotes).
• First note on the codes here: It’s actually not very advisable to stick your crucial and secret information in a script. Your script can be read by humans and machines, so this is a highly unsafe procedure! It’s beyond the scope of this tutorial, but do try to find something better if you have the time.
• Second note: Now that you are pasting your secret stuff into a plain script, make sure you paste it correctly! There shouldn’t be any spaces in the codes, and it’s really easy to miss a character while copying. If you run into any login error, make sure that your keys have been copied in correctly!
• Time for the bot to log in to Twitter:

• Only one more thing to do before you can start up the bot: You need to decide what your bot should do.
• There are two different things the MarkovBot class can do. The first is to periodically post something. This is explained further down.
• The second thing the MarkovBot class can do, is to monitor Twitter for specific things. You can specify a target string, which the bot will then use to track what happens on Twitter. For more information on the search string, see the Twitter API website.
• The target string determines what tweets your bot will reply to, but it doesn’t determine what the bot says. For that, you need to specify keywords. These can go in a big list, which the bot will use whenever he sees a new tweet that matches the target string. Your bot will try to find any of your keywords in the tweets he reads, and will then attempt to use the keywords he found to start a reply with. For example, if your target string is ‘#MarryMeFreud’, and your keywords are [‘marriage’, ‘ring’, ‘flowers’, ‘children’], then your bot could find a tweet that reads I want your flowers and your children! #MarryMeFreud. In this case, the bot would read the tweet, find ‘flowers’ and ‘children’, and it will attempt to use those to start his reply. (Note: He won’t use both words, this is a very simple hierarchical thing, where the bot will try ‘flowers’ first, and ‘children’ if ‘flowers’ doesn’t work.)
• In addition to the above, you can also have the MarkovBot add prefixes and suffixes to your tweets. This allows you to, for example, always start your tweet with a mention of someone (e.g. ‘@example’), or to always end with a hashtag you like (e.g. ‘#askFreud’).
• Finally, the MarkovBot allows you to impose some boundaries on its behaviour. Specifically, it allows you to specify the maximal conversational depth at which it is still allowed to reply. If you are going to use your bot to reply to people, this is something you really should do. For example, if your bot always replies to people who mention ‘@example’, they are likely to wish to talk to Edward Xample. It’s funny to get one or two random responses, but as the conversation between people and Edward Xample continuous, you really don’t want your bot to keep talking to them. For this purpose, you can set the maxconvdepth to 2. This will allow your bot to reply only in conversations with no more than two replies.

• The MarkovBot’s twitter_autoreply_start method can start a Thread that will track tweets with your target string, and automatically reply to them using your chosen parameters.
• If you want to stop your MarkovBot from automatically replying, you can call its twitter_autoreply_start method.
• How quick your bot replies to tweets is highly dependent on how many tweets are posted that match your target string.

• Another thing the MarkovBot can do, is to periodically post a new tweet. You can start this with the twitter_tweeting_start method.
• The keywords, prefix, and suffix keywords are available for this function too. The keywords work a bit different though: For every tweet, one of them is randomly selected. You can also pass None instead of a list of keywords, in which case your bot will just freestyle it.
• One very important thing, is the timing. The twitter_tweeting_start method provides three keywords to control its timing: days, hours, and minutes. The time you specify here, is the time the bot waits between tweets. You can use all three keywords, or just a single one. If you don’t specify anything, the bot will use its default of one day.
• If you want your bot to stop, you can use the twitter_tweeting_stop method.

Spamming and trolling

Although Twitter bots can easily be used to spam and troll people, I kindly ask you not to do it. You gain absolutely nothing by doing it, and Twitter’s API is built in such a way that it automatically blocks accounts that do too much, so you will be shut down for spamming. Nobody likes spammers and trolls, so don’t be one.

Conclusion

Creating a Twitter bot is easy! If you want to use my software to create your own, please do go ahead. It’s free and open, and this page lists the instructions on how to download it. I would love to hear about your projects, so please feel free to leave a comment with your story.

UPDATE: Join competitions with your bot!

Stefan Bohacek was kind enough to point out the existence of a monthly bot competition that he organises. Have a look at his Botwiki website to learn about this month’s theme, and how to compete.