/birdbot

A Twitter bot API made in Node.js to post, retrieve and engage with tweets

Primary LanguageJavaScriptMIT LicenseMIT

NodeJS - Birdbot 1.0

A Twitter bot made in Node.js to post, retrieve and engage with tweets. This API was created to be executed by a time-based task runner like cron-job, however you could run it locally and call endpoints by yourself.

What can i do with birdbot?

  • Retweet
  • Like
  • Write tweets
  • Search tweets and get result as JSON

Index

Create a Twitter APP and get your keys

Before use twitter API, even by a third-party like birdbot, you will need to create an Twitter APP for the Twitter account you'd like automate.

There is a little process to create an app, you will be requested to answer some questions on the web page where you'll create your app, the questions are about your purpose to use the API. Try to save your answers, because maybe you will have to answer again replying an email sent from Twitter.

After that process you will be able to generate your keys. They look like this:

CONSUMER_KEY = XXXXXXXXXXXXXXXXXXXXX

CONSUMER_SECRET = XXXXXXXXXXXXXXXXXXXXXXXXX

ACCESS_TOKEN_KEY = XXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX

ACCESS_TOKEN_SECRET = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx

Once you have keys in your hands, let's install birdbot.

Install

1 - Create an .env file in the project root folder

After clone the repository, it's time to create the .env file with your app keys information like this one:

CONSUMER_KEY = XXXXXXXXXXXXXXXXXXXXX
CONSUMER_SECRET = XXXXXXXXXXXXXXXXXXXXXXXXX
ACCESS_TOKEN_KEY = XXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX
ACCESS_TOKEN_SECRET = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx

2 - Run NPM INSTALL to install all dependencies

npm install

3 - Run NPM START to start server

npm start

OBS. It will start server on port 3004, you can change this param in the config/config.js file.

module.exports = {
	'port': process.env.PORT || 3004
}

Operators

Operators are the properties you can use in request body, to create your custom query, it is like a query language.

  • hashtag (string)
  • mention (string)
  • from (string)
  • filter (string)
    • safe (Tweets marked as potentially sensitive removed)
    • media (image or video)
    • native_video (an uploaded video, Amplify video, Periscope, or Vine.)
    • periscope (Periscope video URL.)
    • vine (a Vine.)
    • images (links identified as photos, including third parties such as Instagram)
    • twimg (pic.twitter.com link representing one or more photos.)
    • links (linking to URL)
  • attitude (string)
  • except (string)
  • ask (boolean)
  • words (array of strings)
  • or (object, word or hashtags)
  • url (string)
  • recent (boolean)

The or operator requires attention to use. Its type may be word or hashtag

TYPE = WORD

{
  "or": {
    "type": "word",
    "keys": ["love", "hate"]
  }
}

TYPE = HASHTAG

{
  "or": {
    "type": "hashtag",
    "keys": ["love", "hate"]
  }
}

How to use operators

You will use operators as keys in the request you sent for endpoints, let's take a look:

OBS. You can't use "words" operator and "or" operator together in the same search, one of them will be ignored in case of use.

  • Tweets with hashtag superbowl
{
  "hashtag": "superbowl"
}
  • Tweets with profile mention @nasa and hashtag #apollo11
{
  "mention": "nasa",
  "hashtag": "apollo11"
}
  • From profile @nasa containing hashtag rocket
{
  "from": "nasa",
  "hashtag": "rocket"
}
  • Tweets with profile mention @spacex, hashtag #apolo and words rocket and launch
{
  "mention": "nasa",
  "hashtag": "apollo11",
  "words": ["rocket", "launch"]
}
  • Tweets with hashtag love, words "beautiful", "couple" and "in the air" except word hate
{
  "hashtag": "love",
  "words": ["beautiful", "couple", "in the air"],
  "except": "hate"
}
  • Containing “traffic” hashtag and asking a question.
{
  "hashtag": "traffic",
  "ask": "true"
}
  • Containing “fight” hashtag and with a negative attitude.
{
  "hashtag": "fight",
  "attitude": "negative"
}
  • Containing “book” hashtag and with a positive attitude.
{
  "hashtag": "book",
  "attitude": "positive"
}
  • Containing “book” hashtag and url containing Amazon
{
  "hashtag": "book",
  "url": "amazon"
}
  • Containing words "puppy" and "cute" and and links identified as photos, including third parties such as Instagram
{
  "words": ["puppy", "cute"],
  "filter": "images"
}
  • Recent tweets containing hashtag "dollar"
{
  "hashtag": "dollar",
  "recent": "true"
}

Containing either “love” or “hate” words (or both).

{
  "or": {
	"type": "word",
	"keys": ["love", "hate"]
  }
}

