Eventsub Subscriptions

class twitchio.eventsub.AutomodMessageHoldSubscription(**condition: Unpack[Condition])

The automod.message.hold subscription type notifies a user if a message was caught by automod for review.

Important

Requires a user access token that includes the moderator:manage:automod scope. The ID in the moderator_user_id condition parameter must match the user ID in the access token.

If app access token used, then additionally requires the moderator:manage:automod scope for the moderator.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.AutomodMessageHoldV2Subscription(**condition: Unpack[Condition])

The automod.message.hold V2 subscription type notifies a user if a message was caught by automod for review.

Version 2 of this endpoint provides additional information about the message, including the reason, the term used, and its position within the message.

Important

Requires a user access token that includes the moderator:manage:automod scope. The ID in the moderator_user_id condition parameter must match the user ID in the access token.

If app access token used, then additionally requires the moderator:manage:automod scope for the moderator.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.AutomodMessageUpdateSubscription(**condition: Unpack[Condition])

The automod.message.update subscription type sends notification when a message in the automod queue has its status changed.

Important

Requires a user access token that includes the moderator:manage:automod scope. The ID in the moderator_user_id condition parameter must match the user ID in the access token.

If app access token used, then additionally requires the moderator:manage:automod scope for the moderator.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.AutomodMessageUpdateV2Subscription(**condition: Unpack[Condition])

The automod.message.update subscription type sends notification when a message in the automod queue has its status changed.

Version 2 of this endpoint provides additional information about the message, including the reason, the term used, and its position within the message.

Important

Requires a user access token that includes the moderator:manage:automod scope. The ID in the moderator_user_id condition parameter must match the user ID in the access token.

If app access token used, then additionally requires the moderator:manage:automod scope for the moderator.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.AutomodSettingsUpdateSubscription(**condition: Unpack[Condition])

The automod.settings.update subscription type sends a notification when a broadcaster’s automod settings are updated.

Important

Requires a user access token that includes the moderator:read:automod_settings scope. The ID in the moderator_user_id condition parameter must match the user ID in the access token.

If app access token used, then additionally requires the moderator:read:automod_settings scope for the moderator.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.AutomodTermsUpdateSubscription(**condition: Unpack[Condition])

The automod.terms.update subscription type sends a notification when a broadcaster’s terms settings are updated. Changes to private terms are not sent.

Important

Requires a user access token that includes the moderator:manage:automod scope. The ID in the moderator_user_id condition parameter must match the user ID in the access token.

If app access token used, then additionally requires the moderator:manage:automod scope for the moderator.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelUpdateSubscription(**condition: Unpack[Condition])

The channel.update subscription type sends notifications when a broadcaster updates the category, title, content classification labels, or broadcast language for their channel.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelFollowSubscription(**condition: Unpack[Condition])

The channel.follow subscription type sends a notification when a specified channel receives a follow.

Important

Must have moderator:read:followers scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.AdBreakBeginSubscription(**condition: Unpack[Condition])

The channel.ad_break.begin subscription type sends a notification when a user runs a midroll commercial break, either manually or automatically via ads manager.

Important

Must have channel:read:ads scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChatClearSubscription(**condition: Unpack[Condition])

The channel.chat.clear subscription type sends a notification when a moderator or bot clears all messages from the chat room.

Important

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.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatClearUserMessagesSubscription(**condition: Unpack[Condition])

The channel.chat.clear_user_messages subscription type sends a notification when a moderator or bot clears all messages for a specific user.

Important

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.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatMessageSubscription(**condition: Unpack[Condition])

The channel.chat.message subscription type sends a notification when any user sends a message to a channel’s chat room.

Important

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.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatNotificationSubscription(**condition: Unpack[Condition])

The channel.chat.notification subscription type sends a notification when an event that appears in chat occurs, such as someone subscribing to the channel or a subscription is gifted.

Important

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.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatMessageDeleteSubscription(**condition: Unpack[Condition])

The channel.chat.message_delete subscription type sends a notification when a moderator removes a specific message.

Important

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.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatSettingsUpdateSubscription(**condition: Unpack[Condition])

The channel.chat_settings.update subscription type sends a notification when a broadcaster’s chat settings are updated.

Important

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.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatUserMessageHoldSubscription(**condition: Unpack[Condition])

The channel.chat.user_message_hold subscription type notifies a user if their message is caught by automod.

