EventSub Websocket#

Note

EventSub Websocket is targeted at programs which have to subscribe to topics for just a single broadcaster.

Should you need to target multiple broadcasters or are building a server side projekt, look at EventSub Webhook

EventSub lets you listen for events that happen on Twitch.

The EventSub client runs in its own thread, calling the given callback function whenever an event happens.

Listening to topics#

After you started your EventSub client, you can use the listen_ prefixed functions to listen to the topics you are interested in.

Look at Available Topics and Callback Payloads to find the topics you are interested in.

The function you hand in as callback will be called whenever that event happens with the event data as a parameter, the type of that parameter is also listed in the link above.

Code Example#

from twitchAPI.helper import first
from twitchAPI.twitch import Twitch
from twitchAPI.oauth import UserAuthenticationStorageHelper
from twitchAPI.object.eventsub import ChannelFollowEvent
from twitchAPI.eventsub.websocket import EventSubWebsocket
from twitchAPI.type import AuthScope
import asyncio

APP_ID = 'your_app_id'
APP_SECRET = 'your_app_secret'
TARGET_SCOPES = [AuthScope.MODERATOR_READ_FOLLOWERS]


async def on_follow(data: ChannelFollowEvent):
    # our event happend, lets do things with the data we got!
    print(f'{data.event.user_name} now follows {data.event.broadcaster_user_name}!')


async def run():
    # create the api instance and get user auth either from storage or website
    twitch = await Twitch(APP_ID, APP_SECRET)
    helper = UserAuthenticationStorageHelper(twitch, TARGET_SCOPES)
    await helper.bind()

    # get the currently logged in user
    user = await first(twitch.get_users())

    # create eventsub websocket instance and start the client.
    eventsub = EventSubWebsocket(twitch)
    eventsub.start()
    # subscribing to the desired eventsub hook for our user
    # the given function (in this example on_follow) will be called every time this event is triggered
    # the broadcaster is a moderator in their own channel by default so specifying both as the same works in this example
    # We have to subscribe to the first topic within 10 seconds of eventsub.start() to not be disconnected.
    await eventsub.listen_channel_follow_v2(user.id, user.id, on_follow)

    # eventsub will run in its own process
    # so lets just wait for user input before shutting it all down again
    try:
        input('press Enter to shut down...')
    except KeyboardInterrupt:
        pass
    finally:
        # stopping both eventsub as well as gracefully closing the connection to the API
        await eventsub.stop()
        await twitch.close()


asyncio.run(run())
class twitchAPI.eventsub.websocket.EventSubWebsocket#

Bases: EventSubBase

__init__(twitch, connection_url=None, subscription_url=None, callback_loop=None, revocation_handler=None)#
Parameters:
  • twitch (Twitch) – The Twitch instance to be used

  • connection_url (Optional[str]) – Alternative connection URL, usefull for development with the twitch-cli

  • subscription_url (Optional[str]) – Alternative subscription URL, usefull for development with the twitch-cli

  • callback_loop (Optional[AbstractEventLoop]) –

    The asyncio eventloop to be used for callbacks.

    Set this if you or a library you use cares about which asyncio event loop is running the callbacks. Defaults to the one used by EventSub Websocket.

  • revocation_handler (Optional[Callable[[dict], Awaitable[None]]]) – Optional handler for when subscriptions get revoked.

    Default: None

subscription_url: Optional[str]#

The URL where subscriptions are being send to. Defaults to TWITCH_API_BASE_URL

connection_url: str#

The URL where the websocket connects to. Defaults to TWITCH_EVENT_SUB_WEBSOCKET_URL

active_session: Optional[Session]#

The currently used session

revokation_handler: Optional[Callable[[dict], Awaitable[None]]]#

Optional handler for when subscriptions get revoked.

reconnect_delay_steps: List[int]#

Time in seconds between reconnect attempts

start()#

Starts the EventSub client

Raises:
async stop()#

Stops the EventSub client

Raises:

RuntimeError – If EventSub is not running

async listen_channel_ad_break_begin(broadcaster_user_id, callback)#

