EventSub Ext#

The EventSub ext is made to receive eventsub webhook notifications from twitch. For those not familiar with eventsub, it allows you to subscribe to certain events, and when these events happen, Twitch will send you an HTTP request containing information on the event. This ext abstracts away the complex portions of this, integrating seamlessly into the twitchio Client event dispatching system.

Warning

This ext requires you to have a public facing ip AND domain, and to be able to receive inbound requests.

Note

Twitch requires EventSub targets to have TLS/SSL enabled (https). TwitchIO does not support this, as such you should use a reverse proxy such as nginx to handle TLS/SSL.

A Quick Example#

import twitchio
from twitchio.ext import eventsub, commands
bot = commands.Bot(token="...")
eventsub_client = eventsub.EventSubClient(bot, "some_secret_string", "https://your-url.here/callback")
# when subscribing (you can only await inside coroutines)

await eventsub_client.subscribe_channel_subscriptions(channel_ID)

@bot.event()
async def eventsub_notification_subscription(payload: eventsub.ChannelSubscribeData):
  ...

bot.loop.create_task(eventsub_client.listen(port=4000))
bot.loop.create_task(bot.start())
bot.loop.run_forever()

Running Eventsub Inside a Commands Bot#

import twitchio
from twitchio.ext import commands, eventsub

esbot = commands.Bot.from_client_credentials(client_id='...',
                                         client_secret='...')
esclient = eventsub.EventSubClient(esbot,
                                   webhook_secret='...',
                                   callback_route='https://your-url.here/callback')


class Bot(commands.Bot):

    def __init__(self):
        super().__init__(token='...', prefix='!', initial_channels=['channel'])

    async def __ainit__(self) -> None:
        self.loop.create_task(esclient.listen(port=4000))

        try:
            await esclient.subscribe_channel_follows_v2(broadcaster=some_channel_ID, moderator=a_channel_mod_ID)
        except twitchio.HTTPException:
            pass

    async def event_ready(self):
        print('Bot is ready!')


bot = Bot()
bot.loop.run_until_complete(bot.__ainit__())


@esbot.event()
async def event_eventsub_notification_followV2(payload: eventsub.ChannelFollowData) -> None:
    print('Received event!')
    channel = bot.get_channel('channel')
    await channel.send(f'{payload.data.user.name} followed woohoo!')

bot.run()

Event Reference#

This is a list of events dispatched by the eventsub ext.

twitchio.ext.eventsub.event_eventsub_notification_user_authorization_grant(event: UserAuthorizationGrantedData)#

Called when your app has had access granted on a channel.

twitchio.ext.eventsub.event_eventsub_revokation(event: RevokationEvent)#

Called when your app has had access revoked on a channel.

twitchio.ext.eventsub.event_eventsub_webhook_callback_verification(event: ChallengeEvent)#

Called when Twitch sends a challenge to your server.

Note

You generally won’t need to interact with this event. The ext will handle responding to the challenge automatically.

twitchio.ext.eventsub.event_eventsub_keepalive(event: KeepaliveEvent)#

Called when a Twitch sends a keepalive event. You do not need to use this in daily usage.

Note

You generally won’t need to interact with this event.

twitchio.ext.eventsub.event_eventsub_reconnect(event: ReconnectEvent)#

Called when a Twitch wishes for us to reconnect.

Note

You generally won’t need to interact with this event. The library will automatically handle reconnecting.

twitchio.ext.eventsub.event_eventsub_notification_follow(event: ChannelFollowData)#

Called when someone creates a follow on a channel you’ve subscribed to.

Warning

Twitch has removed this, please use event_eventsub_notification_followV2()

twitchio.ext.eventsub.event_eventsub_notification_followV2(event: ChannelFollowData)#

Called when someone creates a follow on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_subscription(event: ChannelSubscribeData)#

Called when someone subscribes to a channel that you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_subscription_end(event: ChannelSubscriptionEndData)#

Called when a subscription to a channel that you’ve subscribed to ends.

twitchio.ext.eventsub.event_eventsub_notification_subscription_gift(event: ChannelSubscriptionGiftData)#

