Table Reference¶

Warning

This document is a work in progress.

Type	Subscription	Event	Payload
Automod Message Hold	`AutomodMessageHoldSubscription()`	`event_automod_message_hold()`	`AutomodMessageHold`
Automod Message Update	`AutomodMessageUpdateSubscription()`	`event_automod_message_update()`	`AutomodMessageUpdate`
Automod Settings Update	`AutomodSettingsUpdateSubscription()`	`event_automod_settings_update()`	`AutomodSettingsUpdate`
Automod Terms Update	`AutomodTermsUpdateSubscription()`	`event_automod_terms_update()`	`AutomodTermsUpdate`
Channel Update	`ChannelUpdateSubscription()`	`event_channel_update()`	`ChannelUpdate`
Channel Follow	`ChannelFollowSubscription()`	`event_follow()`	`ChannelFollow`
Channel Ad Break Begin	`AdBreakBeginSubscription()`	`event_ad_break()`	`ChannelAdBreakBegin`
Channel Bits Use	`ChannelBitsUseSubscription()`	`event_bits_use()`	`ChannelBitsUse`
Channel Chat Clear	`ChatClearSubscription()`	`event_chat_clear()`	`ChannelChatClear`
Channel Chat Clear User Messages	`ChatClearUserMessagesSubscription()`	`event_chat_clear_user()`	`ChannelChatClearUserMessages`
Channel Chat Message	`ChatMessageSubscription()`	`event_message()`	`ChatMessage`
Channel Chat Message Delete	`ChatMessageDeleteSubscription()`	`event_message_delete()`	`ChatMessageDelete`
Channel Chat Notification	`ChatNotificationSubscription()`	`event_chat_notification()`	`ChatNotification`
Channel Chat Settings Update	`ChatSettingsUpdateSubscription()`	`event_chat_settings_update()`	`ChatSettingsUpdate`
Channel Chat User Message Hold	`ChatUserMessageHoldSubscription()`	`event_chat_user_message_hold()`	`ChatUserMessageHold`
Channel Chat User Message Update	`ChatUserMessageUpdateSubscription()`	`event_chat_user_message_update()`	`ChatUserMessageUpdate`
Channel Shared Chat Session Begin	`SharedChatSessionBeginSubscription()`	`event_shared_chat_begin()`	`SharedChatSessionBegin`
Channel Shared Chat Session Update	`SharedChatSessionUpdateSubscription()`	`event_shared_chat_update()`	`SharedChatSessionUpdate`
Channel Shared Chat Session End	`SharedChatSessionEndSubscription()`	`event_shared_chat_end()`	`SharedChatSessionEnd`
Channel Subscribe	`ChannelSubscribeSubscription()`	`event_subscription()`	`ChannelSubscribe`
Channel Subscription End	`ChannelSubscriptionEndSubscription()`	`event_subscription_end()`	`ChannelSubscriptionEnd`
Channel Subscription Gift	`ChannelSubscriptionGiftSubscription()`	`event_subscription_gift()`	`ChannelSubscriptionGift`
Channel Subscription Message	`ChannelSubscribeMessageSubscription()`	`event_subscription_message()`	`ChannelSubscriptionMessage`
Channel Cheer	`ChannelCheerSubscription()`	`event_cheer()`	`ChannelCheer`
Channel Raid	`ChannelRaidSubscription()`	`event_raid()`	`ChannelRaid`
Channel Ban	`ChannelBanSubscription()`	`event_ban()`	`ChannelBan`
Channel Unban	`ChannelUnbanSubscription()`	`event_unban()`	`ChannelUnban`
Channel Unban Request Create	`ChannelUnbanRequestSubscription()`	`event_unban_request()`	`ChannelUnbanRequest`
Channel Unban Request Resolve	`ChannelUnbanRequestResolveSubscription()`	`event_unban_request_resolve()`	`ChannelUnbanRequestResolve`
Channel Moderate	`ChannelModerateSubscription()`	`event_mod_action()`	`ChannelModerate`
Channel Moderate V2	`ChannelModerateV2Subscription()`	`event_mod_action()`	`ChannelModerate`
Channel Moderator Add	`ChannelModeratorAddSubscription()`	`event_moderator_add()`	`ChannelModeratorAdd`
Channel Moderator Remove	`ChannelModeratorRemoveSubscription()`	`event_moderator_remove()`	`ChannelModeratorRemove`
Channel Points Automatic Reward Redemption	`ChannelPointsAutoRedeemSubscription()`	`event_automatic_redemption_add()`	`ChannelPointsAutoRedeemAdd`
Channel Points Custom Reward Add	`ChannelPointsRewardAddSubscription()`	`event_custom_reward_add()`	`ChannelPointsRewardAdd`
Channel Points Custom Reward Update	`ChannelPointsRewardUpdateSubscription()`	`event_custom_reward_update()`	`ChannelPointsRewardUpdate`
Channel Points Custom Reward Remove	`ChannelPointsRewardRemoveSubscription()`	`event_custom_reward_remove()`	`ChannelPointsRewardRemove`
Channel Points Custom Reward Redemption Add	`ChannelPointsRedeemAddSubscription()`	`event_custom_redemption_add()`	`ChannelPointsRedemptionAdd`
Channel Points Custom Reward Redemption Update	`ChannelPointsRedeemUpdateSubscription()`	`event_custom_redemption_update()`	`ChannelPointsRedemptionUpdate`
Channel Poll Begin	`ChannelPollBeginSubscription()`	`event_poll_begin()`	`ChannelPollBegin`
Channel Poll Progress	`ChannelPollProgressSubscription()`	`event_poll_progress()`	`ChannelPollProgress`
Channel Poll End	`ChannelPollEndSubscription()`	`event_poll_end()`	`ChannelPollEnd`
Channel Prediction Begin	`ChannelPredictionBeginSubscription()`	`event_prediction_begin()`	`ChannelPredictionBegin`
Channel Prediction Progress	`ChannelPredictionProgressSubscription()`	`event_prediction_progress()`	`ChannelPredictionProgress`
Channel Prediction Lock	`ChannelPredictionLockSubscription()`	`event_prediction_lock()`	`ChannelPredictionLock`
Channel Prediction End	`ChannelPredictionEndSubscription()`	`event_prediction_end()`	`ChannelPredictionEnd`
Channel Suspicious User Message	`SuspiciousUserMessageSubscription()`	`event_suspicious_user_message()`	`SuspiciousUserMessage`
Channel Suspicious User Update	`SuspiciousUserUpdateSubscription()`	`event_suspicious_user_update()`	`SuspiciousUserUpdate`
Channel VIP Add	`ChannelVIPAddSubscription()`	`event_vip_add()`	`ChannelVIPAdd`
Channel VIP Remove	`ChannelVIPRemoveSubscription()`	`event_vip_remove()`	`ChannelVIPRemove`
Channel Warning Acknowledgement	`ChannelWarningAcknowledgementSubscription()`	`event_warning_acknowledge()`	`ChannelWarningAcknowledge`
Channel Warning Send	`ChannelWarningSendSubscription()`	`event_warning_send()`	`ChannelWarningSend`
Charity Donation	`CharityDonationSubscription()`	`event_charity_campaign_donate()`	`CharityCampaignDonation`
Charity Campaign Start	`CharityCampaignStartSubscription()`	`event_charity_campaign_start()`	`CharityCampaignStart`
Charity Campaign Progress	`CharityCampaignProgressSubscription()`	`event_charity_campaign_progress()`	`CharityCampaignProgress`
Charity Campaign Stop	`CharityCampaignStopSubscription()`	`event_charity_campaign_stop()`	`CharityCampaignStop`
Goal Begin	`GoalBeginSubscription()`	`event_goal_begin()`	`GoalBegin`
Goal Progress	`GoalProgressSubscription()`	`event_goal_progress()`	`GoalProgress`
Goal End	`GoalEndSubscription()`	`event_goal_end()`	`GoalEnd`
Hype Train Begin	`HypeTrainBeginSubscription()`	`event_hype_train()`	`HypeTrainBegin`
Hype Train Progress	`HypeTrainProgressSubscription()`	`event_hype_train_progress()`	`HypeTrainProgress`
Hype Train End	`HypeTrainEndSubscription()`	`event_hype_train_end()`	`HypeTrainEnd`
Shield Mode Begin	`ShieldModeBeginSubscription()`	`event_shield_mode_begin()`	`ShieldModeBegin`
Shield Mode End	`ShieldModeEndSubscription()`	`event_shield_mode_end()`	`ShieldModeEnd`
Shoutout Create	`ShoutoutCreateSubscription()`	`event_shoutout_create()`	`ShoutoutCreate`
Shoutout Received	`ShoutoutReceiveSubscription()`	`event_shoutout_receive()`	`ShoutoutReceive`
Stream Online	`StreamOnlineSubscription()`	`event_stream_online()`	`StreamOnline`
Stream Offline	`StreamOfflineSubscription()`	`event_stream_offline()`	`StreamOffline`
User Authorization Grant	`UserAuthorizationGrantSubscription()`	`event_user_authorization_grant()`	`UserAuthorizationGrant`
User Authorization Revoke	`UserAuthorizationRevokeSubscription()`	`event_user_authorization_revoke()`	`UserAuthorizationRevoke`
User Update	`UserUpdateSubscription()`	`event_user_update()`	`UserUpdate`
Whisper Received	`WhisperReceivedSubscription()`	`event_message_whisper()`	`Whisper`

