Tweetit - a simple bulk tweeter using twitter APIs and twitter4j

Tweetit is a pretty simple java based command-line bulk tweeter application capable of automatically tweeting, retweeting and cloning existing tweets from twitter stream. Tweetit was primarily created for the ones who work for twitter campaigns fighting for a good cause. This application can be further extended to schedule tweets using readily available scheduler tools that come pre-installed with any operating system. It may also be useful for product marketing and sales announcements using a trending hashtag to get maximum reach.

I’m thankful to twitter4j and twitter APIs without which Tweetit could not have been created. Tweetit has been open sourced under Apache 2.0 license and hosted in github. Feel free to download the source from GitHub repository - Tweetit and play around.

Origin of Tweetit
        A super frustrated group of good-hearted people lost their patience waiting for the American government to finalize and publish a rule RIN:1615-AB92, also called H4EAD – a provision to provide work authorization for certain H4 spouses who have been backlogged heavily due to the unavailability of immigrant visas (green cards). They have been waiting for this rule to effect since 2012. Out of extreme frustration, this group made a decision in trackitt discussion thread to start running campaigns through various mediums. There were some from the community that sent emails to their local congress men, there were some who wrote post cards to USCIS office in Washington DC, there were some who sent fax to DHS and USCIS, there were some who started aggressive tweeting and finally there were some who met with USCIS directors & law offices to get updates and represent the whole community. The members of this community were separated by distance but unified by their thoughts and actions.

Out of all such campaigns, twitter campaign picked up a lot of steam after USCIS director Leon Rodriguez stated that he understands their frustrations and knows about the tweets and emails that are being sent. He further recommended to keep the momentum and noise high to get things done sooner. After listening to his suggestions, this community started working more towards their campaigns in which twitter became the primary medium of expression. This created a need for a simple bulk tweeting application that will help everyone to work more towards this good cause.

Capabilities
Tweetit is capable of

• Searching tweets under a specific hashtag from twitter stream and retweeting them back in your timeline
• Searching tweets under a specific hashtag from twitter stream, cloning the searched tweets and tweet them to your timeline as new tweets. I call this cloning!!
• Tweeting status messages and pictures that can be picked from a source of data, currently being a spreadsheet. The pictures need not be embedded in the spreadsheet but just an absolute path (reference) to pictures in your hard drive has to go in the spreadsheet

Being Ethical
        Twitter is a wonderful social medium through which voices of unheard and unseen can be listened to. Social media listening tools monitor and measure trends of tweets to learn and aid organizations to make informed decisions. Campaigns take place in twitter to express support and hate, likes and dislikes, agreements and disagreements to spread the cause, news and views. Therefore, it is not right to spam such a useful social medium and disrupt the system. It is indeed not ethical to do it.

Twitter officially encourages everyone to build tools and applications over the features it provides. However it throttles the traffic based on various measures so that a higher volume traffic source does not choke a lower volume traffic source. Twitter allows a maximum of 2400 updates (includes tweet and retweet) per day and it further breaks down the limits per 15 minute window - https://support.twitter.com/articles/15364-twitter-limits-api-updates-and-following. Some of the known throttling mechanisms that twitter already uses are IP based and APIs based. It has quotas per API per application. Users that are often flagged and suspicious are moved to a lower tier or sometimes even blocked permanently.

Tweetit application has been built completely being conscious about these principles. It neither tries to spam nor encourages you to do so. It has been built with just one good objective - to ease the life of twitter-heavy users that mainly run good-cause campaigns. It accomplishes this by pausing a minimum of 10 seconds in between tweets & retweets. Apparently, generous users can increase the interval between tweets but cannot bring it lower than the minimum allowed. This helps users two folds

• To be a good twitter user paving way for rest of the world to work for their respective needs and causes
• Do not fall under twitter’s radar-of-scrutiny and take the brunt of being labelled as a flagged-user

Tweetit Prerequisites

• Tweetit runs in any operating system that supports Java run time environment (>= version 1.6). Tweetit is not a web application and can be just run from the command-line or shell prompt using its executable jar file.
• Supports tweeting text and images. Currently it supports only JPEG (.jpg) images.
• It is not required to have Microsoft Office (or any other ports of it) installed but it will be good to have, if you would like to add and edit the contents of spreadsheet. Please note that Tweetit supports (.xls) spreadsheets but currently does NOT have the support for newer (.xlsx) spreadsheets yet.
• And lastly, if you have a basic technical ground or has a very basic exposure to java, it is pretty easy to catch up the rest of instructions and use this app

Tweetit will NOT need your Sign-in password but needs your OAuth keys to tweet on your behalf. It uses a special file called key file. This key file is expected to contain the user’s OAuth keys for twitter authentication. These keys can be generated at https://apps.twitter.com. OAuth keys are a secured way to access and post tweets on your behalf. Below steps will guide you to generate needed keys and access tokens. It's pretty simple to do and it will not take more than 15 minutes. Once created, these OAuth keys can be used forever to run tweetit. It is just an one time effort. Please note that, you will have the full control over your keys and contents of tweets. Tweetit does not and cannot misuse your keys. Neither it can snoop or mess with your tweet contents.