A midroll commercial break has started running.

Requires the CHANNEL_READ_ADS scope.

Parameters:
Return type:

str

async listen_channel_ban(broadcaster_user_id, callback)#

A viewer is banned from the specified channel.

User Authentication with CHANNEL_MODERATE is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelban

Parameters:
Raises:
Return type:

str

async listen_channel_charity_campaign_donate(broadcaster_user_id, callback)#

Sends a notification when a user donates to the broadcaster’s charity campaign.

Requires the CHANNEL_READ_CHARITY auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaigndonate

Parameters:
Raises:
Return type:

str

async listen_channel_charity_campaign_progress(broadcaster_user_id, callback)#

Sends notifications when progress is made towards the campaign’s goal or when the broadcaster changes the fundraising goal.

Requires the CHANNEL_READ_CHARITY auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaignprogress

Parameters:
Raises:
Return type:

str

async listen_channel_charity_campaign_start(broadcaster_user_id, callback)#

Sends a notification when the broadcaster starts a charity campaign.

Requires the CHANNEL_READ_CHARITY auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaignstart

Parameters:
Raises:
Return type:

str

async listen_channel_charity_campaign_stop(broadcaster_user_id, callback)#

Sends a notification when the broadcaster stops a charity campaign.

Requires the CHANNEL_READ_CHARITY auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaignstop

Parameters:
Raises:
Return type:

str

async listen_channel_chat_clear(broadcaster_user_id, user_id, callback)#

A moderator or bot has cleared all messages from the chat room.

Requires USER_READ_CHAT scope from chatting user. If app access token used, then additionally requires USER_BOT scope from chatting user, and either CHANNEL_BOT scope from broadcaster or moderator status.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatclear

Parameters:
Return type:

str

async listen_channel_chat_clear_user_messages(broadcaster_user_id, user_id, callback)#

A moderator or bot has cleared all messages from a specific user.

Requires USER_READ_CHAT scope from chatting user. If app access token used, then additionally requires USER_BOT scope from chatting user, and either CHANNEL_BOT scope from broadcaster or moderator status.

Parameters:
Return type:

str

async listen_channel_chat_message(broadcaster_user_id, user_id, callback)#

Any user sends a message to a specific chat room.

Parameters:
Return type:

str

async listen_channel_chat_message_delete(broadcaster_user_id, user_id, callback)#

A moderator has removed a specific message.

Requires USER_READ_CHAT scope from chatting user. If app access token used, then additionally requires USER_BOT scope from chatting user, and either CHANNEL_BOT scope from broadcaster or moderator status.

Parameters:
Return type:

str

async listen_channel_chat_notification(broadcaster_user_id, user_id, callback)#

A notification for when an event that appears in chat has occurred.

Requires USER_READ_CHAT scope from chatting user. If app access token used, then additionally requires USER_BOT scope from chatting user, and either CHANNEL_BOT scope from broadcaster or moderator status.

Parameters:
Return type:

str

async listen_channel_cheer(broadcaster_user_id, callback)#

A user cheers on the specified channel.

User Authentication with BITS_READ is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelcheer

Parameters:
Raises:
Return type:

str

async listen_channel_follow_v2(broadcaster_user_id, moderator_user_id, callback)#

A specified channel receives a follow.

User Authentication with MODERATOR_READ_FOLLOWERS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelfollow

Parameters:
  • broadcaster_user_id (str) – the id of the user you want to listen to

  • moderator_user_id (str) – The ID of the moderator of the channel you want to get follow notifications for.

  • callback (Callable[[ChannelFollowEvent], Awaitable[None]]) – function for callback

Raises:
Return type:

str

async listen_channel_moderator_add(broadcaster_user_id, callback)#

Moderator privileges were added to a user on a specified channel.

User Authentication with MODERATION_READ is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelmoderatoradd

Parameters:
Raises:
Return type:

str

async listen_channel_moderator_remove(broadcaster_user_id, callback)#

Moderator privileges were removed from a user on a specified channel.

User Authentication with MODERATION_READ is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelmoderatorremove

Parameters:
Raises:
Return type:

str

async listen_channel_points_custom_reward_add(broadcaster_user_id, callback)#

A custom channel points reward has been created for the specified channel.

User Authentication with CHANNEL_READ_REDEMPTIONS or CHANNEL_MANAGE_REDEMPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardadd

Parameters:
Raises:
Return type:

str

async listen_channel_points_custom_reward_redemption_add(broadcaster_user_id, callback, reward_id=None)#

A viewer has redeemed a custom channel points reward on the specified channel.

User Authentication with CHANNEL_READ_REDEMPTIONS or CHANNEL_MANAGE_REDEMPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_reward_redemptionadd

Parameters:
Raises:
Return type:

str

async listen_channel_points_custom_reward_redemption_update(broadcaster_user_id, callback, reward_id=None)#

A redemption of a channel points custom reward has been updated for the specified channel.

User Authentication with CHANNEL_READ_REDEMPTIONS or CHANNEL_MANAGE_REDEMPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_reward_redemptionupdate

Parameters:
Raises:
Return type:

str

async listen_channel_points_custom_reward_remove(broadcaster_user_id, callback, reward_id=None)#

A custom channel points reward has been removed from the specified channel.

User Authentication with CHANNEL_READ_REDEMPTIONS or CHANNEL_MANAGE_REDEMPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardremove

Parameters:
Raises:
Return type:

str

async listen_channel_points_custom_reward_update(broadcaster_user_id, callback, reward_id=None)#

A custom channel points reward has been updated for the specified channel.

User Authentication with CHANNEL_READ_REDEMPTIONS or CHANNEL_MANAGE_REDEMPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardupdate

Parameters:
Raises:
Return type:

str

async listen_channel_poll_begin(broadcaster_user_id, callback)#

A poll started on a specified channel.

User Authentication with CHANNEL_READ_POLLS or CHANNEL_MANAGE_POLLS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollbegin

Parameters:
Raises:
Return type:

str

async listen_channel_poll_end(broadcaster_user_id, callback)#

A poll ended on a specified channel.

User Authentication with CHANNEL_READ_POLLS or CHANNEL_MANAGE_POLLS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollend

Parameters:
Raises:
Return type:

str

async listen_channel_poll_progress(broadcaster_user_id, callback)#

Users respond to a poll on a specified channel.

User Authentication with CHANNEL_READ_POLLS or CHANNEL_MANAGE_POLLS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollprogress

Parameters:
Raises:
Return type:

str

async listen_channel_prediction_begin(broadcaster_user_id, callback)#

A Prediction started on a specified channel.

User Authentication with CHANNEL_READ_PREDICTIONS or CHANNEL_MANAGE_PREDICTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionbegin

Parameters:
Raises:
Return type:

str

async listen_channel_prediction_end(broadcaster_user_id, callback)#

A Prediction ended on a specified channel.

User Authentication with CHANNEL_READ_PREDICTIONS or CHANNEL_MANAGE_PREDICTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionend

Parameters:
Raises:
Return type:

str

async listen_channel_prediction_lock(broadcaster_user_id, callback)#

A Prediction was locked on a specified channel.

User Authentication with CHANNEL_READ_PREDICTIONS or CHANNEL_MANAGE_PREDICTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionlock

Parameters:
Raises:
Return type:

str

async listen_channel_prediction_progress(broadcaster_user_id, callback)#

Users participated in a Prediction on a specified channel.

User Authentication with CHANNEL_READ_PREDICTIONS or CHANNEL_MANAGE_PREDICTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionprogress

Parameters:
Raises:
Return type:

str

async listen_channel_raid(callback, to_broadcaster_user_id=None, from_broadcaster_user_id=None)#

A broadcaster raids another broadcaster’s channel.

No authorization required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelraid

Parameters:
  • from_broadcaster_user_id (Optional[str]) – The broadcaster user ID that created the channel raid you want to get notifications for.

  • to_broadcaster_user_id (Optional[str]) – The broadcaster user ID that received the channel raid you want to get notifications for.

  • callback (Callable[[ChannelRaidEvent], Awaitable[None]]) – function for callback