Client Events¶

async twitchio.event_ready() → None¶: Event dispatched when the Client is ready and has completed login.

async twitchio.event_error(payload: twitchio.EventErrorPayload) → None¶

Event dispatched when an exception is raised inside of a dispatched event.

Parameters: payload (twitchio.EventErrorPayload) – The payload containing information about the event and exception raised.

async twitchio.event_token_refreshed(payload: twitchio.TokenRefreshedPayload) → None:¶

Event dispatched when a token managed by the Client is successfully refreshed.

You can use this event to update the stored token locally as they are refreshed.

Parameters: payload (TokenRefreshedPayload) – The payload containing various information about the refreshed token.

async twitchio.event_oauth_authorized(payload: twitchio.authentication.UserTokenPayload) → None¶

Event dispatched when a user authorizes your Client-ID via Twitch OAuth on a built-in web adapter.

The default behaviour of this event is to add the authorized token to the client. See: add_token for more details.

Parameters: payload (UserTokenPayload) – The payload containing token information.

async twitchio.event_subscription_revoked(payload: SubscriptionRevoked) → None¶

Event dispatched when Twitch revokes a subscription. This can occur on websockets and webhooks. You’ll receive this message once and then no longer receive messages for the specified user and subscription type.

Webhook:

The user mentioned in the subscription no longer exists. The notification’s status is set to user_removed.
The user revoked the authorization token or simply changed their password. The notification’s status is set to authorization_revoked.
The callback failed to respond in a timely manner too many times. The notification’s status is set to notification_failures_exceeded.
The subscribed to subscription type and version is no longer supported. The notification’s status is set to version_removed.