Generate OAuth keys
OAuth is a pretty widely used Open source authorization standard that any client application can use to get secure access to users resources without the need of their login credentials. Below is a onetime setup steps that has to be followed to generate OAuth keys from your twitter account. Once done, these keys can be used to run “tweetit”.

1) Go to https://twitter.com/settings/devices and add your phone number. Twitter validates your phone number by sending a verification code. Once done, UNTICK all the check boxes unless you want to receive twitter text notifications to your mobile. Kindly be aware that twitter does not allow you to generate OAuth keys if you do not have a phone number added to your profile. A screenshot that shows all text related settings of mobile deselected.



2) Go to https://apps.twitter.com/ and create a new application through which you can create keys. Please note that the application name should be globally unique. Click “Create your Twitter application” after accepting the Developer agreement. Below is a screen capture of the details after having entered.



3) Once your application is successfully created, navigate to “Permissions” tab/link and provide “read and write” permission as shown below. This ensures that your keys can be used by Tweetit to post tweets on your behalf.



4) Click “Keys and access tokens” tab/link to display application settings including your consumer key and consumer secret. Scroll down to “Your Access token” and click “Create my Access Token” to create access tokens.



5) Now you got all the OAuth keys and access tokens that are needed. The values you just got for a) Consumer Key b) Consumer Secret c) Access Token and d) Access Secret
need to be copied to a text file called keyfile.txt as shown below. A sample keyfile.txt can be downloaded from github repository https://github.com/metallicatony/tweetit/blob/master/src/main/resources/keyfile.txt. If you find that the contents of the downloaded keyfile are all present in the same line, it is because of End of line conversion differences between unix and windows. Kindly make the file look like the below screenshot as a first step. Then replace the respective values of keys and tokens generated from the previous step, in place of dummy values marked as ABCD, EFGH, IJKL and MNOP of the downloaded keyfile.



Download other needed resources
Below is a list of steps that need to be followed to have all the needed resources in place before running “tweetit”. Please note that all resources are hosted in github.

• Create a directory called C:\tweetit and move the above created “keyfile.txt” there if not done before. Though you have a choice to place the keyfile.txt anywhere in your harddrive and refer the full path while running “tweetit”, it is prudent to place it under C:\tweetit\


• Download tweetit jar application and save in the same directory location. The jar can be found here https://github.com/metallicatony/tweetit/blob/master/target/tweetit-1.1.jar?raw=true


• As said before, tweetit picks the contents for your tweets from a spreadsheet (*.xls). The spreadsheet (.xls) should have the message content of your tweets and optionally it can contain the path to the images in your computer that you want to upload as part of your tweet. Please download a template of the spreadsheet from the repository https://github.com/metallicatony/tweetit/blob/master/src/main/resources/tweets.xls?raw=true and place it under C:\tweetit\


• Download a sample picture https://github.com/metallicatony/tweetit/blob/master/src/main/resources/H4EAD_Banner_Woman.png along with the above spreadsheet and save it under the same directory C:\tweetit\


• This has been already covered by the last step from the previous section. Double check whether you already got keyfile.txt after merging in your keys and tokens into it. This keyfile needs to go under the same directory C:\tweetit\
.

After the above steps are complete, you are now ready to bulk tweet using “tweetit”.

Tweetit Commands
Below are some sample commands that you can use from a windows command prompt to run tweetit. The same set of commands can be used if you are using from Linux or any unix variant operating systems too. The only change will be the referred absolute path in the command. Before you try out below commands, please navigate to tweetit’s home directory C:\tweetit\

Search & Retweet
The below command pulls a recent 250 tweets with hashtag #H4EAD and retweets the same. Kindly note that by default tweetit retweets the latest 500 tweets. The retweets are done every ~12 seconds

java -jar tweetit-1.1.jar --retweet --keyfile "C:\tweetit\keyfile.txt" --search "#H4EAD" --count 250 --every 12 

A screenshot of the above command in action



Clone Tweets
The below command pulls a recent 250 tweets with hashtag #H4EAD ,clones them and tweets them as new tweets to your timeline. Kindly note that by default tweetit pulls the latest 500 tweets but the tweets are done every ~12 seconds.

java -jar tweetit-1.1.jar --clone --keyfile "C:\tweetit\keyfile.txt"

A screenshot of the above command in action



Tweet using Spreadsheet contents
The below command pulls the contents of the spreadsheet that you downloaded and tweets them to your timeline. The path to the spreadsheet can be explicitly mentioned as below. If not, it assumes a default path C:\tweetit\tweets.xls

java -jar tweetit-1.1.jar --tweet --keyfile "C:\tweetit\keyfile.txt" --every 10 --spreadsheet "C:\tweetit\tweets.xls"

A screenshot of the above command in action



Tweetit is really helpful when you want to tweet and retweet bulk on a daily basis. It can save you a lot of time by automatically tweeting with a simple run of a command and thereby you can focus on your day to day activities without much intervention.