Called when someone gifts a subscription to a channel that you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_subscription_message(event: ChannelSubscriptionMessageData)#

Called when someone resubscribes with a message to a channel that you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_cheer(event: ChannelCheerData)#

Called when someone cheers on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_raid(event: ChannelRaidData)#

Called when someone raids a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_poll_begin(event: PollBeginProgressData)#

Called when a poll begins on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_poll_progress(event: PollBeginProgressData)#

Called repeatedly while a poll is running on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_poll_end(event: PollEndData)#

Called when a poll ends on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_prediction_begin(event: PredictionBeginProgressData)#

Called when a prediction starts on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_prediction_progress(event: PredictionBeginProgressData)#

Called repeatedly while a prediction is running on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_prediction_lock(event: PredictionLockData)#

Called when a prediction locks on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_prediction_end(event: PredictionEndData)#

Called when a prediction ends on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_stream_start(event: StreamOnlineData)#

Called when a stream starts on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_stream_end(event: StreamOfflineData)#

Called when a stream ends on a channel you’ve subscribed to.

twitchio.ext.eventsub.event_eventsub_notification_channel_goal_begin(event: ChannelGoalBeginProgressData)#

Called when a streamer starts a goal on their channel.

twitchio.ext.eventsub.event_eventsub_notification_channel_goal_progress(event: ChannelGoalBeginProgressData)#

Called when there is an update event to a channel’s goal.

twitchio.ext.eventsub.event_eventsub_notification_channel_goal_end(event: ChannelGoalEndData)#

Called when someone ends a goal on their channel.

twitchio.ext.eventsub.event_eventsub_notification_hypetrain_begin(event: HypeTrainBeginProgressData)#

Called when a hype train starts on their channel.

twitchio.ext.eventsub.event_eventsub_notification_hypetrain_progress(event: HypeTrainBeginProgressData)#

Called when a hype train receives an update on their channel.

twitchio.ext.eventsub.event_eventsub_notification_hypetrain_end(event: HypeTrainEndData)#

Called when a hype train ends on their channel.

twitchio.ext.eventsub.event_eventsub_notification_channel_shield_mode_begin(event: ChannelShieldModeBeginData)#

Called when a channel’s Shield Mode status is activated.

twitchio.ext.eventsub.event_eventsub_notification_channel_shield_mode_end(event: ChannelShieldModeEndData)#

Called when a channel’s Shield Mode status is deactivated.

twitchio.ext.eventsub.event_eventsub_notification_channel_shoutout_create(event: ChannelShoutoutCreateData)#

Called when a channel sends a shoutout.

twitchio.ext.eventsub.event_eventsub_notification_channel_shoutout_receive(event: ChannelShoutoutReceiveData)#

Called when a channel receives a shoutout.

twitchio.ext.eventsub.event_eventsub_notification_channel_charity_donate(event: ChannelCharityDonationData)#

Called when a user donates to an active charity campaign.

API Reference#