Websocket:

The user mentioned in the subscription no longer exists. The notification’s status field is set to user_removed.
The user revoked the authorization token that the subscription relied on. The notification’s status field is set to authorization_revoked.
The subscribed to subscription type and version is no longer supported. The notification’s status field is set to version_removed.

Parameters: payload (SubscriptionRevoked) – The payload containing token information.

async twitchio.event_websocket_welcome(payload: WebsocketWelcome) → None¶

Event dispatched when a websocket successfully connects to Twitch via Eventsub or Conduits.

Parameters: payload (WebsocketWelcome) – The payload containing information about the connected websocket.

Commands Events¶

async twitchio.event_command_invoked(ctx: twitchio.ext.commands.Context) → None¶

Event dispatched when a Command is invoked.

Parameters: ctx (twitchio.ext.commands.Context) – The context object that invoked the command.

async twitchio.event_command_completed(ctx: twitchio.ext.commands.Context) → None¶

Event dispatched when a Command has completed invocation.

Parameters: ctx (twitchio.ext.commands.Context) – The context object that invoked the command.

async twitchio.event_command_error(payload: twitchio.ext.commands.CommandErrorPayload) → None¶

Event dispatched when a Command encounters an error during invocation.

By default, every Bot implements this event. You can override the default implementation of this event to fine-tune errors. Care should be taken to make sure unexpected exceptions are properly logged or made aware of.

Below is a small example of overriding the default implementation in a Component. This, when used in an extension allows your error handler to be hot-reloaded without losing access to a proper exception handler.

Parameters: payload (twitchio.ext.commands.CommandErrorPayload) – The error payload containing context and the exception raised.

Example

import logging

from twitchio.ext import commands


logger = logging.getLogger(__name__)


class ErrorComponent(commands.Component):

    def __init__(self, bot: commands.Bot) -> None:
        # Store the original error handler; if we re/unload this component it will be reassigned to our bot...
        self.original = bot.event_command_error

        # Override the default error handler...
        bot.event_command_error = self.event_command_error

        self.bot = bot

    async def component_teardown(self) -> None:
        # Reassign the original error handler...
        self.bot.event_command_error = self.original

    async def event_command_error(self, payload: commands.CommandErrorPayload) -> None:
        ctx = payload.context
        command = ctx.command
        error = payload.exception

        # We don't want to dispatch errors that have already been handled before...
        if command and command.has_error and ctx.error_dispatched:
            return

        # Example: A common error to suppress is the CommandNotFound error...
        if isinstance(error, commands.CommandNotFound):
            return

        # Example: As an example if a guard fails we can send a default message back...
        if isinstance(error, commands.GuardFailure):
            await ctx.send(f"{ctx.chatter} you do not have permission to use this command.")

        # For all unhandled errors, we should log them so we know what went wrong...
        msg = f'Ignoring exception in command "{ctx.command}":\n'
        logger.error(msg, exc_info=error)


async def setup(bot: commands.Bot) -> None:
    await bot.add_component(ErrorComponent(bot))

Automod¶

async twitchio.event_automod_message_hold(payload: twitchio.AutomodMessageHold) → None¶

Event dispatched when a message is held by Automod and needs review.

Corresponds to the Twitch EventSub subscriptions Automod Message Hold and Automod Message Hold V2.

You must subscribe to EventSub with AutomodMessageHoldSubscription or AutomodMessageHoldV2Subscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.AutomodMessageHold) – The EventSub payload received for this event.

async twitchio.event_automod_message_update(payload: twitchio.AutomodMessageUpdate) → None¶

Event dispatched when a message held by Automod status changes.

Corresponds to the Twitch EventSub subscriptions Automod Message Update and Automod Message Update V2.

You must subscribe to EventSub with AutomodMessageUpdateSubscription or AutomodMessageUpdateV2Subscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.AutomodMessageUpdate) – The EventSub payload received for this event.

async twitchio.event_automod_settings_update(payload: twitchio.AutomodSettingsUpdate) → None¶

Event dispatched when a broadcaster’s automod settings are updated.

Corresponds to the Twitch EventSub subscriptions Automod Settings Update