Important

Requires user:read:chat scope from chatting user.

If app access token used, then additionally requires user:bot scope from chatting user.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.ChatUserMessageUpdateSubscription(**condition: Unpack[Condition])

The channel.chat.user_message_update subscription type notifies a user if their message’s automod status is updated.

Important

Requires user:read:chat scope from chatting user.

If app access token used, then additionally requires user:bot scope from chatting user.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • user_id (str | PartialUser) – The ID, or PartialUser, of the chatter reading chat. e.g. Your bot ID.

Raises

ValueError – The parameters “broadcaster_user_id” and “user_id” must be passed.

class twitchio.eventsub.SharedChatSessionBeginSubscription(**condition: Unpack[Condition])

The channel.shared_chat.begin subscription type sends a notification when a channel becomes active in an active shared chat session.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.SharedChatSessionUpdateSubscription(**condition: Unpack[Condition])

The channel.shared_chat.update subscription type sends a notification when the active shared chat session the channel is in changes.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.SharedChatSessionEndSubscription(**condition: Unpack[Condition])

The channel.shared_chat.end subscription type sends a notification when a channel leaves a shared chat session or the session ends.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelSubscribeSubscription(**condition: Unpack[Condition])

The channel.subscribe subscription type sends a notification when a specified channel receives a subscriber. This does not include resubscribes.

Important

Must have channel:read:subscriptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelSubscriptionEndSubscription(**condition: Unpack[Condition])

The channel.subscription.end subscription type sends a notification when a subscription to the specified channel expires.

Important

Must have channel:read:subscriptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelSubscriptionGiftSubscription(**condition: Unpack[Condition])

The channel.subscription.gift subscription type sends a notification when a user gives one or more gifted subscriptions in a channel.

Important

Must have channel:read:subscriptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelSubscribeMessageSubscription(**condition: Unpack[Condition])

The channel.subscription.message subscription type sends a notification when a user sends a resubscription chat message in a specific channel.

Important

Must have channel:read:subscriptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelCheerSubscription(**condition: Unpack[Condition])

The channel.cheer subscription type sends a notification when a user cheers on the specified channel.

Important

Must have bits:read scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelRaidSubscription(**condition: Unpack[Condition])

The channel.raid subscription type sends a notification when a broadcaster raids another broadcaster’s channel.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • to_broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to. This listens to the raid events to a specific broadcaster.

  • from_broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to. This listens to the raid events from a specific broadcaster.

Raises

ValueError – The parameter “to_broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelBanSubscription(**condition: Unpack[Condition])

The channel.ban subscription type sends a notification when a viewer is timed out or banned from the specified channel.

Important

Must have channel:moderate scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelUnbanSubscription(**condition: Unpack[Condition])

The channel.unban subscription type sends a notification when a viewer is unbanned from the specified channel.

Important

Must have channel:moderate scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelUnbanRequestSubscription(**condition: Unpack[Condition])

The channel.unban_request.create subscription type sends a notification when a user creates an unban request.

Important

Must have moderator:read:unban_requests or moderator:manage:unban_requests scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelUnbanRequestResolveSubscription(**condition: Unpack[Condition])

The channel.unban_request.resolve subscription type sends a notification when an unban request has been resolved.

Important

Must have moderator:read:unban_requests or moderator:manage:unban_requests scope.

If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelModerateSubscription(**condition: Unpack[Condition])

The channel.moderate subscription type sends a notification when a moderator performs a moderation action in a channel. Some of these actions affect chatters in other channels during Shared Chat.

This is Version 1 of the subscription.

Important

Must have all of the following scopes:

  • moderator:read:blocked_terms OR moderator:manage:blocked_terms

  • moderator:read:chat_settings OR moderator:manage:chat_settings

  • moderator:read:unban_requests OR moderator:manage:unban_requests

  • moderator:read:banned_users OR moderator:manage:banned_users

  • moderator:read:chat_messages OR moderator:manage:chat_messages

  • moderator:read:moderators

  • moderator:read:vips

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelModerateV2Subscription(**condition: Unpack[Condition])

The channel.moderate subscription type sends a notification when a moderator performs a moderation action in a channel. Some of these actions affect chatters in other channels during Shared Chat.

This is Version 2 of the subscription that includes warnings.

Important

