Base EventSub Client#

Note

This is the base class used for all EventSub Transport implementations.

See EventSub for a list of all available Transports.

Class Documentation#

class twitchAPI.eventsub.base.EventSubBase#

Bases: ABC

EventSub integration for the Twitch Helix API.

__init__(twitch)#

Parameters:: twitch¶ (Twitch) – a app authenticated instance of Twitch

logger: Logger#: The logger used for EventSub related log messages

abstract start()#

Starts the EventSub client

Return type:: None
Raises:: RuntimeError – if EventSub is already running

abstract async stop()#

Stops the EventSub client

This also unsubscribes from all known subscriptions if unsubscribe_on_stop is True

Return type:: None

async unsubscribe_all()#: Unsubscribe from all subscriptions

async unsubscribe_all_known()#: Unsubscribe from all subscriptions known to this client.

async unsubscribe_topic(topic_id)#

Unsubscribe from a specific topic.

Return type:: bool

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelUpdateEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelUpdateEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelSubscribeEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelSubscriptionEndEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelSubscriptionGiftEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelSubscriptionMessageEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelCheerEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelBanEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelUnbanEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelModeratorAddEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelModeratorRemoveEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPointsCustomRewardAddEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
reward_id¶ (Optional[str]) – the id of the reward you want to get updates from.
Default: None
callback¶ (Callable[[ChannelPointsCustomRewardUpdateEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
reward_id¶ (Optional[str]) – the id of the reward you want to get updates from.
Default: None
callback¶ (Callable[[ChannelPointsCustomRewardRemoveEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
reward_id¶ (Optional[str]) – the id of the reward you want to get updates from.
Default: None
callback¶ (Callable[[ChannelPointsCustomRewardRedemptionAddEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
reward_id¶ (Optional[str]) – the id of the reward you want to get updates from.
Default: None
callback¶ (Callable[[ChannelPointsCustomRewardRedemptionUpdateEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPollBeginEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPollProgressEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPollEndEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPredictionEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPredictionEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPredictionEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ChannelPredictionEndEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

extension_client_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[ExtensionBitsTransactionCreateEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[GoalEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[GoalEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[GoalEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[HypeTrainEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[HypeTrainEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[HypeTrainEndEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[StreamOnlineEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – the id of the user you want to listen to
callback¶ (Callable[[StreamOfflineEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

client_id¶ (str) – Your application’s client id.
callback¶ (Callable[[UserAuthorizationGrantEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

client_id¶ (str) – Your application’s client id.
callback¶ (Callable[[UserAuthorizationRevokeEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

user_id¶ (str) – The user ID for the user you want update notifications for.
callback¶ (Callable[[UserUpdateEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – The ID of the broadcaster that you want to receive notifications about when they start a charity campaign.
callback¶ (Callable[[CharityCampaignStartEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – The ID of the broadcaster that you want to receive notifications about when their campaign makes progress or is updated.
callback¶ (Callable[[CharityCampaignProgressEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – The ID of the broadcaster that you want to receive notifications about when they stop a charity campaign.
callback¶ (Callable[[CharityCampaignStopEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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:

broadcaster_user_id¶ (str) – The ID of the broadcaster that you want to receive notifications about when users donate to their campaign.
callback¶ (Callable[[CharityDonationEvent], Awaitable[None]]) – function for callback

Raises:

EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if wait_for_subscription_confirm is true and the subscription was not fully confirmed in time
EventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error

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_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:

broadcaster_user_id¶ (str) – User ID of the channel to receive chat clear events for.
user_id¶ (str) – The user ID to read chat as.
callback¶ (Callable[[ChannelChatClearEvent], Awaitable[None]]) – function for callback

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:

broadcaster_user_id¶ (str) – User ID of the channel to receive chat clear user messages events for.
user_id¶ (str) – The user ID to read chat as.
callback¶ (Callable[[ChannelChatClearUserMessagesEvent], Awaitable[None]]) – function for callback

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:

broadcaster_user_id¶ (str) – User ID of the channel to receive chat message delete events for.
user_id¶ (str) – The user ID to read chat as.
callback¶ (Callable[[ChannelChatMessageDeleteEvent], Awaitable[None]]) – function for callback

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:

broadcaster_user_id¶ (str) – User ID of the channel to receive chat notification events for.
user_id¶ (str) – The user ID to read chat as.
callback¶ (Callable[[ChannelChatNotificationEvent], Awaitable[None]]) – function for callback

Return type:

str

async listen_channel_ad_break_begin(broadcaster_user_id, callback)#

A midroll commercial break has started running.

Requires the CHANNEL_READ_ADS scope.

Parameters:

broadcaster_user_id¶ (str) – The ID of the broadcaster that you want to get Channel Ad Break begin notifications for.
callback¶ (Callable[[ChannelAdBreakBeginEvent], Awaitable[None]]) – function for callback

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:

broadcaster_user_id¶ (str) – User ID of the channel to receive chat message events for.
user_id¶ (str) – The user ID to read chat as.
callback¶ (Callable[[ChannelChatMessageEvent], Awaitable[None]]) – function for callback

Return type:

str

async listen_channel_chat_settings_update(broadcaster_user_id, user_id, callback)#

This event sends a notification when a broadcaster’s chat settings are updated.

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:

broadcaster_user_id¶ (str) – User ID of the channel to receive chat settings update events for.
user_id¶ (str) – The user ID to read chat as.
callback¶ (Callable[[ChannelChatSettingsUpdateEvent], Awaitable[None]]) – function for callback

Return type:

str