You must subscribe to EventSub with AutomodSettingsUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.AutomodSettingsUpdate) – The EventSub payload received for this event.

async twitchio.event_automod_terms_update(payload: twitchio.AutomodTermsUpdate) → None¶

Event dispatched when a broadcaster’s automod terms are updated. Changes to private terms are not sent.

Corresponds to the Twitch EventSub subscriptions Automod Terms Update

You must subscribe to EventSub with AutomodTermsUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.AutomodTermsUpdate) – The EventSub payload received for this event.

Bans¶

async twitchio.event_ban(payload: twitchio.ChannelBan) → None¶

Event dispatched when a viewer is banned from the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Ban

You must subscribe to EventSub with ChannelBanSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelBan) – The EventSub payload received for this event.

async twitchio.event_unban(payload: twitchio.ChannelUnban) → None¶

Event dispatched when a viewer is unbanned from the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Unban

You must subscribe to EventSub with ChannelUnbanSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelUnban) – The EventSub payload received for this event.

async twitchio.event_unban_request(payload: twitchio.ChannelUnbanRequest) → None¶

Event dispatched when user creates an unban request.

Corresponds to the Twitch EventSub subscriptions Channel Unban Request Create

You must subscribe to EventSub with ChannelUnbanRequestSubscription for each required broadcaster, with moderator, to receive this event.

Parameters: payload (twitchio.ChannelUnbanRequest) – The EventSub payload received for this event.

async twitchio.event_unban_request_resolve(payload: twitchio.ChannelUnbanRequest) → None¶

Event dispatched when an unban request is resolved.

Corresponds to the Twitch EventSub subscriptions Channel Unban Request Resolve

You must subscribe to EventSub with ChannelUnbanRequestResolveSubscription for each required broadcaster, with moderator, to receive this event.

Parameters: payload (twitchio.ChannelUnbanRequest) – The EventSub payload received for this event.

Channel / Broadcaster¶

async twitchio.event_channel_update(payload: twitchio.ChannelUpdate) → None¶

Event dispatched when a broadcaster updates their channel properties e.g. category, title, content classification labels, broadcast, or language.

Corresponds to the Twitch EventSub subscriptions Channel Update

You must subscribe to EventSub with ChannelUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelUpdate) – The EventSub payload received for this event.

async twitchio.event_follow(payload: twitchio.ChannelFollow) → None¶

Event dispatched when someone follows a channel.

Corresponds to the Twitch EventSub subscriptions Channel Follow

You must subscribe to EventSub with ChannelFollowSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelFollow) – The EventSub payload received for this event.

async twitchio.event_ad_break(payload: twitchio.ChannelAdBreakBegin) → None¶

Event dispatched when a midroll commercial break has started running.

Corresponds to the Twitch EventSub subscriptions Channel Ad Break Begin

You must subscribe to EventSub with AdBreakBeginSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelAdBreakBegin) – The EventSub payload received for this event.

async twitchio.event_cheer(payload: twitchio.ChannelCheer) → None¶

Event dispatched when a user cheers on the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Cheer

You must subscribe to EventSub with ChannelCheerSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelCheer) – The EventSub payload received for this event.

async twitchio.event_raid(payload: twitchio.ChannelRaid) → None¶

Event dispatched when a user broadcaster raids another broadcaster’s channel.

Corresponds to the Twitch EventSub subscriptions Channel Raid

You must subscribe to EventSub with ChannelRaidSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelRaid) – The EventSub payload received for this event.

Channel Points¶

async twitchio.event_automatic_redemption_add(payload: twitchio.ChannelPointsAutoRedeemAdd) → None¶

Event dispatched when a viewer has redeemed an automatic channel points reward on the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Points Automatic Reward Redemption

You must subscribe to EventSub with ChannelPointsAutoRedeemSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelPointsAutoRedeemAdd) – The EventSub payload received for this event.

async twitchio.event_custom_reward_add(payload: twitchio.ChannelPointsRewardAdd) → None¶

Event dispatched when a custom channel points reward has been created for the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Points Custom Reward Add

You must subscribe to EventSub with ChannelPointsRewardAddSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelPointsRewardAdd) – The EventSub payload received for this event.

async twitchio.event_custom_reward_update(payload: twitchio.ChannelPointsRewardUpdate) → None¶

Event dispatched when a custom channel points reward has been updated for the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Points Custom Reward Update

You must subscribe to EventSub with ChannelPointsRewardUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelPointsRewardUpdate) – The EventSub payload received for this event.

async twitchio.event_custom_reward_remove(payload: twitchio.ChannelPointsRewardRemove) → None¶

Event dispatched when a custom channel points reward has been removed from the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Points Custom Reward Remove

You must subscribe to EventSub with ChannelPointsRewardRemoveSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelPointsRewardRemove) – The EventSub payload received for this event.

async twitchio.event_custom_redemption_add(payload: twitchio.ChannelPointsRedemptionAdd) → None¶

Event dispatched when a viewer has redeemed a custom channel points reward on the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Points Custom Reward Redemption Add

You must subscribe to EventSub with ChannelPointsRedeemAddSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelPointsRedemptionAdd) – The EventSub payload received for this event.