Raises:
Return type:

str

async listen_channel_shield_mode_begin(broadcaster_user_id, moderator_user_id, callback)#

Sends a notification when the broadcaster activates Shield Mode.

Requires the MODERATOR_READ_SHIELD_MODE or MODERATOR_MANAGE_SHIELD_MODE auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshield_modebegin

Parameters:
  • broadcaster_user_id (str) – The ID of the broadcaster that you want to receive notifications about when they activate Shield Mode.

  • moderator_user_id (str) – The ID of the broadcaster or one of the broadcaster’s moderators.

  • callback (Callable[[ShieldModeEvent], Awaitable[None]]) – function for callback

Raises:
Return type:

str

async listen_channel_shield_mode_end(broadcaster_user_id, moderator_user_id, callback)#

Sends a notification when the broadcaster deactivates Shield Mode.

Requires the MODERATOR_READ_SHIELD_MODE or MODERATOR_MANAGE_SHIELD_MODE auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshield_modeend

Parameters:
  • broadcaster_user_id (str) – The ID of the broadcaster that you want to receive notifications about when they deactivate Shield Mode.

  • moderator_user_id (str) – The ID of the broadcaster or one of the broadcaster’s moderators.

  • callback (Callable[[ShieldModeEvent], Awaitable[None]]) – function for callback

Raises:
Return type:

str

async listen_channel_shoutout_create(broadcaster_user_id, moderator_user_id, callback)#

Sends a notification when the specified broadcaster sends a Shoutout.

Requires the MODERATOR_READ_SHOUTOUTS or MODERATOR_MANAGE_SHOUTOUTS auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshoutoutcreate

Parameters:
  • broadcaster_user_id (str) – The ID of the broadcaster that you want to receive notifications about when they send a Shoutout.

  • moderator_user_id (str) – The ID of the broadcaster that gave the Shoutout or one of the broadcaster’s moderators.

  • callback (Callable[[ChannelShoutoutCreateEvent], Awaitable[None]]) – function for callback

Return type:

str

async listen_channel_shoutout_receive(broadcaster_user_id, moderator_user_id, callback)#

Sends a notification when the specified broadcaster receives a Shoutout.

Requires the MODERATOR_READ_SHOUTOUTS or MODERATOR_MANAGE_SHOUTOUTS auth scope.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshoutoutreceive

Parameters:
  • broadcaster_user_id (str) – The ID of the broadcaster that you want to receive notifications about when they receive a Shoutout.

  • moderator_user_id (str) – The ID of the broadcaster that received the Shoutout or one of the broadcaster’s moderators.

  • callback (Callable[[ChannelShoutoutReceiveEvent], Awaitable[None]]) – function for callback

Return type:

str

async listen_channel_subscribe(broadcaster_user_id, callback)#

A notification when a specified channel receives a subscriber. This does not include resubscribes.

User Authentication with CHANNEL_READ_SUBSCRIPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscribe

Parameters:
Raises:
Return type:

str

async listen_channel_subscription_end(broadcaster_user_id, callback)#

A notification when a subscription to the specified channel ends.

User Authentication with CHANNEL_READ_SUBSCRIPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptionend

Parameters:
Raises:
Return type:

str

async listen_channel_subscription_gift(broadcaster_user_id, callback)#

A notification when a viewer gives a gift subscription to one or more users in the specified channel.

User Authentication with CHANNEL_READ_SUBSCRIPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptiongift

Parameters:
Raises:
Return type:

str

async listen_channel_subscription_message(broadcaster_user_id, callback)#

A notification when a user sends a resubscription chat message in a specific channel.

User Authentication with CHANNEL_READ_SUBSCRIPTIONS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptionmessage

Parameters:
Raises:
Return type:

str

async listen_channel_unban(broadcaster_user_id, callback)#

A viewer is unbanned from the specified channel.

User Authentication with CHANNEL_MODERATE is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelunban

Parameters:
Raises:
Return type:

str

