Noob’s Guide #2: ReTweeting with your Twython Twitter Bot

Last week in this Noob’s Guide to Twython we covered setting up your Twython for the first time (installing Twython, authenticating with the Twitter API, and Tweeting your first Tweet from Twython). Now we’re going to begin exploring how you can use your Twitter bot to ReTweet.

Reasons to ReTweet

Though the very idea of having a bot automatically ReTweeting things has been corrupted by the mindless Twitter accounts that distribute nothing but spam, the use of a ReTweet bot is not actually against any of Twitter’s terms and conditions. If executed correctly. This is because there’s a whole wealth of value to having a ReTweet bot.

All Twitter cares about is spam. But when not performed for spam, a ReTweet can be a powerful thing. It can be used to promote certain events or news across a wider audience. People’s incentive to follow a ReTweet bot may be to receive Tweets regarding a subject, but wouldn’t want to Follow the original poster on Twitter as they are only interested in very specific Tweets and not everything that user has to say. People can use the hashtag ReTweet bots to follow the hashtag within their stream, so they don’t have to access it via a separate search just to browse.

Other automated ReTweet possibilities could include anyone mentioning your domain or brand name. Of course, you would definitely have to create a negative keyword list to filter out any negative sentiment being expressed toward your brand. Wouldn’t want to be ReTweeting abusive messages about yourself! How unfortunate would that be!

ReTweets are a great method of content discovery, and I can’t tell you how many times I’ve Followed users from seeing a ReTweet of their status. Their Tweet gained my interest, I checked it out and it inspired me to Follow them for more! Similarly, if there’s a big event going on with a promoted hashtag, you could have each Tweet containing that hashtag automatically be ReTweeted via your account. So those at the event can just Follow the user to discover everything that’s going on at the event, and network with other Twitter users who are attending.

Maybe you only want the bot to share only certain hashtagged Tweets from those Following you on Twitter, so you can Follow the account as a consumer or a provider. People will either Follow you because they want the latest news regarding the hashtagged subject, or because they want you to ReTweet their news.

So as you can see, depending on how you are ReTweeting, and for what purpose, a ReTweet bot can be a great central hub of information and a network for open communication and discovery.

Unfortunately, having shared with you now just a tiny portion of the possibilities of a ReTweet bot, there are still going to be some who are only looking to build a bot with the intention of spamming people. This tutorial then might seem a little like handing a child a loaded gun. But I’m going to trust here that you’ll be responsible enough to use this tutorial example to learn and not to go spamming 100 ReTweets an hour. Twitter will ban you. And nobody likes a spammer.

Your First Unnecessarily Difficult ReTweet