async twitchio.event_custom_redemption_update(payload: twitchio.ChannelPointsRedemptionUpdate) → None¶

Event dispatched when a redemption of a channel points custom reward has been updated for the specified channel.

Corresponds to the Twitch EventSub subscriptions Channel Points Custom Reward Redemption Update

You must subscribe to EventSub with ChannelPointsRedeemUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelPointsRedemptionUpdate) – The EventSub payload received for this event.

Charity Campaigns¶

async twitchio.event_charity_campaign_donate(payload: twitchio.CharityCampaignDonation) → None¶

Event dispatched when a user donates to the broadcaster’s charity campaign.

Corresponds to the Twitch EventSub subscription Charity Donation.

You must subscribe to EventSub with CharityDonationSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.CharityCampaignDonation) – The EventSub payload for this event.

async twitchio.event_charity_campaign_start(payload: twitchio.CharityCampaignStart) → None¶

Event dispatched when the broadcaster starts a charity campaign.

Corresponds to the Twitch EventSub subscription Charity Campaign Start.

You must subscribe to EventSub with CharityCampaignStartSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.CharityCampaignStart) – The EventSub payload for this event.

async twitchio.event_charity_campaign_progress(payload: twitchio.CharityCampaignProgress) → None¶

Event dispatched when progress is made towards the campaign’s goal or when the broadcaster changes the fundraising goal.

Corresponds to the Twitch EventSub subscription Charity Campaign Progress.

You must subscribe to EventSub with CharityCampaignProgressSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.CharityCampaignProgress) – The EventSub payload for this event.

async twitchio.event_charity_campaign_stop(payload: twitchio.CharityCampaignStop) → None¶

Event dispatched when the broadcaster stops a charity campaign.

Corresponds to the Twitch EventSub subscription Charity Campaign Stop.

You must subscribe to EventSub with CharityCampaignStopSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.CharityCampaignStop) – The EventSub payload for this event.

Chat / Messages¶

async twitchio.event_message(payload: twitchio.ChatMessage) → None¶

Event dispatched when a user sends a message to a chat room.

Corresponds to the Twitch EventSub subscriptions Channel Chat Message

You must subscribe to EventSub with ChatMessageSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChatMessage) – The EventSub payload received for this event.

async twitchio.event_message_delete(payload: twitchio.ChatMessageDelete) → None¶

Event dispatched when a moderator has removed a specific message.

Corresponds to the Twitch EventSub subscriptions Channel Chat Message Delete

You must subscribe to EventSub with ChatMessageDeleteSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChatMessageDelete) – The EventSub payload received for this event.

async twitchio.event_chat_clear(payload: twitchio.ChannelChatClear) → None¶

Event dispatched when a moderator or bot has cleared all messages from the chat room.

Corresponds to the Twitch EventSub subscriptions Channel Chat Clear

You must subscribe to EventSub with ChatClearSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelChatClear) – The EventSub payload received for this event.

async twitchio.event_chat_clear_user(payload: twitchio.ChannelChatClearUserMessages) → None¶

Event dispatched when a moderator or bot has cleared all messages from a specific user.

Corresponds to the Twitch EventSub subscriptions Channel Chat Clear User Messages

You must subscribe to EventSub with ChatClearUserMessagesSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelChatClearUserMessages) – The EventSub payload received for this event.

async twitchio.event_chat_notification(payload: twitchio.ChatNotification) → None¶

Event dispatched when an event that appears in chat has occurred. This event can be used to replace multiple other events, depending on the data required.

Corresponds to the Twitch EventSub subscriptions Channel Chat Notification

You must subscribe to EventSub with ChatNotificationSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChatNotification) – The EventSub payload received for this event.

async twitchio.event_chat_settings_update(payload: twitchio.ChatSettingsUpdate) → None¶

Event dispatched when a broadcaster’s chat settings are updated.

Corresponds to the Twitch EventSub subscriptions Channel Chat Settings Update

You must subscribe to EventSub with ChatSettingsUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChatSettingsUpdate) – The EventSub payload received for this event.

async twitchio.event_chat_user_message_hold(payload: twitchio.ChatUserMessageHold) → None¶

Event dispatched when a user is notified if their message is caught by automod.

Corresponds to the Twitch EventSub subscriptions Channel Chat User Message Hold

You must subscribe to EventSub with ChatUserMessageHoldSubscription for each required broadcaster and user to receive this event.

Parameters: payload (twitchio.ChatUserMessageHold) – The EventSub payload received for this event.

async twitchio.event_chat_user_message_update(payload: twitchio.ChatUserMessageUpdate) → None¶

Event dispatched when a user is notified if their message’s automod status is updated.

Corresponds to the Twitch EventSub subscriptions Channel Chat User Message Hold

You must subscribe to EventSub with ChatUserMessageUpdateSubscription for each required broadcaster and user to receive this event.

Parameters: payload (twitchio.ChatUserMessageUpdate) – The EventSub payload received for this event.

async twitchio.event_message_whisper(payload: twitchio.Whisper) → None¶

Event dispatched when a user receives this a whisper.