Methods
class twitchio.ext.eventsub.EventSubClient(client: Client, webhook_secret: str, callback_route: str, token: Optional[str] = None)#
coroutine delete_all_active_subscriptions()#
coroutine delete_subscription(subscription_id: str)#
coroutine get_subscriptions(status: Optional[str] = None, sub_type: Optional[str] = None, user_id: Optional[int] = None)#
coroutine listen(**kwargs)#
stop()#
subscribe_channel_bans(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_charity_donate(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_cheers(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_follows(broadcaster: Union[PartialUser, str, int])#

Warning

This endpoint is deprecated, use subscribe_channel_follows_v2()

subscribe_channel_follows_v2(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int])#
subscribe_channel_goal_begin(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_goal_end(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_goal_progress(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_hypetrain_begin(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_hypetrain_end(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_hypetrain_progress(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_moderators_add(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_moderators_remove(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_points_redeem_updated(broadcaster: Union[PartialUser, str, int], reward_id: Optional[str] = None)#
subscribe_channel_points_redeemed(broadcaster: Union[PartialUser, str, int], reward_id: Optional[str] = None)#
subscribe_channel_points_reward_added(broadcaster: Union[PartialUser, str, int], reward_id: str)#
subscribe_channel_points_reward_removed(broadcaster: Union[PartialUser, str, int], reward_id: str)#
subscribe_channel_points_reward_updated(broadcaster: Union[PartialUser, str, int], reward_id: str)#
subscribe_channel_poll_begin(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_poll_end(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_poll_progress(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_prediction_begin(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_prediction_end(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_prediction_lock(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_prediction_progress(broadcaster: Union[PartialUser, str, int])#
coroutine subscribe_channel_raid(from_broadcaster: Optional[Union[PartialUser, str, int]] = None, to_broadcaster: Optional[Union[PartialUser, str, int]] = None)#
subscribe_channel_shield_mode_begin(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int])#
subscribe_channel_shield_mode_end(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int])#
subscribe_channel_shoutout_create(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int])#
subscribe_channel_shoutout_receive(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int])#
subscribe_channel_stream_end(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_stream_start(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_subscription_end(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_subscription_gifts(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_subscription_messages(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_subscriptions(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_unbans(broadcaster: Union[PartialUser, str, int])#
subscribe_channel_update(broadcaster: Union[PartialUser, str, int])#
coroutine subscribe_user_authorization_granted()#
coroutine subscribe_user_authorization_revoked()#
coroutine subscribe_user_updated(user: Union[PartialUser, str, int])#
Methods
class twitchio.ext.eventsub.EventSubWSClient(client: Client)#
coroutine subscribe_channel_bans(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_charity_donate(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_cheers(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_follows(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_follows_v2(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_goal_begin(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_goal_end(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_goal_progress(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_hypetrain_begin(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_hypetrain_end(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_hypetrain_progress(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_moderators_add(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_moderators_remove(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_points_redeem_updated(broadcaster: Union[PartialUser, str, int], token: str, reward_id: Optional[str] = None)#
coroutine subscribe_channel_points_redeemed(broadcaster: Union[PartialUser, str, int], token: str, reward_id: Optional[str] = None)#
coroutine subscribe_channel_points_reward_added(broadcaster: Union[PartialUser, str, int], reward_id: str, token: str)#
coroutine subscribe_channel_points_reward_removed(broadcaster: Union[PartialUser, str, int], reward_id: str, token: str)#
coroutine subscribe_channel_points_reward_updated(broadcaster: Union[PartialUser, str, int], reward_id: str, token: str)#
coroutine subscribe_channel_poll_begin(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_poll_end(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_poll_progress(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_prediction_begin(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_prediction_end(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_prediction_lock(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_prediction_progress(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_raid(token: str, from_broadcaster: Optional[Union[PartialUser, str, int]] = None, to_broadcaster: Optional[Union[PartialUser, str, int]] = None)#
coroutine subscribe_channel_shield_mode_begin(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_shield_mode_end(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_shoutout_create(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_shoutout_receive(broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_stream_end(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_stream_start(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_subscription_end(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_subscription_gifts(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_subscription_messages(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_subscriptions(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_unbans(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_channel_update(broadcaster: Union[PartialUser, str, int], token: str)#
coroutine subscribe_user_updated(user: Union[PartialUser, str, int], token: str)#
class twitchio.ext.eventsub.Subscription(data: dict)#
Attributes
class twitchio.ext.eventsub.Headers(request: Request)#

The headers of the inbound EventSub message

message_id#

The unique ID of the message

Type

str

message_retry#

Unknown

Type

int

signature#

The signature associated with the message

Type

str

subscription_type#

The type of the subscription on the inbound message

Type

str

subscription_version#

The version of the subscription.

Type

str

timestamp#

The timestamp the message was sent at

Type

datetime.datetime

Attributes
class twitchio.ext.eventsub.WebsocketHeaders(frame: dict)#

The headers of the inbound Websocket EventSub message

message_id#

The unique ID of the message

Type

str

message_type#

The type of the message coming through

Type

str

message_retry#

Kept for compatibility with Headers

Type

int

signature#

Kept for compatibility with Headers

Type

str

subscription_type#

The type of the subscription on the inbound message

Type

str

subscription_version#

The version of the subscription.

Type

str

timestamp#

The timestamp the message was sent at

Type

datetime.datetime

class twitchio.ext.eventsub.ChannelBanData(client: EventSubClient, data: dict)#

A Ban event

user#

The user that was banned

Type

twitchio.PartialUser

broadcaster#

The broadcaster who’s channel the ban occurred in

Type

twitchio.PartialUser

moderator#

The moderator responsible for the ban

Type

twitchio.PartialUser

reason#

The reason for the ban

Type

str

ends_at#

When the ban ends at. Could be None

Type

Optional[datetime.datetime]

permanant#

A typo of permanent Kept for backwards compatibility

Type

bool

permanent#

Whether the ban is permanent

Type

bool

class twitchio.ext.eventsub.ChannelShieldModeBeginData(client: EventSubClient, data: dict)#

Represents a Shield Mode activation status.

broadcaster#

The broadcaster whose Shield Mode status was updated.

Type

PartialUser

moderator#

The moderator that updated the Shield Mode staus.

Type

PartialUser

started_at#

The UTC datetime of when Shield Mode was last activated.

Type

datetime.datetime

class twitchio.ext.eventsub.ChannelShieldModeEndData(client: EventSubClient, data: dict)#

Represents a Shield Mode activation status.

broadcaster#

The broadcaster whose Shield Mode status was updated.

Type

PartialUser

moderator#

The moderator that updated the Shield Mode staus.

Type

PartialUser

ended_at#

The UTC datetime of when Shield Mode was last deactivated.

Type

datetime.datetime

class twitchio.ext.eventsub.ChannelShoutoutCreateData(client: EventSubClient, data: dict)#

Represents a Shoutout event being sent.

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

broadcaster#

The broadcaster from who sent the shoutout event.

Type

PartialUser

moderator#

The moderator who sent the shoutout event.

Type

PartialUser

to_broadcaster#

The broadcaster who the shoutout was sent to.

Type

PartialUser

started_at#

The datetime the shoutout was sent.

Type

datetime.datetime

viewer_count#

The viewer count at the time of the shoutout

Type

int

cooldown_ends_at#

The datetime the broadcaster can send another shoutout.

Type

datetime.datetime

target_cooldown_ends_at#

The datetime the broadcaster can send another shoutout to the same broadcaster.

Type

datetime.datetime

class twitchio.ext.eventsub.ChannelShoutoutReceiveData(client: EventSubClient, data: dict)#

Represents a Shoutout event being received.

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

broadcaster#

The broadcaster receiving shoutout event.

Type

PartialUser

from_broadcaster#

The broadcaster who sent the shoutout.

Type

PartialUser

started_at#

The datetime the shoutout was sent.

Type

datetime.datetime

viewer_count#

The viewer count at the time of the shoutout

Type

int

class twitchio.ext.eventsub.ChannelSubscribeData(client: EventSubClient, data: dict)#

A Subscription event

user#

The user who subscribed

Type

twitchio.PartialUser

broadcaster#

The channel that was subscribed to

Type

twitchio.PartialUser

tier#

The tier of the subscription

Type

int

is_gift#

Whether the subscription was a gift or not

Type

bool

class twitchio.ext.eventsub.ChannelSubscriptionGiftData(client: EventSubClient, data: dict)#

A Subscription Gift event Explicitly, the act of giving another user a Subscription. Receiving a gift-subscription uses ChannelSubscribeData above, with is_gift is True

is_anonymous#

Whether the gift sub was anonymous

Type

bool

user#

The user that gifted subs. Will be None if is_anonymous is True

Type

Optional[twitchio.PartialUser]

broadcaster#

The channel that was subscribed to

Type

twitchio.PartialUser

tier#

The tier of the subscription

Type

int

total#

The total number of subs gifted by a user at once

Type

int

cumulative_total#

The total number of subs gifted by a user overall. Will be None if is_anonymous is True

Type

Optional[int]

class twitchio.ext.eventsub.ChannelSubscriptionMessageData(client: EventSubClient, data: dict)#

A Subscription Message event. A combination of resubscriptions + the messages users type as part of the resub.

user#

The user who subscribed

Type

twitchio.PartialUser

broadcaster#

The channel that was subscribed to

Type

twitchio.PartialUser

tier#

The tier of the subscription

Type

int

message#

The user’s resubscription message

Type

str

emote_data#

emote data within the user’s resubscription message. Not the emotes themselves

Type

list

cumulative_months#

The total number of months a user has subscribed to the channel

Type

int

streak#

The total number of months subscribed in a row. None if the user declines to share it.

Type

Optional[int]

duration#

The length of the subscription. Typically 1, but some users may buy subscriptions for several months.

Type

int

class twitchio.ext.eventsub.ChannelCheerData(client: EventSubClient, data: dict)#

A Cheer event

is_anonymous#

Whether the cheer was anonymous

Type

bool

user#

The user that cheered. Will be None if is_anonymous is True

Type

Optional[twitchio.PartialUser]

broadcaster#

The channel the cheer happened on

Type

twitchio.PartialUser

message#

The message sent along with the bits

Type

str

bits#

The amount of bits sent

Type

int

class twitchio.ext.eventsub.ChannelUpdateData(client: EventSubClient, data: dict)#

A Channel Update event

broadcaster#

The channel that was updated

Type

twitchio.PartialUser

title#

The title of the stream

Type

str

language#

The language of the channel

Type

str

category_id#

The category the stream is in

Type

str

category_name#

The category the stream is in

Type

str

is_mature#

Whether the channel is marked as mature by the broadcaster

Type

bool

class twitchio.ext.eventsub.ChannelFollowData(client: EventSubClient, data: dict)#

A Follow event

user#

The user that followed

Type

twitchio.PartialUser

broadcaster#

The channel that was followed

Type

twitchio.PartialUser

followed_at#

When the follow occurred

Type

datetime.datetime

class twitchio.ext.eventsub.ChannelRaidData(client: EventSubClient, data: dict)#

A Raid event

raider#

The person initiating the raid

Type

twitchio.PartialUser

reciever#

The person recieving the raid

Type

twitchio.PartialUser

viewer_count#

The amount of people raiding

Type

int

class twitchio.ext.eventsub.ChannelModeratorAddRemoveData(client: EventSubClient, data: dict)#

A Moderator Add/Remove event

user#

The user being added or removed from the moderator status

Type

twitchio.PartialUser

broadcaster#

The channel that is having a moderator added/removed

Type

twitchio.PartialUser

class twitchio.ext.eventsub.ChannelGoalBeginProgressData(client: EventSubClient, data: dict)#

A goal begin event

user#

The broadcaster that started the goal

Type

twitchio.PartialUser

id#

The ID of the goal event

Type

str

type#

The goal type

Type

str

description#

The goal description

Type

str

current_amount#

The goal current amount

Type

int

target_amount#

The goal target amount

Type

int

started_at#

The datetime the goal was started

Type

datetime.datetime

class twitchio.ext.eventsub.ChannelGoalEndData(client: EventSubClient, data: dict)#

A goal end event

user#

The broadcaster that ended the goal

Type

twitchio.PartialUser

id#

The ID of the goal event

Type

str

type#

The goal type

Type

str

description#

The goal description

Type

str

is_achieved#

Whether the goal is achieved

Type

bool

current_amount#

The goal current amount

Type

int

target_amount#

The goal target amount

Type

int

started_at#

The datetime the goal was started

Type

datetime.datetime

ended_at#

The datetime the goal was ended

Type

datetime.datetime

class twitchio.ext.eventsub.CustomReward(data, broadcaster)#

A Custom Reward

broadcaster#

The channel that has this reward

Type

twitchio.PartialUser

id#

The ID of the reward

Type

str

title#

The title of the reward

Type

str

cost#

The cost of the reward in Channel Points

Type

int

prompt#

The prompt of the reward

Type

str

enabled#

Whether or not the reward is enabled. Will be None for Redemption events.

Type

Optional[bool]

paused#

Whether or not the reward is paused. Will be None for Redemption events.

Type

Optional[bool]

in_stock#

Whether or not the reward is in stock. Will be None for Redemption events.

Type

Optional[bool]

cooldown_until#

How long until the reward is off cooldown and can be redeemed again. Will be None for Redemption events.

Type

Optional[datetime.datetime]

input_required#

Whether or not the reward requires an input. Will be None for Redemption events.

Type

Optional[bool]

redemptions_skip_queue#

Whether or not redemptions for this reward skips the queue. Will be None for Redemption events.

Type

Optional[bool]

redemptions_current_stream#

How many redemptions of this reward have been redeemed for this stream. Will be None for Redemption events.

Type

Optional[int]

max_per_stream#

Whether or not a per-stream redemption limit is in place, and if so, the maximum number of redemptions allowed per stream. Will be None for Redemption events.

Type

Tuple[bool, int]

max_per_user_per_stream#

Whether or not a per-user-per-stream redemption limit is in place, and if so, the maximum number of redemptions allowed per user per stream. Will be None for Redemption events.

Type

Tuple[bool, int]

cooldown#

Whether or not a global cooldown is in place, and if so, the number of seconds until the reward can be redeemed again. Will be None for Redemption events.

Type

Tuple[bool, int]

background_color#

Hexadecimal color code for the background of the reward.

Type

Optional[str]

image#

Image URL for the reward.

Type

Optional[str]

class twitchio.ext.eventsub.CustomRewardAddUpdateRemoveData(client: EventSubClient, data: dict)#

A Custom Reward Add/Update/Remove event

id#

The ID of the custom reward

Type

str

broadcaster#

The channel the custom reward was modified in

Type

twitchio.PartialUser

reward#

The reward object

Type

CustomReward

class twitchio.ext.eventsub.CustomRewardRedemptionAddUpdateData(client: EventSubClient, data: dict)#

A Custom Reward Redemption event

broadcaster#

The channel the redemption occurred in

Type

twitchio.PartialUser

user#

The user that redeemed the reward

Type

twitchio.PartialUser

id#

The ID of the redemption

Type

str

input#

The user input, if present. This will be an empty string if it is not present

Type

str

status#

One of “unknown”, “unfulfilled”, “fulfilled”, or “cancelled”

Type

str

redeemed_at#

When the reward was redeemed at

Type

datetime.datetime

reward#

The reward object

Type

CustomReward

class twitchio.ext.eventsub.HypeTrainContributor(client: EventSubClient, data: dict)#

A Contributor to a Hype Train

user#

The user

Type

twitchio.PartialUser

type#

One of “bits, “subscription” or “other”. The way they contributed to the hype train

Type

str

total#

How many points they’ve contributed to the Hype Train

Type

int

class twitchio.ext.eventsub.HypeTrainBeginProgressData(client: EventSubClient, data: dict)#

A Hype Train Begin/Progress event

broadcaster#

The channel the Hype Train occurred in

Type

twitchio.PartialUser

total_points#

The total amounts of points in the Hype Train

Type

int

progress#

The progress of the Hype Train towards the next level

Type

int

goal#

The goal to reach the next level

Type

int

started#

When the Hype Train started

Type

datetime.datetime

expires#

When the Hype Train ends

Type

datetime.datetime

top_contributions#

The top contributions of the Hype Train

Type

List[HypeTrainContributor]

last_contribution#

The last contributor to the Hype Train

Type

HypeTrainContributor

level#

The current level of the Hype Train

Type

int

class twitchio.ext.eventsub.HypeTrainEndData(client: EventSubClient, data: dict)#

A Hype Train End event

broadcaster#

The channel the Hype Train occurred in

Type

twitchio.PartialUser

total_points#

The total amounts of points in the Hype Train

Type

int

level#

The level the hype train reached

Type

int

started#

When the Hype Train started

Type

datetime.datetime

top_contributions#

The top contributions of the Hype Train

Type

List[HypeTrainContributor]

cooldown_ends_at#

When another Hype Train can begin

Type

datetime.datetime

class twitchio.ext.eventsub.PollChoice(data)#

A Poll Choice

choice_id#

The ID of the choice

Type

str

title#

The title of the choice

Type

str

bits_votes#

How many votes were cast using Bits

Warning

Twitch have removed support for voting with bits. This will return as 0

Type

int

channel_points_votes#

How many votes were cast using Channel Points

Type

int

votes#

The total number of votes, including votes cast using Bits and Channel Points

Type

int

class twitchio.ext.eventsub.BitsVoting(data)#

Information on voting on a poll with Bits

is_enabled#

Whether users can use Bits to vote on the poll

Type

bool

amount_per_vote#

How many Bits are required to cast an extra vote

Warning

Twitch have removed support for voting with bits. This will return as False and 0 respectively

Type

int

class twitchio.ext.eventsub.ChannelPointsVoting(data)#

Information on voting on a poll with Channel Points

is_enabled#

Whether users can use Channel Points to vote on the poll

Type

bool

amount_per_vote#

How many Channel Points are required to cast an extra vote

Type

int

class twitchio.ext.eventsub.PollStatus(value)#

The status of a poll.

ACTIVE: Poll is currently in progress. COMPLETED: Poll has reached its ended_at time. TERMINATED: Poll has been manually terminated before its ended_at time. ARCHIVED: Poll is no longer visible on the channel. MODERATED: Poll is no longer visible to any user on Twitch. INVALID: Something went wrong determining the state.

class twitchio.ext.eventsub.PollBeginProgressData(client: EventSubClient, data: dict)#

A Poll Begin/Progress event

broadcaster#

The channel the poll occured in

Type

twitchio.PartialUser

poll_id#

The ID of the poll

Type

str

title#

The title of the poll

Type

str

choices#

The choices in the poll

Type

List[PollChoice]

bits_voting#

Information on voting on the poll with Bits

Warning

Twitch have removed support for voting with bits.

Type

BitsVoting

channel_points_voting#

Information on voting on the poll with Channel Points

Type

ChannelPointsVoting

started_at#

When the poll started

Type

datetime.datetime

ends_at#

When the poll is set to end

Type

datetime.datetime

...
class twitchio.ext.eventsub.PollEndData(client: EventSubClient, data: dict)#

A Poll End event

broadcaster#

The channel the poll occured in

Type

twitchio.PartialUser

poll_id#

The ID of the poll

Type

str

title#

The title of the poll

Type

str

choices#

The choices in the poll

Type

List[PollChoice]

bits_voting#

Information on voting on the poll with Bits

Warning

Twitch have removed support for voting with bits.

Type

BitsVoting

channel_points_voting#

Information on voting on the poll with Channel Points

Type

ChannelPointsVoting

status#

How the poll ended

Type

PollStatus

started_at#

When the poll started

Type

datetime.datetime

ended_at#

When the poll is set to end

Type

datetime.datetime

class twitchio.ext.eventsub.Predictor(client: EventSubClient, data: dict)#

A Predictor

user#

The user who predicted an outcome

Type

twitchio.PartialUser

channel_points_used#

How many Channel Points the user used to predict this outcome

Type

int

channel_points_won#

How many Channel Points was distributed to the user. Will be None if the Prediction is unresolved, cancelled (refunded), or the user predicted the losing outcome.

Type

int

class twitchio.ext.eventsub.PredictionOutcome(client: EventSubClient, data: dict)#

A Prediction Outcome

outcome_id#

The ID of the outcome

Type

str

title#

The title of the outcome

Type

str

channel_points#

The amount of Channel Points that have been bet for this outcome

Type

int

color#

The color of the outcome. Can be blue or pink

Type

str

users#

The number of users who predicted the outcome

Type

int

top_predictors#

The top predictors of the outcome

Type

List[Predictor]

property colour: str#

The colour of the prediction. Alias to color.

class twitchio.ext.eventsub.PredictionStatus(value)#

The status of a Prediction.

ACTIVE: Prediction is active and viewers can make predictions. LOCKED: Prediction has been locked and viewers can no longer make predictions. RESOLVED: A winning outcome has been chosen and the Channel Points have been distributed to the users who guessed the correct outcome. CANCELED: Prediction has been canceled and the Channel Points have been refunded to participants.

class twitchio.ext.eventsub.PredictionBeginProgressData(client: EventSubClient, data: dict)#

A Prediction Begin/Progress event

broadcaster#

The channel the prediction occured in

Type

twitchio.PartialUser

prediction_id#

The ID of the prediction

Type

str

title#

The title of the prediction

Type

str

outcomes#

The outcomes for the prediction

Type

List[PredictionOutcome]

started_at#

When the prediction started

Type

datetime.datetime

locks_at#

When the prediction is set to be locked

Type

datetime.datetime

class twitchio.ext.eventsub.PredictionLockData(client: EventSubClient, data: dict)#

A Prediction Begin/Progress event

broadcaster#

The channel the prediction occured in

Type

twitchio.PartialUser

prediction_id#

The ID of the prediction

Type

str

title#

The title of the prediction

Type

str

outcomes#

The outcomes for the prediction

Type

List[PredictionOutcome]

started_at#

When the prediction started

Type

datetime.datetime

locked_at#

When the prediction was locked

Type

datetime.datetime

class twitchio.ext.eventsub.PredictionEndData(client: EventSubClient, data: dict)#

A Prediction Begin/Progress event

broadcaster#

The channel the prediction occured in

Type

twitchio.PartialUser

prediction_id#

The ID of the prediction

Type

str

title#

The title of the prediction

Type

str

winning_outcome_id#

The ID of the outcome that won

Type

str

outcomes#

The outcomes for the prediction

Type

List[PredictionOutcome]

status#

How the prediction ended

Type

PredictionStatus

started_at#

When the prediction started

Type

datetime.datetime

ended_at#

When the prediction ended

Type

datetime.datetime

class twitchio.ext.eventsub.StreamOnlineData(client: EventSubClient, data: dict)#

A Stream Start event

broadcaster#

The channel that went live

Type

twitchio.PartialUser

id#

Some sort of ID for the stream

Type

str

type#

One of “live”, “playlist”, “watch_party”, “premier”, or “rerun”. The type of live event.

Type

str

started_at#
Type

datetime.datetime

class twitchio.ext.eventsub.StreamOfflineData(client: EventSubClient, data: dict)#

A Stream End event

broadcaster#

The channel that stopped streaming

Type

twitchio.PartialUser

class twitchio.ext.eventsub.UserAuthorizationRevokedData(client: EventSubClient, data: dict)#

An Authorization Revokation event

user#

The user that has revoked authorization for your app

Type

twitchio.PartialUser

client_id#

The client id of the app that had its authorization revoked

Type

str

class twitchio.ext.eventsub.UserUpdateData(client: EventSubClient, data: dict)#

A User Update event

user#

The user that was updated

Type

twitchio.PartialUser

email#

The users email, if you have permission to read this information

Type

Optional[str]

description#

The channels description (displayed as bio)

Type

str

class twitchio.ext.eventsub.ChannelCharityDonationData(client: EventSubClient, data: dict)#

Represents a donation towards a charity campaign.

Requires the channel:read:charity scope.

id#

The ID of the event.

Type

str

campaign_id#

The ID of the running charity campaign.

Type

str

broadcaster#

The broadcaster running the campaign.

Type

PartialUser

user#

The user who donated.

Type

PartialUser

charity_name#

The name of the charity.

Type

str

charity_description#

The description of the charity.

Type

str

The logo of the charity.

Type

str

charity_website#

The websiet of the charity.

Type

str

donation_value#

The amount of money being donated.

Type

int

donation_decimal_places#

The decimal places to put into the :attr`~.donation_amount`.

Type

int

donation_currency#

The currency that was donated (ex. USD, GBP, EUR)

Type

str