Streams Introduction¶

Twitter API exposes multiple type of streams. In their public API you will have access to:

The Sample Stream is a stream of tweets returning 1% of the tweets published in the world randomly

What is a stream?¶

A stream emit events that can be listened to. These events are triggered by messages received from Twitter.
You can find a list of the available events at the bottom of this page.

var stream = client.Streams.CreateTweetStream();
stream.EventReceived += (sender, eventReceived) =>
{
    Console.WriteLine(eventReceived.Json);
};
await stream.StartAsync("https://stream.twitter.com/1.1/statuses/sample.json");

Start, Pause and Stop¶

A stream can have 3 different states:

StreamState.Running - the stream is actively running and events are triggered when messages are received from Twitter. Technically, a socket is open with Twitter server until the stream stops.
StreamState.Stop - the stream is not running
StreamState.Pause - the stream has been paused. The socket is still open but we are not consuming the messages sent by Twitter.

When you create a stream, no connection is yet established.
You need to start the stream for it to open a connection and start receiving events.

When you are done with the current stream, you stop it.

// Here is an example showing how to stop a stream. In this case we want to stop after receiving 5 events.

var i = 0;
var twitterStream = client.Streams.CreateTweetStream();
twitterStream.EventReceived += (sender, eventReceived) =>
{
    Console.WriteLine(eventReceived.Json);
    if (i == 5)
    {
        twitterStream.Stop();
        Console.WriteLine("Complete!");
    }

    ++i;
};

// NOTE: this will complete only when `sampleStream.Stop();` has been called
await twitterStream.StartAsync("https://stream.twitter.com/1.1/statuses/sample.json"); 

Should I use Pause() or Stop()?¶

The difference between a Paused stream and a Stopped stream is the socket connection.
When a stream is stopped, no socket connection exist.
When a stream is paused, a socket connection is opened but is not used.

Having an open socket allow to “restart” the stream instantaneously. If the stream was stopped a connection should first be established before starting to receive the events.

Stop() should be used when you know that you will no longer need to use the stream. Stop() should be used when you do not care of losing events happening during the milliseconds of connecting to Twitter. Pause() should be used only when you need to quickly switch between pause and running.

Stream Events¶

Tweetinvi offers various events to help you manage your stream and easily make sense of messages received from Twitter.

Twitter events¶

Event	Description
EventReceived	Indicates that an event was received from twitter
TweetDeleted	Indicates that a tweet was deleted on Twitter. If you store any content of that tweet in your system, you should delete it
TweetLocationInfoRemoved	Indicates that the location information of a tweet was removed. If you store the location of the tweet in your system, you should delete it
TweetWitheld	Indicates that a tweet was created but the event cannot be forwarded to your application as it has been blocked by your country
UserWitheld	Indicates that a user matching your stream criteria performed an operation but the event cannot be forwarded to your application as the user is blocked in your country
LimitReached	Indicates that your stream criteria match more than 1% of the worlwide tweets. As a consequences some of the tweets will not be forwarded to the stream
WarningFallingBehindDetected	Indicates that your application is not consuming the messages from the stream fast enough. Failing to improve the speed of consumption will result in the stream being disconnected
UnmanagedEventReceived	Indicates that an event was received but Tweetinvi does not yet support it. If you receive such event please create an issue on github with the `json` received

Stream state events¶

Here is a list of events supported by Tweetinvi.

Twitter events

Event	Description
DisconnectMessageReceived	Twitter informs you that you are being disconnecting. A reason will be provided as to why you are
KeepAliveReceived	Twitter emits keep alive events at regular intervals to inform that the socket is open and that if no events were received it is expected

Tweetinvi events

Event	Description
StreamStateChanged	The state of the stream has changed (between running, paused and stopped)
StreamStarted	The stream is started and will be emitting events when received
StreamResumed	The stream that was previously paused is now consuming events from Twitter
StreamPaused	The stream is no longer consuming events sent by Twitter
StreamStopped	The stream is no longer active. The connection has been closed

Options¶

Language Filters¶

It is possible to restrict the stream to only return content associated with a specific language. You cannot change the language while a stream is running, this has to be done before calling StartAsync.

// add a language
stream.AddLanguageFilter(LanguageFilter.French);
// or
stream.AddLanguageFilter("fr");

// list filters applied to your stream
var languages = stream.LanguageFilters;

Filter levels¶

Twitter allow to filter the tweets that could have sensitive content using the filter_level.

You can read more about it here : https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters.

stream.FilterLevel = StreamFilterLevel.Low;

Stall Warnings¶

Twitter can send messages relevant to the stream state. To decide to not receive such messages, you can set the stall_warnings.

stream.StallWarnings = false;

Tweet Mode¶

TweetMode can be set to define the format of tweets messages received. Learn more about TweetMode.

sampleStream.TweetMode = TweetMode.Compat;

Custom Query Parameters¶

Tweetinvi supports all the currently existing parameters from the stream API.
If new query parameters appear in the future you can keep using Tweetinvi via the custom query parameters.

stream.AddCustomQueryParameter("new_location_filter", "paris");