Must have all of the following scopes:

  • moderator:read:blocked_terms OR moderator:manage:blocked_terms

  • moderator:read:chat_settings OR moderator:manage:chat_settings

  • moderator:read:unban_requests OR moderator:manage:unban_requests

  • moderator:read:banned_users OR moderator:manage:banned_users

  • moderator:read:chat_messages OR moderator:manage:chat_messages

  • moderator:read:warnings OR moderator:manage:warnings

  • moderator:read:moderators

  • moderator:read:vips

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelModeratorAddSubscription(**condition: Unpack[Condition])

The channel.moderator.add subscription type sends a notification when a user is given moderator privileges on a specified channel.

Important

Must have moderation:read scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelModeratorRemoveSubscription(**condition: Unpack[Condition])

The channel.moderator.remove subscription type sends a notification when a user has moderator privileges removed on a specified channel.

Important

Must have moderation:read scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPointsAutoRedeemSubscription(**condition: Unpack[Condition])

The channel.channel_points_automatic_reward_redemption.add subscription type sends a notification when a viewer has redeemed an automatic channel points reward on the specified channel.

Important

Must have channel:read:redemptions or channel:manage:redemptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPointsRewardAddSubscription(**condition: Unpack[Condition])

The channel.channel_points_custom_reward.add subscription type sends a notification when a custom channel points reward has been created for the specified channel.

Important

Must have channel:read:redemptions or channel:manage:redemptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPointsRewardUpdateSubscription(**condition: Unpack[Condition])

The channel.channel_points_custom_reward.update subscription type sends a notification when a custom channel points reward has been updated for the specified channel.

Important

Must have channel:read:redemptions or channel:manage:redemptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • reward_id (str) – Optional to only get notifications for a specific reward.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPointsRewardRemoveSubscription(**condition: Unpack[Condition])

The channel.channel_points_custom_reward.remove subscription type sends a notification when a custom channel points reward has been removed from the specified channel.

Important

Must have channel:read:redemptions or channel:manage:redemptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • reward_id (str) – Optional to only get notifications for a specific reward.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPointsRedeemAddSubscription(**condition: Unpack[Condition])

The channel.channel_points_custom_reward_redemption.add subscription type sends a notification when a viewer has redeemed a custom channel points reward on the specified channel.

Important

Must have channel:read:redemptions or channel:manage:redemptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • reward_id (str) – Optional to only get notifications for a specific reward.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPointsRedeemUpdateSubscription(**condition: Unpack[Condition])

The channel.channel_points_custom_reward_redemption.update subscription type sends a notification when a redemption of a channel points custom reward has been updated for the specified channel.

Important

Must have channel:read:redemptions or channel:manage:redemptions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • reward_id (str) – Optional to only get notifications for a specific reward.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPollBeginSubscription(**condition: Unpack[Condition])

The channel.poll.begin subscription type sends a notification when a poll begins on the specified channel.

Important

Must have channel:read:polls or channel:manage:polls scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPollProgressSubscription(**condition: Unpack[Condition])

The channel.poll.progress subscription type sends a notification when users respond to a poll on the specified channel.

Important

Must have channel:read:polls or channel:manage:polls scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPollEndSubscription(**condition: Unpack[Condition])

The channel.poll.end subscription type sends a notification when a poll ends on the specified channel.

Important

Must have channel:read:polls or channel:manage:polls scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPredictionBeginSubscription(**condition: Unpack[Condition])

The channel.prediction.begin subscription type sends a notification when a Prediction begins on the specified channel.

Important

Must have channel:read:predictions or channel:manage:predictions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPredictionLockSubscription(**condition: Unpack[Condition])

The channel.prediction.lock subscription type sends a notification when a Prediction is locked on the specified channel.

Important

Must have channel:read:predictions or channel:manage:predictions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPredictionProgressSubscription(**condition: Unpack[Condition])

The channel.prediction.progress subscription type sends a notification when users participate in a Prediction on the specified channel.

Important

Must have channel:read:predictions or channel:manage:predictions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelPredictionEndSubscription(**condition: Unpack[Condition])

The channel.prediction.end subscription type sends a notification when a Prediction ends on the specified channel.

Important

Must have channel:read:predictions or channel:manage:predictions scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.SuspiciousUserUpdateSubscription(**condition: Unpack[Condition])

The channel.suspicious_user.update subscription type sends a notification when a suspicious user has been updated.

Important

Requires the moderator:read:suspicious_users scope.