So let’s test out this whole ReTweet thing by ReTweeting a single Tweet. Go find yourself something that you want to ReTweet and retrieve it’s status ID. (For the sake of saving a lot of people from getting mildly irritated by your Twitter bot testing, I do suggest you using your own Twitter accounts to test and play with. If you don’t already have another Twitter account, make one, or alternatively you can play with the corpse of an abandoned account that hasn’t had any activity for years. But if it returns as an angry zombie, don’t blame me!

You can find the status ID of a Tweet by clicking on the Tweet so it brings it up as its own page. (Twitter’s a little fiddly. You may want to click “Expand”, and then once the Tweet has expanded, click on “Details”. Once the page is loaded, there you can find the status ID in the page’s URL in the address bar. It should look something like this:

https://twitter.com/YOUR_USERNAME/status/TWEET_STATUS_ID

Replace TWEET_ID with that long number. That long number is the ID. (Your keys, tokens and secrets should still be kept as your actual keys, tokens and secrets throughout all tutorials obviously, as we covered in the tutorial last week.)

from twython import Twython

app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
oauth_token = "YOUR_OAUTH_TOKEN"
oauth_token_secret = "YOUR_OAUTH_TOKEN_SECRET"

twitter = Twython(app_key, app_secret, oauth_token, oauth_token_secret)

#ReTweeting by ID of the Tweet
twitter.retweet(id = "TWEET_ID")

Now check your Twitter profile! Has it ReTweeted successfully?

Well, that’s all good and well, but it’s hardly going to be an automatic process if you’re going to be inserting the ID of each Tweet you want to ReTweet by hand each time. Thankfully, you won’t have to!

Dissecting the Search Query

#Import TwythonError now too!
from twython import Twython, TwythonError

app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
oauth_token = "YOUR_OAUTH_TOKEN"
oauth_token_secret = "YOUR_OAUTH_TOKEN_SECRET"

twitter = Twython(app_key, app_secret, oauth_token, oauth_token_secret)

#Setting Twitter's search results as a variable
search_results = twitter.search(q="SOMETHING", count=10)
try:
    for tweet in search_results["statuses"]:
        twitter.retweet(id = tweet["id_str"])
except TwythonError as e:
    print e

For someone who’s completely new to Python, picking this up for the first time, that may just look like a strange block of code right now. So let’s break it down to the basics.

Let’s start with search_results. We can read on Twitter’s REST API documentation that search takes a required parameter of q (for query). After all, to use the search results you do actually need to be searching for something. In fact, you can see this for yourself when you do search for something on Twitter. When I perform a search for “southend” (the town in which we here at Silkstream are based – Southend, Essex), you can see in the URL that the search is taking a parameter of q=southend.

So in our code, if we wanted to access the search results for “southend”, we would type:

search_results = twitter.search(q="southend", count=10)

And all that count is for is just to specify how many results we would like to return. In this case: Twitter, I would like exactly ten search results back based on the query “southend” please!

The count is an optional parameter, but a very useful one. Otherwise you might be biting off more than you can chew…

Other optional search parameters include:

• geocode – e.g. “longitude, latitude, radius”
• lang – restricts Tweets to a certain language
• locale – specifies the query’s language
• result_type – return mixed, recent or popular Tweets
• until – returns Tweets generated before the given date
• since_id – returns only Tweets more recent than the given one’s ID
• max_id – returns only Tweets older than the given one’s ID
• include_entities – the entities node will be disincluded when set to false

As you can see, some are more useful than others depending on what it is you’re boiling things down to.

Automatically ReTweeting based on Search Query

So what about:

try:
    for tweet in search_results["statuses"]:
        twitter.retweet(id = tweet["id_str"])
except TwythonError as e:
    print e

In the above bit of Python code here we are asking Twitter to try, for every Tweet’s status in our search results for “SOMETHING”, to ReTweet each Tweet that comes up for that search. Notice how instead of:

twitter.retweet(id = "TWEET_ID")

we are now using:

twitter.retweet(id = tweet["id_str"])

This is because, as you so cleverly pointed out earlier, we can’t sit there all day manually entering the IDs of every Tweet we want to ReTweet. It would be quicker to just use Twitter itself if we were to do that. It’s just plain silly.

Instead we are telling Twitter to identify the ID of each Tweet that pops up in our search results, and insert its ID there as a string. That’s the difference between id and id_str. To set it as a non-string (or an integer) would mean that you are giving the ID a numerical value, which we don’t want. So we want the number to be enclosed in quotation marks, indicating that it is a string. As we would if we were to be typing out the Tweet’s ID to be ReTweeted manually. Which we won’t do, because it’s just plain silly.

And what about that TwythonError?

What does TwythonError do? This is just a generic “catch all” Error exception that will display the issue, should an error occur. For example, if it returns a HTTP status code of 403 in the console, the text will display as “Forbidden” and explain that, though the request was understood, it has been refused or access has not been allowed. You may find that this is due to you having hit a limit of some kind.

Filtering search queries to ReTweet

Sometimes there are words that you will want to prevent from automatically ReTweeting, such as curse words, irrelevant words or words that express a certain sentiment. Or we have a multiple choice of words that we want Twitter to search for, such as a variation of spellings for a keyword and such.

from twython import Twython, TwythonError

app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
oauth_token = "YOUR_OAUTH_TOKEN"
oauth_token_secret = "YOUR_OAUTH_TOKEN_SECRET"

#Let's gather a list of words we DON'T want to RT
naughty_words = [" -RT", "Boston", "football", "charlotte", "amos"]
#And a list of words we WOULD like to RT
good_words = ["southend", "southendonsea", "southend on sea"]
#OR is Twitter's search operator to search for this OR that
#So let's join everything in good_words with an OR!
filter = " OR ".join(good_words)

# The - is Twitter's search operator for negative keywords
# So we want to prefix every negative keyword with a -
blacklist = " -".join(naughty_words)

#And finally our list of keywords that we want to search for
#This will search for any words in good_words minus any naughty_words
keywords = filter + blacklist

twitter = Twython(app_key, app_secret, oauth_token, oauth_token_secret)

#This time we want to set our q to search for our keywords
search_results = twitter.search(q=keywords, count=10)
try:
    for tweet in search_results["statuses"]:
        try:
            twitter.retweet(id = tweet["id_str"])
        except TwythonError as e:
            print e
except TwythonError as e:
    print e

So again, let’s take a closer look at everything new we’ve added to our Twitter bot.

So we’ve made an example list of naughty_words, and since for this example we want to be ReTweeting Tweets about Silkstream’s hometown of Southend in Essex, I’ve included negative keywords like “boston”, “charlotte” and “amos” as they tend to be popular keywords used in Tweets containing “Southend” but SouthEnd (or South End) in the United States rather than in Essex, UK.

I’ve also added “football” just for this example (I don’t really care too much about football news myself…) and I’ve also added at the beginning ” -RT”. I don’t want to be ReTweeting ReTweets so it’s important for me to add that. You may also notice that I’ve prefixed it with a ” -“, which as we know is the negative keyword search operator on Twitter. This is because when we joined the naughty_words for our blacklist, it does just that. It joins each item in that list. And since ” -RT” is our first item, it doesn’t add a ” -” to the beginning. So we’ve had to do that manually. Since it’s a one off and the program is just for us, it’s just easier to do it manually for now.

filter = " OR ".join(good_words)
blacklist = " -".join(naughty_words)
keywords = filter + blacklist

We’re using Twitter’s OR operator to join our good_words so that Twitter knows that we’re searching for any Tweet that contains “southend OR southendonsea OR southend on sea”. Which is why our ” OR ” has spaces before and after the OR. So it doesn’t search for “southendORsouthendonseaORsouthend on sea”.

Likewise, as we already covered, our blacklist joins every item in our naughty_words by a ” -“, with a space before the “-” but not after. So Twitter will search for “-RT -Boston -football -charlotte -amos”, and not “-RT-Boston-football-charlotte-amos”.

And finally, our keywords list is just a concatenation of our filter and our blacklist so if we set our search query to keywords, Twitter will be searching for:

southend OR southendonsea OR southend on sea -RT -Boston -football -charlotte -amos

Awesome. So our Twitter ReTweet bot right now should look a little like this:

from twython import Twython, TwythonError

app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
oauth_token = "YOUR_OAUTH_TOKEN"
oauth_token_secret = "YOUR_OAUTH_TOKEN_SECRET"

naughty_words = [" -RT", "Boston", "football", "charlotte", "amos"]
good_words = ["southend", "southendonsea", "southend on sea"]
filter = " OR ".join(good_words)
blacklist = " -".join(naughty_words)
keywords = filter + blacklist

twitter = Twython(app_key, app_secret, oauth_token, oauth_token_secret)

search_results = twitter.search(q=keywords, count=10)
try:
    for tweet in search_results["statuses"]:
        try:
            twitter.retweet(id = tweet["id_str"])
        except TwythonError as e:
            print e
except TwythonError as e:
    print e

Next week, we’ll be looking to tinker a little bit more with our Twitter ReTweet bot and really see what this baby can do!

The Noob’s Guide to Twython – Part 1:

How To Get Going With Twython

The Noob’s Guide to Twython – Part 3:

Random Tweets with Twython