index.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Making a Twitter Bot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This Jupyter Notebooks shows the basics of making a Twitter bot with Python.\n",
    "\n",
    "This is a *very* heavily modified version of a [tutorial posted on the CUNY Academic Commons Blog](https://emerging.commons.gc.cuny.edu/2013/10/making-twitter-bot-python-tutorial/) by [Robin Camilla Davis](https://twitter.com/robincamille). I have taken some of the content and structure of the static blog post and ported it into a Jupyter Notebook Python environment. \n",
    "\n",
    "Here is Robin's introduction:\n",
    "\n",
    "> If there’s one thing this budding computational linguist finds delightful, it’s computers that talk to us. From [SmarterChild](http://en.wikipedia.org/wiki/SmarterChild) to [horse_ebooks](http://www.robincamille.com/2013-09-25-horse_ebooks/) to [Beetlejuice](http://muffinlabs.com/content/twitter-bot-info.html), I love the weirdness of machines that seem to have a voice, especially when it’s a Twitter bot that adds its murmur to a tweetstream of accounts mostly run by other humans.\n",
    "\n",
    "> As fun midnight project a few weeks ago, I cobbled together [@MechanicalPoe](https://twitter.com/MechanicalPoe), a Twitter bot that tweets Poe works line by line on the hour from a long .txt file. This slow-tweeting of text is by no means new—[@SlowDante](https://twitter.com/slowdante) is pretty popular, and so is[@CDarwin](http://www.metaburbia.com/darwin/), among many others. In case you want to make your own, here are the quick ‘n’ easy steps I took. This is just one way of doing it—shop around and see what others have done, too.\n",
    "\n",
    "\n",
    "## Contents\n",
    "\n",
    "* [Steps Towards an Ecology of Bots](#Steps-Towards-an-Ecology-of-Bots)\n",
    "* [Building a Basic Bot](#Building-a-Basic-Bot)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Steps Towards an Ecology of Bots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Creating a Twitter bot means creating a Twitter account AND a Twitter app. The account will belong to the bot and the app will be the mechanism you use to access the Twitter API and control the bot **WITH PYTHON.**\n",
    "\n",
    "Creating a Twitter bot is somewhat complicated because of quirks in the way Twitter manages verification. If you don’t already have a Twitter account, the process of creating a Twitter bot is pretty painless. If you already have a Twitter account, you have to do the *Twitter verification dance*.  Managing more than one Twitter account is a huge *pain in the ass* because you need a unique email address and mobile phone number for each account.  \n",
    "\n",
    "**Step 0)** *Note: This step is only for people who already have Twitter accounts.* Log into Twitter and visit [your account's mobile devices settings page](https://twitter.com/settings/devices). If you have a phone number associated with that account click “Delete my phone” to remove your mobile from number from this account. You are going to need that phone number for creating your bot account. Alternatively, you can get a free phone number from [Google Voice](http://voice.google.com) and use that for all the mobile phone verification BS.\n",
    "\n",
    "You are also going to need another email address for your new Twitter account. Twitter won’t let you create multiple accounts with the same email address. If you have a 2nd email address you’ll need to use it in step 1 below. If you don’t have another email address it is easy to [create one with gmail](https://accounts.google.com/signup). Alternatively, you can fake a new unique email address with Gmail by adding a `+` and something after your username. For example: `myemail+sometext@gmail.com`. Any messages addressed to this email will still show up in your inbox, but it behaves like a different email address. Give it a try!\n",
    "\n",
    "**Step 1)** Create a new Twitter account by visiting the [Twitter signup page](https://twitter.com/signup). This will be the Twitter account for your bot, so pick your username wisely. You will need to pick a name that hasn’t already been selected. Twitter *should* ask you for a mobile phone verification when you are creating the account, if it doesn’t you’ll have to add the phone number to your profile in [the new account's mobile devices settings page](https://twitter.com/settings/devices).\n",
    "\n",
    "**Step 2)** OK. Now that you have a Twitter **account** for your bot, you need to create a Twitter **application** so you can access the Twitter API **WITH PYTHON**. Twitter doesn’t allow people to connect to their API willy-nilly. Creating applications is Twitter's way of tracking (and controlling) who is programmatically accessing their network and data. In the world of big social media sites, heavily regulated access to APIs, networks, and data is a fact of life. \n",
    "\n",
    "Fortunately, creating an application on Twitter is very easy. Visit Twitter’s [Application Management page](https://apps.twitter.com/) and click the “Create New App” button. You’ll be shown the form shown below. Pick a name for your application and a description, this information is just for you it should be named something different (and more descriptive) than the account you just created. For the website, put the name of the course `http://annettevee.com/2015fall_computationalmedia/` into the website field.\n",
    "\n",
    "![New App information](images/create-application.png)\n",
    "\n",
    "**Step 3)** The last step for this part of the Twitter bot making process is to create the Access Token so your Python code can access the API. With your app created, you should see a dashboard page will all kinds of technical jargon about your Twitter app. You can ignore most of it for now and instead focus on the tab that says “Keys and Access Tokens.” The keys and access tokens behave like passwords so your computer can talk to Twitter’s computer. Twitter uses a protocol called [OAuth](http://oauth.net) for [“providing authorized access to its API](https://dev.twitter.com/oauth). You don’t really need to wor\n",
    "\n",
    "- Click the \"Keys and Access Tokens” tab\n",
    "- Click the “Create my access token button” at the bottom of the page.\n",
    "\n",
    "Once you have created your access tokens there will be **four** pieces of information you will need to put into your Python script so it can access the Twitter API:\n",
    "\n",
    "1. Consumer Key\n",
    "2. Consumer Secret\n",
    "3. Access Token\n",
    "4. Access Token Secret\n",
    "\n",
    "![Keys and Access Tokens Dashboard](images/access-keys.png)\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "\n",
    "Some other things to consider:\n",
    "\n",
    "- When you create a Twitter App you agree to the [developer agreement and policy](https://dev.twitter.com/overview/terms/agreement-and-policy) which has some complete bullshit within it. Basically, Twitter reserves the right to lock down your application and your account if their machine learning algorithms detect what they think is bad behavior.\n",
    "- Creating to many Accounts can lock-out your mobile phone number and prevent you from creating new accounts or apps. This comes from **personal experience**  and there is NO INDICATION if and when that happens. AND Twitter support is TOTALLY WORTHLESS. This is when creating another cell phone number with Google Voice is helpful.\n",
    "- You are not alone in thinking this is a HUGE PAIN IN THE ASS.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building a Basic Bot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you skim the code below, you'll notice *there isn't a lot of code* that is because a bulk of the work is being done by a Python library called [Tweepy](http://tweepy.readthedocs.org/en/latest/). Tweepy handles all the annoying plumbing work involved with connecting to Twitter and accessing specific functions like authentication, search or updating your status. You could access the Twitter API directly by issuing raw HTTP request to Twitters [REST endpoints](https://dev.twitter.com/rest/public), but why do that when someone has already a nice and easy to use interface to Twitter?\n",
    "\n",
    "The code below is for a very simple Twitter bot that just Tweets lines of Edgar Allen Poe's poetry. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Boilerplate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Import the python libraries we need to \n",
    "import time\n",
    "import tweepy\n",
    "\n",
    "\n",
    "# Be sure to paste your keys and tokens in here because it won't work otherwise!\n",
    "CONSUMER_KEY = \"INSERT KEY HERE\"\n",
    "CONSUMER_SECRET = \"INSERT SECRET HERE\"\n",
    "ACCESS_KEY = \"INSERT ACCESS KEY\"\n",
    "ACCESS_SECRET = \"INSERT SECRET HERE\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Oauth Dance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is the code the initates a connection to Twitter via the API using the Keys and Access Tokens we created earlier. Once we've gotten through the \"Oauth Dance\" we'll have an object, `the_twitter_api` that we can use to programmatically perform actions on Twitter. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Send our keys and tokens to Twitter\n",
    "credentials = tweepy.OAuthHandler(CONSUMER_KEY, CONSUMER_SECRET)\n",
    "credentials.set_access_token(ACCESS_KEY, ACCESS_SECRET)\n",
    "\n",
    "# Authenticate with Twitter to get access\n",
    "the_twitter_api = tweepy.API(credentials)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tweeting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are going to make a bot that tweets lines from classic texts. \n",
    "\n",
    "> I chose some texts from [Project Gutenberg](http://www.gutenberg.org/) and copied them into separate .txt files. (Maybe don’t choose a long-winded writer.) I ran a script over them to split them up by sentence and mark sentences longer than 140 characters. ([Link to chunking script.](https://github.com/robincamille/kicks-and-giggles/blob/master/poe-twitterbot-chunker.py)) There are other scripts to break up long sentences intelligently, but I wanted to exert some editorial control over where the splits occurred in the texts, so the script I wrote writes ‘SPLIT’ next to long sentences to alert me as I went over the ~600 lines by hand. I copied my chunked texts into one .txt file and marked the beginnings and ends of each individual text. ([Link to the finalized .txt file.](https://github.com/robincamille/kicks-and-giggles/blob/master/poe-lines.txt))\n",
    "\n",
    "So I am going to cheat a little bit here and just use the data files Robin already prepared. I downloaded Robin's pre-prepared text into a file in the `data/` directory.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# open Robin's Edgar Allen Poe data file and read every line into memory\n",
    "with open('data/thats-so-raven.txt','r') as filename:\n",
    "    lines = filename.readlines()\n",
    "\n",
    "# Tweet each line, then wait one minute and tweet another.\n",
    "# Note: this design means the bot runs continuously\n",
    "for line in lines: \n",
    "    the_twitter_api.update_status(status=line)\n",
    "    print(line)\n",
    "    time.sleep(60) # Sleep for 1 minute"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it you're done! That's all it takes to create a very simple Twitter bot."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are some other bot examples to play with:\n",
    "* Copora Tutorial Bot - A bot that uses [Corpora](https://github.com/dariusk/corpora) to generate text to tweet. [TODO] \n",
    "* Mayor of Pittsburgh Bot - A bot that translates the Mayor's tweets into Pittsburghese. [TODO]\n",
    "\n",
    "To make your own bot, you can start with this [python code for a very minimal bot](minimal-bot.ipynb) and modify it to cause whatever havoc or happiness you'd like.\n",
    "\n",
    "\n",
    "### Deploying you Botnet\n",
    "\n",
    "Making a bot is the easy part, making it run all the time requires a server that can continually run the bots. We have been creating and modifying these bots in Jupyter Notebooks which are fun and easy to use, but not great for deploying bots in the wild.\n",
    "\n",
    "If you have a server, the best way to deploy a bot you've written in a notebook is to save the Notebook as a python script (File -> Download As -> Python (.py) and run the scrip or set up a [CRON JOB](http://www.unixgeeks.org/security/newbie/unix/cron-1.html) to execute the python script periodically (if you've written the script to just execute one and quit rather than run continuously)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}