Corresponds to the Twitch EventSub subscription User Whisper.

You must subscribe to EventSub with WhisperReceivedSubscription for each required user to receive this event.

Parameters: payload (twitchio.Whisper) – The EventSub payload for this event.

async twitchio.event_bits_use(payload: twitchio.ChannelBitsUse) → None¶

Event dispatched whenever Bits are used on a channel.

Corresponds to the Twitch EventSub subscription Channel Bits Use.

You must subscribe to EventSub with ChannelBitsUseSubscription for each required user to receive this event.

Parameters: payload (twitchio.ChannelBitsUse) – The EventSub payload for this event.

Goals¶

async twitchio.event_goal_begin(payload: twitchio.GoalBegin) → None¶

Event dispatched when a broadcaster begins a goal.

Corresponds to the Twitch EventSub subscription Goal Begin.

You must subscribe to EventSub with GoalBeginSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.GoalBegin) – The EventSub payload for this event.

async twitchio.event_goal_progress(payload: twitchio.GoalProgress) → None¶

Event dispatched when progress (either positive or negative) is made towards a broadcaster’s goal.

Corresponds to the Twitch EventSub subscription Goal Progress.

You must subscribe to EventSub with GoalProgressSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.GoalProgress) – The EventSub payload for this event.

async twitchio.event_goal_end(payload: twitchio.GoalEnd) → None¶

Event dispatched when a broadcaster ends a goal.

Corresponds to the Twitch EventSub subscription Goal End.

You must subscribe to EventSub with GoalEndSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.GoalEnd) – The EventSub payload for this event.

Hype Train¶

async twitchio.event_hype_train(payload: twitchio.HypeTrainBegin) → None¶

Event dispatched when a Hype Train begins on the specified channel.

Corresponds to the Twitch EventSub subscription Hype Train Begin.

You must subscribe to EventSub with HypeTrainBeginSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.HypeTrainBegin) – The EventSub payload for this event.

async twitchio.event_hype_train_progress(payload: twitchio.HypeHypeTrainProgress) → None¶

Event dispatched when a Hype Train makes progress on the specified channel.

Corresponds to the Twitch EventSub subscription Hype Train Progress.

You must subscribe to EventSub with HypeTrainProgressSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.HypeTrainProgress) – The EventSub payload for this event.

async twitchio.event_hype_train_end(payload: twitchio.HypeTrainEnd) → None¶

Event dispatched when a Hype Train ends on the specified channel.

Corresponds to the Twitch EventSub subscription Hype Train End.

You must subscribe to EventSub with HypeTrainEndSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.HypeTrainEnd) – The EventSub payload for this event.

Moderation¶

async twitchio.event_mod_action(payload: twitchio.ChannelModerate) → None¶

Event dispatched when a moderator performs a moderation action in a channel. If you subscribe to V2 then warnings are included.

Corresponds to the Twitch EventSub subscriptions Channel Moderate and Channel Moderate V2.

You must subscribe to EventSub with ChannelModerateSubscription or ChannelModerateV2Subscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelModerate) – The EventSub payload for this event.

async twitchio.event_moderator_add(payload: twitchio.ChannelModeratorAdd) → None¶

Event dispatched when moderator privileges were added to a user on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Moderator Add.

You must subscribe to EventSub with ChannelModeratorAddSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelModeratorAdd) – The EventSub payload for this event.

async twitchio.event_moderator_remove(payload: twitchio.ChannelModeratorRemove) → None¶

Event dispatched when moderator privileges were rmoved from a user on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Moderator Removed.

You must subscribe to EventSub with ChannelModeratorRemoveSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelModeratorRemove) – The EventSub payload for this event.

async twitchio.event_vip_add(payload: twitchio.ChannelVIPAdd) → None¶

Event dispatched when a vip is added to the channel.

Corresponds to the Twitch EventSub subscription Channel VIP Add.

You must subscribe to EventSub with ChannelVIPAddSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelVIPAdd) – The EventSub payload for this event.

async twitchio.event_vip_remove(payload: twitchio.ChannelVIPRemove) → None¶

Event dispatched when a vip is removed from the channel.

Corresponds to the Twitch EventSub subscription Channel VIP Remove.

You must subscribe to EventSub with ChannelVIPRemoveSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelVIPRemove) – The EventSub payload for this event.

Polls¶

async twitchio.event_poll_begin(payload: twitchio.ChannelPollBegin) → None¶

Event dispatched when a poll started on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Poll Begin.

You must subscribe to EventSub with ChannelPollBeginSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPollBegin) – The EventSub payload for this event.

async twitchio.event_poll_progress(payload: twitchio.ChannelPollProgress) → None¶

Event dispatched when users respond to a poll on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Poll Progress.

You must subscribe to EventSub with ChannelPollProgressSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPollProgress) – The EventSub payload for this event.

async twitchio.event_poll_end(payload: twitchio.ChannelPollEnd) → None¶

Event dispatched when a poll ends on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Poll End.

You must subscribe to EventSub with ChannelPollEndSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPollEnd) – The EventSub payload for this event.

Predictions¶

async twitchio.event_prediction_begin(payload: twitchio.ChannelPredictionBegin) → None¶

