Skip to main content


Latest Version: 2.0.0

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"


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 -");

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'"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())


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"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

function onTweet(tweetData) {
    this.log(format("%s - %s", tweetData.text, tweetData.user.screen_name));
}"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.


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

// Open stream"iot", onTweet);

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

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


The Twitter library is licensed under the MIT License.