Containing either “love” or “hate” hashtags (or both).

{
  "or": {
	"type": "hashtag",
	"keys": ["love", "hate"]
  }
}

Retweet

Endpoint for retweet, assuming you're running it locally on port 3004

POST http://localhost:3004/api/retweet

Example Body :

{
  hashtag: "superbowl",
  mention: "nasa",
  words: ["one", "two"]
}

Response:

{
    "found_including_already_retweeted": 14,
    "retweeted": 2
}

Like

Endpoint for like tweets, assuming you're running it locally on port 3004

POST http://localhost:3004/api/like

Example Body :

{
  "hashtag": "guitar",
  "mention": "gibsonguitar"
}

Response:

{
    "found_including_already_liked": 22,
    "liked": 20
}

Write Tweet

Endpoint for write tweets, assuming you're running it locally on port 3004

POST http://localhost:3004/api/tweet

Example Body :

{
  "text": "This is my first tweet with birdbot",
}

Response (tweet object):

{
    "created_at": "Mon Dec 24 06:37:53 +0000 2018",
    "id": 1077090970502615000,
    "id_str": "1077090970502615041",
    "text": "Hey there",
    "truncated": false,
    "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
    },
    "source": "<a href=\"https://github.com/marcoshmendes/60daysguitar\" rel=\"nofollow\">60daysguitar</a>",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
        "id": 751283766300074000,
        "id_str": "751283766300073985",
        "name": "60Days Guitar Challenge",
        "screen_name": "60daysguitar",
        "location": "",
        "description": "Guitar every day for 60 days challenge. Join us posting one Twitter video playing, everyday with #60daysguitar hashtag and tag us. We'll post everything here.",
        "url": null,
        "entities": {
            "description": {
                "urls": []
            }
        },
        "protected": false,
        "followers_count": 2,
        "friends_count": 0,
        "listed_count": 0,
        "created_at": "Fri Jul 08 05:16:22 +0000 2016",
        "favourites_count": 10,
        "utc_offset": null,
        "time_zone": null,
        "geo_enabled": false,
        "verified": false,
        "statuses_count": 81,
        "lang": "pt",
        "contributors_enabled": false,
        "is_translator": false,
        "is_translation_enabled": false,
        "profile_background_color": "F5F8FA",
        "profile_background_image_url": null,
        "profile_background_image_url_https": null,
        "profile_background_tile": false,
        "profile_image_url": "http://pbs.twimg.com/profile_images/1059596261387571200/MwVRAFNq_normal.jpg",
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/1059596261387571200/MwVRAFNq_normal.jpg",
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/751283766300073985/1541463216",
        "profile_link_color": "1DA1F2",
        "profile_sidebar_border_color": "C0DEED",
        "profile_sidebar_fill_color": "DDEEF6",
        "profile_text_color": "333333",
        "profile_use_background_image": true,
        "has_extended_profile": false,
        "default_profile": true,
        "default_profile_image": false,
        "following": false,
        "follow_request_sent": false,
        "notifications": false,
        "translator_type": "none"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "is_quote_status": false,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "lang": "en"
}

Search and get result as JSON

Endpoint for retrieve tweets, assuming you're running it locally on port 3004

POST http://localhost:3004/api/search

Example Body :

{
  "hashtag": "guitar",
  "mention": "gibsonguitar"
}

Response (A collection of tweet objects):

{
    "statuses": [
    	{ Tweet Object },
        { Tweet Object },
        { Tweet Object },
        { Tweet Object },
        { Tweet Object },
        { Tweet Object }
    ]
}

Twitter Search API restrictions

This project uses Standard API, and results of search and retweets may be not totally reliable.

The Twitter API platform offers three tiers of search APIs:

Standard This search API searches against a sampling of recent Tweets published in the past 7 days. Part of the 'public' set of APIs.

Premium Free and paid access to either the last 30 days of Tweets or access to Tweets from as early as 2006. Built on the reliability and full-fidelity of our enterprise data APIs, provides the opportunity to upgrade your access as your app and business grow.

Enterprise Paid (and managed) access to either the last 30 days of Tweets or access to Tweets from as early as 2006. Provides full-fidelity data, direct account management support, and dedicated technical support to help with integration strategy.

Category Product Name Supported history Query capability Counts endpoint Data fidelity
Standard Standard Search API 7 days Standard operators Not available Incomplete
Premium Search Tweets: 30-day endpoint 30 days Premium operators Available Full
Premium Search Tweets: Full-archive endpoint Tweets from as early as 2006 Premium operators Available Full
Enterprise 30-day Search API 30 day Premium operators Included Full
Enterprise Full-archive Search API Tweets from as early as 2006 Premium operators Included Full