Event dispatched when a prediction begins on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Prediction Begin.

You must subscribe to EventSub with ChannelPredictionBeginSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPredictionBegin) – The EventSub payload for this event.

async twitchio.event_prediction_progress(payload: twitchio.ChannelPredictionProgress) → None¶

Event dispatched when users participated in a Prediction on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Prediction Progress.

You must subscribe to EventSub with ChannelPredictionProgressSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPredictionProgress) – The EventSub payload for this event.

async twitchio.event_prediction_lock(payload: twitchio.ChannelPredictionLock) → None¶

Event dispatched when a prediction was locked on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Prediction Lock.

You must subscribe to EventSub with ChannelPredictionLockSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPredictionLock) – The EventSub payload for this event.

async twitchio.event_prediction_end(payload: twitchio.ChannelPredictionEnd) → None¶

Event dispatched when a prediction ended on a specified channel.

Corresponds to the Twitch EventSub subscription Channel Prediction End.

You must subscribe to EventSub with ChannelPredictionEndSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ChannelPredictionEnd) – The EventSub payload for this event.

Shared Chat¶

async twitchio.event_shared_chat_begin(payload: twitchio.SharedChatSessionBegin) → None¶

Event dispatched when a channel becomes active in an active shared chat session.

Corresponds to the Twitch EventSub subscription Channel Shared Chat Session Begin.

You must subscribe to EventSub with SharedChatSessionBeginSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.SharedChatSessionBegin) – The EventSub payload for this event.

async twitchio.event_shared_chat_update(payload: twitchio.SharedChatSessionUpdate) → None¶

Event dispatched when the active shared chat session the channel is in changes.

Corresponds to the Twitch EventSub subscription Channel Shared Chat Session Update.

You must subscribe to EventSub with SharedChatSessionUpdateSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.SharedChatSessionUpdate) – The EventSub payload for this event.

async twitchio.event_shared_chat_end(payload: twitchio.SharedChatSessionEnd) → None¶

Event dispatched when a channel leaves a shared chat session or the session ends.

Corresponds to the Twitch EventSub subscription Channel Shared Chat Session End.

You must subscribe to EventSub with SharedChatSessionEndSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.SharedChatSessionEnd) – The EventSub payload for this event.

Shield Mode¶

async twitchio.event_shield_mode_begin(payload: twitchio.ShieldModeBegin) → None¶

Event dispatched when the broadcaster activates Shield Mode.

Corresponds to the Twitch EventSub subscription Shield Mode Begin.

You must subscribe to EventSub with ShieldModeBeginSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ShieldModeBegin) – The EventSub payload for this event.

async twitchio.event_shield_mode_end(payload: twitchio.ShieldModeEnd) → None¶

Event dispatched when the broadcaster deactivates Shield Mode.

Corresponds to the Twitch EventSub subscription Shield Mode End.

You must subscribe to EventSub with ShieldModeEndSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ShieldModeEnd) – The EventSub payload for this event.

Shoutouts¶

async twitchio.event_shoutout_create(payload: twitchio.ShoutoutCreate) → None¶

Event dispatched when the specified broadcaster sends a shoutout.

Corresponds to the Twitch EventSub subscription Shoutout Create.

You must subscribe to EventSub with ShoutoutCreateSubscription for each required broadcaster to receive this event to receive this event.

Parameters: payload (twitchio.ShoutoutCreate) – The EventSub payload for this event.

async twitchio.event_shoutout_receive(payload: twitchio.ShoutoutReceive) → None¶

Event dispatched when the specified broadcaster receives a shoutout.

Corresponds to the Twitch EventSub subscription Shoutout Create.

You must subscribe to EventSub with ShoutoutReceiveSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ShoutoutReceive) – The EventSub payload for this event.

Subscriptions¶

async twitchio.event_subscription(payload: twitchio.ChannelSubscribe) → None¶

Event dispatched when a specified channel receives a subscriber. This does not include resubscribes.

Corresponds to the Twitch EventSub subscription Channel Subscribe.

You must subscribe to EventSub with ChannelSubscribeSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelSubscribe) – The EventSub payload for this event.

async twitchio.event_subscription_end(payload: twitchio.ChannelSubscriptionEnd) → None¶

Event dispatched when a subscription to the specified channel ends.

Corresponds to the Twitch EventSub subscription Channel Subscription End.

You must subscribe to EventSub with ChannelSubscriptionEndSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelSubscriptionEnd) – The EventSub payload for this event.

async twitchio.event_subscription_gift(payload: twitchio.ChannelSubscriptionGift) → None¶

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

Corresponds to the Twitch EventSub subscription Channel Subscription Gift.

You must subscribe to EventSub with ChannelSubscriptionGiftSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelSubscriptionGift) – The EventSub payload for this event.

async twitchio.event_subscription_message(payload: twitchio.ChannelSubscriptionMessage) → None¶

Event dispatched when a user sends a resubscription chat message in a specific channel.

Corresponds to the Twitch EventSub subscription Channel Subscription Message.

