Twitter

The Twitter class allows you to Tweet and to stream results from Twitter’s streaming API.

Note You can only have one instance of the streaming API open per Twitter account per Twitter App.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To include this library in your project, add

#require "Twitter.agent.lib.nut:2.0.0"

at the top of your agent code

Create a Twitter App

In order to use the Twitter library, you’ll first need to create a Twitter app.

Class Usage

Constructor: Twitter(apiKey, apiSecret, authToken, tokenSecret[, debug])

The Twitter constructor takes five parameters. The first four are your Twitter app’s OAuth credentials. You can find these in the ‘Keys and Access Tokens’ section of your app in the Twitter Dev Center.

The constructor can also take an optional fifth parameter: a debugging flag. When the debug flag is set to true, the class will log information to the device logs. When it is set to false it will not. It is recommended that you leave the flag set to true, and this is the default setting.

#require "Twitter.agent.lib.nut:2.0.0"

const API_KEY = "YOUR_API_KEY";
const API_SECRET = "YOUR_API_SECRET";
const AUTH_TOKEN = "YOUR_AUTH_TOKEN";
const TOKEN_SECRET = "YOUR_TOKEN_SECRET";
twitter <- Twitter(API_KEY, API_SECRET, AUTH_TOKEN, TOKEN_SECRET);

Class Methods

tweet(tweetData[, callback])

You send a Tweet with the tweet() method. The first parameter, tweetData, can be one of two things: a string containing the text of the tweet, or a table representing the Tweet. In most cases, simply passing a string should be sufficient:

twitter.tweet("I just tweeted from an @electricimp agent - bit.ly/ei-twitter.");

By passing a table instead of a string, we can include additional Tweet fields such as geolocation, reply_to, etc. The table must include the key status, which is the text of the Tweet:

// Reply to every Tweet that mentions 'electricimp'
twitter.stream("electricimp", function(tweetData) {
    local tweetTable = {
        "in_reply_to_status_id" : tweetData.id_str,
        "status" : format("@%s Thanks for saying hello! (tweeted at %i)", tweetData.user.screen_name, time())
    };

    twitter.tweet(tweetTable);
});

stream(searchTerm, callback[, onError])

You can get near instantaneous results for a Twitter search by using the stream() method. To open a stream, you need to provide two values: a string containing the text you want to search for and a callback function that will be executed whenever a new Tweet comes into the stream. The callback takes a single parameter: a table into which the Tweet and associated data will be placed. The table has two keys: text (the text of the Tweet as a string) and user (a table containing information about the user who posted the Tweet):

function onTweet(tweetData) {
    // Callback function to log the Tweet
    // and who Tweeted it (there is a LOT more info in tweetData)
    this.log(format("%s - %s", tweetData.text, tweetData.user.screen_name));
}

// Start the stream
twitter.stream("electricimp", onTweet);

An optional third parameter can be passed to stream(): onError. This parameter is a callback function that takes a single parameter of its own, errors, which is an array of tables, each with the following format:

{ "code" : errorCode,
  "message" : "description of the error" }

If defined, onError will be called in the event of the Twitter stream returning an error.

function onError(errors) {
    // Log all the error messages
    foreach (err in errors) {
        server.error(err.code + ": " + err.message);
    }

    // Close the stream then re-open it
    twitter.closeStream();
    twitter.stream();
}

function onTweet(tweetData) {
    this.log(format("%s - %s", tweetData.text, tweetData.user.screen_name));
}

twitter.stream("electricimp", onTweet, onError);

If the stream() method’s onError parameter is omitted, the Twitter class will automatically try to reopen the stream when an unexpected response is encountered. If the onError parameter is included, you are responsible for reopening the stream in the onError callback.

closeStream()

The closeStream() method will close the stream created by the stream() method.

// Open stream
twitter.stream("iot", onTweet);

// Only stream data for 10 seconds, so wake after
// that period and close the stream
imp.wakeup(10, function() {
    twitter.closeStream();
});

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release
1.1.0	GitHub	Bug fixes
1.1.1	GitHub	Minor code improvements; bug fixes
1.2.0	GitHub	Major code improvements
1.2.1	GitHub	Update error-handling code
2.0.0	GitHub	Fixed a bug with reopening random streams; updated library name to meet requirements of new naming scheme

License

The Twitter library is licensed under the MIT License.