Skip to main content

​
Overview

The Streaming API allows you to receive real-time updates for tweet engagements, direct message events, and typing indicators. This is useful for building live dashboards, notification systems, or monitoring tweet performance in real-time.

​
StreamingSession

Represents an active streaming session that receives real-time events from Twitter.

​
Attributes

​
id
str
The unique identifier of the streaming session.
​
topics
set[str]
The set of topics currently being streamed.
​
auto_reconnect
bool
Whether the session automatically reconnects when disconnected.

​
Methods

​
reconnect()

Reconnects the streaming session if it gets disconnected. 
await session.reconnect()
Returns: tuple[str, Payload] - The configuration event after reconnection.

​
update_subscriptions()

Updates the topics you’re subscribed to in an active streaming session. 
await session.update_subscriptions(
    subscribe=subscribe_topics,
    unsubscribe=unsubscribe_topics
)
​
subscribe
set[str] | None
Topics to subscribe to.
​
unsubscribe
set[str] | None
Topics to unsubscribe from.
DM update and DM typing topics cannot be added dynamically after session creation.
Returns: Payload - The subscription update confirmation.

​
Payload

A named tuple containing various event types received from the streaming API.

​
Attributes

​
config
ConfigEvent | None
Configuration event containing session information.
​
subscriptions
SubscriptionsEvent | None
Event containing subscription status and errors.
​
tweet_engagement
TweetEngagementEvent | None
Event containing tweet engagement metrics updates.
​
dm_update
DMUpdateEvent | None
Event indicating a new direct message.
​
dm_typing
DMTypingEvent | None
Event indicating someone is typing in a DM conversation.

​
Event Types

​
ConfigEvent

Event containing streaming session configuration.
​
session_id
str
The session ID for this streaming connection.
​
subscription_ttl_millis
int
The time-to-live for subscriptions in milliseconds.
​
heartbeat_millis
int
The heartbeat interval in milliseconds.

​
SubscriptionsEvent

Event representing subscription status updates.
​
errors
list
List of errors that occurred during subscription updates.

​
TweetEngagementEvent

Event containing real-time tweet engagement metrics.
​
like_count
str | None
The updated number of likes on the tweet.
​
retweet_count
str | None
The updated number of retweets.
​
view_count
str | None
The updated number of views.
​
view_count_state
str | None
The state of the view count.
​
quote_count
int | None
The updated number of quote tweets.
​
reply_count
int | None
The updated number of replies.

​
DMUpdateEvent

Event indicating a direct message update.
​
conversation_id
str
The ID of the conversation where the message was sent.
​
user_id
str
The ID of the user who sent the message.

​
DMTypingEvent

Event indicating typing activity in a DM conversation.
​
conversation_id
str
The ID of the conversation where typing is occurring.
​
user_id
str
The ID of the user who is typing.

​
Topic

Utility class for generating topic strings for streaming subscriptions.

​
tweet_engagement()

Generates a topic string for streaming tweet engagement events. 
from twikit.streaming import Topic

topic = Topic.tweet_engagement('1234567890')
​
tweet_id
str
required
The ID of the tweet to monitor.
Returns: str - Topic string in format /tweet_engagement/{tweet_id}

​
dm_update()

Generates a topic string for streaming direct message updates. 
topic = Topic.dm_update('123456789-987654321')
​
conversation_id
str
required
The ID of the conversation. Can be a group ID (00000000) or partner-user format (00000000-00000001).
Returns: str - Topic string in format /dm_update/{conversation_id}

​
dm_typing()

Generates a topic string for streaming typing indicators. 
topic = Topic.dm_typing('123456789-987654321')
​
conversation_id
str
required
The ID of the conversation. Can be a group ID (00000000) or partner-user format (00000000-00000001).
Returns: str - Topic string in format /dm_typing/{conversation_id}

​
Usage Examples

​
Basic Streaming Session

from twikit.streaming import Topic

# Define topics to stream
topics = {
    Topic.tweet_engagement('1739617652'),
    Topic.dm_update('17544932482-174455537996'),
    Topic.dm_typing('17544932482-174455537996')
}

# Create streaming session
session = await client.get_streaming_session(topics)

# Listen for events
async for topic, payload in session:
    if payload.dm_update:
        conversation_id = payload.dm_update.conversation_id
        user_id = payload.dm_update.user_id
        print(f'{conversation_id}: {user_id} sent a message')
    
    if payload.dm_typing:
        conversation_id = payload.dm_typing.conversation_id
        user_id = payload.dm_typing.user_id
        print(f'{conversation_id}: {user_id} is typing')
    
    if payload.tweet_engagement:
        likes = payload.tweet_engagement.like_count
        retweets = payload.tweet_engagement.retweet_count
        views = payload.tweet_engagement.view_count
        print(f'Engagement updated: likes={likes}, retweets={retweets}, views={views}')

​
Auto-Reconnection

By default, streaming sessions automatically reconnect when disconnected: 
# Auto-reconnect is enabled by default
session = await client.get_streaming_session(topics, auto_reconnect=True)

# Disable auto-reconnect
session = await client.get_streaming_session(topics, auto_reconnect=False)
When auto_reconnect=False, the session will stop yielding events after a disconnection.

​
DM Event Handling

from twikit.streaming import Topic

# Monitor DM conversations
conversation_id = '17544932482-174455537996'
topics = {
    Topic.dm_update(conversation_id),
    Topic.dm_typing(conversation_id)
}

session = await client.get_streaming_session(topics)

async for topic, payload in session:
    if payload.dm_update:
        # New message received
        print(f"New message from {payload.dm_update.user_id}")
        # Fetch the actual message content
        # messages = await client.get_messages(conversation_id)
    
    if payload.dm_typing:
        # User is typing
        print(f"{payload.dm_typing.user_id} is typing...")

Build docs developers (and LLMs) love

Get started for freeTalk to us