If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.SuspiciousUserMessageSubscription(**condition: Unpack[Condition])

The channel.suspicious_user.message subscription type sends a notification when a chat message has been sent from a suspicious user.

Important

Requires the moderator:read:suspicious_users scope.

If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelVIPAddSubscription(**condition: Unpack[Condition])

The channel.vip.add subscription type sends a notification when a VIP is added to the channel.

Important

Must have channel:read:vips or channel:manage:vips scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelVIPRemoveSubscription(**condition: Unpack[Condition])

The channel.vip.remove subscription type sends a notification when a VIP is removed from the channel.

Important

Must have channel:read:vips or channel:manage:vips scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ChannelWarningAcknowledgementSubscription(**condition: Unpack[Condition])

The channel.warning.acknowledge subscription type sends a notification when a warning is acknowledged by a user. Broadcasters and moderators can see the warning’s details.

Important

Must have the moderator:read:warnings or moderator:manage:warnings scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.ChannelWarningSendSubscription(**condition: Unpack[Condition])

The channel.warning.send subscription type sends a notification when a warning is sent to a user. Broadcasters and moderators can see the warning’s details.

Important

Must have the moderator:read:warnings or moderator:manage:warnings scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameters “broadcaster_user_id” and “moderator_user_id” must be passed.

class twitchio.eventsub.CharityDonationSubscription(**condition: Unpack[Condition])

The channel.charity_campaign.donate subscription type sends a notification when a user donates to the broadcaster’s charity campaign.

Important

Must have channel:read:charity scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.CharityCampaignStartSubscription(**condition: Unpack[Condition])

The channel.charity_campaign.start subscription type sends a notification when the broadcaster starts a charity campaign.

Note

It’s possible to receive this event after the Progress event.

Important

Must have channel:read:charity scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.CharityCampaignProgressSubscription(**condition: Unpack[Condition])

The channel.charity_campaign.progress subscription type sends a notification when progress is made towards the campaign’s goal or when the broadcaster changes the fundraising goal.

Note

It’s possible to receive this event before the Start event.

To get donation information, subscribe to CharityDonationSubscription() event.

Important

Must have channel:read:charity scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.CharityCampaignStopSubscription(**condition: Unpack[Condition])

The channel.charity_campaign.stop subscription type sends a notification when the broadcaster stops a charity campaign.

Important

Must have channel:read:charity scope.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.GoalBeginSubscription(**condition: Unpack[Condition])

The channel.goal.begin subscription type sends a notification when the specified broadcaster begins a goal.

Note

It’s possible to receive the Begin event after receiving Progress events.

Important

Requires a user OAuth access token with scope channel:read:goals.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.GoalProgressSubscription(**condition: Unpack[Condition])

The channel.goal.progress subscription type sends a notification when progress is made towards the specified broadcaster’s goal. Progress could be positive (added followers) or negative (lost followers).

Note

It’s possible to receive the Progress events before receiving the Begin event.

Important

Requires a user OAuth access token with scope channel:read:goals.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.GoalEndSubscription(**condition: Unpack[Condition])

The channel.goal.end subscription type sends a notification when the specified broadcaster ends a goal.

Important

Requires a user OAuth access token with scope channel:read:goals.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.HypeTrainBeginSubscription(**condition: Unpack[Condition])

The channel.hype_train.begin subscription type sends a notification when a Hype Train begins on the specified channel.

Important

Requires a user OAuth access token with scope channel:read:hype_train.

Note

EventSub does not make strong assurances about the order of message delivery, so it is possible to receive channel.hype_train.progress notifications before you receive the corresponding channel.hype_train.begin notification.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.HypeTrainProgressSubscription(**condition: Unpack[Condition])

The channel.hype_train.progress subscription type sends a notification when a Hype Train makes progress on the specified channel.

Important

Requires a user OAuth access token with scope channel:read:hype_train.

Note

EventSub does not make strong assurances about the order of message delivery, so it is possible to receive channel.hype_train.progress notifications before you receive the corresponding channel.hype_train.begin notification.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.HypeTrainEndSubscription(**condition: Unpack[Condition])

The channel.hype_train.end subscription type sends a notification when a Hype Train ends on the specified channel.

Important

Requires a user OAuth access token with scope channel:read:hype_train.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ShieldModeBeginSubscription(**condition: Unpack[Condition])