async listen_channel_update(broadcaster_user_id, callback)#

A broadcaster updates their channel properties e.g., category, title, mature flag, broadcast, or language.

No Authentication required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelupdate

Parameters:
Raises:
Return type:

str

async listen_channel_update_v2(broadcaster_user_id, callback)#

A broadcaster updates their channel properties e.g., category, title, content classification labels or language.

No Authentication required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelupdate

Parameters:
Raises:
Return type:

str

async listen_drop_entitlement_grant(organisation_id, callback, category_id=None, campaign_id=None)#

An entitlement for a Drop is granted to a user.

App access token required. The client ID associated with the access token must be owned by a user who is part of the specified organization.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#dropentitlementgrant

Parameters:
  • organisation_id (str) – The organization ID of the organization that owns the game on the developer portal.

  • category_id (Optional[str]) – The category (or game) ID of the game for which entitlement notifications will be received.

    Default: None

  • campaign_id (Optional[str]) – The campaign ID for a specific campaign for which entitlement notifications will be received.

    Default: None

  • callback (Callable[[DropEntitlementGrantEvent], Awaitable[None]]) – function for callback

Raises:
Return type:

str

async listen_extension_bits_transaction_create(extension_client_id, callback)#

A Bits transaction occurred for a specified Twitch Extension.

The OAuth token client ID must match the Extension client ID.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#extensionbits_transactioncreate

Parameters:
Raises:
Return type:

str

async listen_goal_begin(broadcaster_user_id, callback)#

A goal begins on the specified channel.

User Authentication with CHANNEL_READ_GOALS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalbegin

Parameters:
Raises:
Return type:

str

async listen_goal_end(broadcaster_user_id, callback)#

A goal ends on the specified channel.

User Authentication with CHANNEL_READ_GOALS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalend

Parameters:
Raises:
Return type:

str

async listen_goal_progress(broadcaster_user_id, callback)#

A goal makes progress on the specified channel.

User Authentication with CHANNEL_READ_GOALS is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalprogress

Parameters:
Raises:
Return type:

str

async listen_hype_train_begin(broadcaster_user_id, callback)#

A Hype Train begins on the specified channel.

User Authentication with CHANNEL_READ_HYPE_TRAIN is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainbegin

Parameters:
Raises:
Return type:

str

async listen_hype_train_end(broadcaster_user_id, callback)#

A Hype Train ends on the specified channel.

User Authentication with CHANNEL_READ_HYPE_TRAIN is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainend

Parameters:
Raises:
Return type:

str

async listen_hype_train_progress(broadcaster_user_id, callback)#

A Hype Train makes progress on the specified channel.

User Authentication with CHANNEL_READ_HYPE_TRAIN is required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainprogress

Parameters:
Raises:
Return type:

str

async listen_stream_offline(broadcaster_user_id, callback)#

The specified broadcaster stops a stream.

No authorization required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#streamoffline

Parameters:
Raises:
Return type:

str

async listen_stream_online(broadcaster_user_id, callback)#

The specified broadcaster starts a stream.

No authorization required.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#streamonline

Parameters:
Raises:
Return type:

str

async listen_user_authorization_grant(client_id, callback)#

A user’s authorization has been granted to your client id.

Provided client_id must match the client id in the application access token.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userauthorizationgrant

Parameters:
Raises:
Return type:

str

async listen_user_authorization_revoke(client_id, callback)#

A user’s authorization has been revoked for your client id.

Provided client_id must match the client id in the application access token.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userauthorizationrevoke

Parameters:
Raises:
Return type:

str

async listen_user_update(user_id, callback)#

A user has updated their account.

No authorization required. If you have the USER_READ_EMAIL scope, the notification will include email field.

For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userupdate

Parameters:
Raises:
Return type:

str

async unsubscribe_all()#

Unsubscribe from all subscriptions

async unsubscribe_all_known()#

Unsubscribe from all subscriptions known to this client.

async unsubscribe_topic(topic_id)#
Return type:

bool

Unsubscribe from a specific topic.

logger: Logger#

The logger used for EventSub related log messages