You must subscribe to EventSub with ChannelSubscriptionMessageSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.ChannelSubscriptionMessage) – The EventSub payload for this event.

Streams¶

async twitchio.event_stream_online(payload: twitchio.StreamOnline) → None¶

Event dispatched when a stream comes online.

Corresponds to the Twitch EventSub subscription Stream Online.

You must subscribe to EventSub with StreamOnlineSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.StreamOnline) – The EventSub payload for this event.

async twitchio.event_stream_offline(payload: twitchio.StreamOffline) → None¶

Event dispatched when a stream goes offline.

Corresponds to the Twitch EventSub subscription Stream Offline.

You must subscribe to EventSub with StreamOfflineSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.StreamOffline) – The EventSub payload for this event.

Suspicious Users¶

async twitchio.event_suspicious_user_message(payload: twitchio.SuspiciousUserMessage) → None¶

Event dispatched when chat message has been sent by a suspicious user.

Corresponds to the Twitch EventSub subscription Channel Suspicious User Message.

You must subscribe to EventSub with SuspiciousUserMessageSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.SuspiciousUserMessage) – The EventSub payload for this event.

async twitchio.event_suspicious_user_update(payload: twitchio.SuspiciousUserUpdate) → None¶

Event dispatched when a suspicious user has been updated.

Corresponds to the Twitch EventSub subscription Channel Suspicious User Update.

You must subscribe to EventSub with SuspiciousUserUpdateSubscription for each required broadcaster to receive this event.

Parameters: payload (twitchio.SuspiciousUserUpdate) – The EventSub payload for this event.

OAuth¶

async twitchio.event_user_authorization_grant(payload: twitchio.UserAuthorizationGrant) → None¶

Event dispatched when a user’s authorization has been granted for your client id.

Corresponds to the Twitch EventSub subscription User Authorization Grant.

You must subscribe to EventSub with UserAuthorizationRevokeSubscription to receive this event.

Parameters: payload (twitchio.UserAuthorizationGrant) – The EventSub payload for this event.

async twitchio.event_user_authorization_revoke(payload: twitchio.UserAuthorizationRevoke) → None¶

Event dispatched when a user’s authorization has been revoked for your client id.

Corresponds to the Twitch EventSub subscription User Authorization Revoke.

You must subscribe to EventSub with UserAuthorizationRevokeSubscription to receive this event.

Parameters: payload (twitchio.UserAuthorizationRevoke) – The EventSub payload for this event.

User¶

async twitchio.event_user_update(payload: twitchio.UserUpdate) → None¶

Event dispatched when a user has updated their account.

Corresponds to the Twitch EventSub subscription User Update.

You must subscribe to EventSub with UserUpdateSubscription for each required user to receive this event.

Parameters: payload (twitchio.UserUpdate) – The EventSub payload for this event.

Warnings¶

async twitchio.event_warning_acknowledge(payload: twitchio.ChannelWarningAcknowledge) → None¶

Event dispatched when a user awknowledges a warning. Broadcasters and moderators can see the warning’s details.

Corresponds to the Twitch EventSub subscription Channel Warning Acknowledgement.

You must subscribe to EventSub with ChannelWarningAcknowledgementSubscription for each required broadcaster, with a moderator, to receive this event.

Parameters: payload (twitchio.ChannelWarningAcknowledge) – The EventSub payload for this event.

async twitchio.event_warning_send(payload: twitchio.ChannelWarningSend) → None¶

Event dispatched when a user is sent a warning. Broadcasters and moderators can see the warning’s details.

Corresponds to the Twitch EventSub subscription Channel Warning Send.

You must subscribe to EventSub with ChannelWarningSendSubscription for each required broadcaster, with a moderator, to receive this event.

Parameters: payload (twitchio.ChannelWarningSend) – The EventSub payload for this event.

Payloads¶

Attributes

error
listener
original

class twitchio.EventErrorPayload¶

Payload received in the Client.event_error event when an error occurs during an event listener.

error¶

The error that occurred.

Type: Exception

listener¶

The listener that raised the error.

Type: Callable[…, Coroutine[Any, Any, None]]

original¶

The original event payload that was passed to the listener that caused the error.

Type: Any

Attributes

expires_in
refresh_token
scopes
token
user_id

class twitchio.TokenRefreshedPayload¶

Payload received in the event_token_refreshed() event when a token managed by TwitchIO is successfully refreshed on the Client.

user_id¶

The User ID associated with the refreshed token.

Type: str

refresh_token¶

The new refresh token returned by Twitch.

Type: str

token¶

The updated token after refreshing returned by Twitch.

Type: str

scopes¶

The scopes associated with the token.

Type: Scopes

expires_in¶

The time the new token expires as an int of seconds.

Type: int

Attributes

connected_at
id
keepalive_timeout_seconds

class twitchio.WebsocketWelcome¶

The model received in the event_websocket_welcome() event.

id¶

The ID associated with the Websocket, received from Twitch in “session_welcome”.

Type: str

keepalive_timeout_seconds¶

The keepalive timeout as an int sent and confirmed by Twitch.

Type: int

connected_at¶

A datetime.datetime representing when this websocket officially connected.

Type: datetime.datetime