The channel.shield_mode.begin subscription type sends a notification when the broadcaster activates Shield Mode.

This event informs the subscriber that the broadcaster’s moderation settings were changed based on the broadcaster’s Shield Mode configuration settings.

Important

Requires the moderator:read:shield_mode or moderator:manage:shield_mode scope.

  • If you use webhooks, the moderator must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

  • If you use WebSockets, the moderator’s ID must match the user ID in the user access token.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ShieldModeEndSubscription(**condition: Unpack[Condition])

The channel.shield_mode.end subscription type sends a notification when the broadcaster deactivates Shield Mode.

This event informs the subscriber that the broadcaster’s moderation settings were changed back to the broadcaster’s previous moderation settings.

Important

Requires the moderator:read:shield_mode or moderator:manage:shield_mode scope.

  • If you use webhooks, the moderator must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

  • If you use WebSockets, the moderator’s ID must match the user ID in the user access token.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ShoutoutCreateSubscription(**condition: Unpack[Condition])

The channel.shoutout.create subscription type sends a notification when the specified broadcaster sends a shoutout.

Important

Requires the moderator:read:shoutouts or moderator:manage:shoutouts scope.

  • If you use webhooks, the moderator must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

  • If you use WebSockets, the moderator’s ID must match the user ID in the user access token.

Note

This is only sent if Twitch posts the Shoutout to the broadcaster’s activity feed.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.ShoutoutReceiveSubscription(**condition: Unpack[Condition])

The channel.shoutout.receive subscription type sends a notification when the specified broadcaster receives a shoutout.

Important

Requires the moderator:read:shoutouts or moderator:manage:shoutouts scope.

  • If you use webhooks, the moderator must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.

  • If you use WebSockets, the moderator’s ID must match the user ID in the user access token.

Note

This is only sent if Twitch posts the Shoutout to the broadcaster’s activity feed.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters
  • broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

  • moderator_user_id (str | PartialUser) – The ID, or PartialUser, of a moderator for the the broadcaster you are subscribing to. This could also be the broadcaster.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.StreamOnlineSubscription(**condition: Unpack[Condition])

The stream.online subscription type sends a notification when the specified broadcaster starts a stream.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.StreamOfflineSubscription(**condition: Unpack[Condition])

The stream.offline subscription type sends a notification when the specified broadcaster stops a stream.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

broadcaster_user_id (str | PartialUser) – The ID, or PartialUser, of the broadcaster to subscribe to.

Raises

ValueError – The parameter “broadcaster_user_id” must be passed.

class twitchio.eventsub.UserAuthorizationGrantSubscription(**condition: Unpack[Condition])

The user.authorization.grant subscription type sends a notification when a user’s authorization has been granted to your client id.

Important

This subscription type is only supported by webhooks, and cannot be used with WebSockets.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

client_id (str) – Provided client_id must match the client id in the application access token.

Raises

ValueError – The parameter “client_id” must be passed.

class twitchio.eventsub.UserAuthorizationRevokeSubscription(**condition: Unpack[Condition])

The user.authorization.revoke subscription type sends a notification when a user’s authorization has been revoked for your client id. Use this webhook to meet government requirements for handling user data, such as GDPR, LGPD, or CCPA.

Important

This subscription type is only supported by webhooks, and cannot be used with WebSockets.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

client_id (str) – Provided client_id must match the client id in the application access token.

Raises

ValueError – The parameter “client_id” must be passed.

class twitchio.eventsub.UserUpdateSubscription(**condition: Unpack[Condition])

The user.update subscription type sends a notification when user updates their account.

Note

No authorization required. If you have the user:read:email scope, the notification will include email field.

If the user no longer exists then the login attribute will be None.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

user_id (str | PartialUser) – The ID, or PartialUser, of the user receiving the whispers you wish to subscribe to.

Raises

ValueError – The parameter “user_id” must be passed.

class twitchio.eventsub.WhisperReceivedSubscription(**condition: Unpack[Condition])

The user.whisper.message subscription type sends a notification when a user receives a whisper.

Important

Must have oauth scope user:read:whispers or user:manage:whispers.

One attribute .condition can be accessed from this class, which returns a mapping of the subscription parameters provided.

Parameters

user_id (str | PartialUser) – The ID, or PartialUser, of the user receiving the whispers you wish to subscribe to.

Raises

ValueError – The parameter “user_id” must be passed.