API reference#

Client Reference#

Methods
class twitchio.eventsub.Client(transport: BaseTransport, token_handler: TokenHandlerT, proxy: str | None = None, proxy_auth: aiohttp.BasicAuth | None = None, trace: aiohttp.TraceConfig | None = None)#

The base EventSub client, which handles incoming eventsub data and dispatches it through its own event system. This client is completely standalone from the core TwitchIO Client, and can operate without any attached Client. When operating in standalone mode, a Token Handler is still required to manage token access for HTTP calls. To operate Eventsub with a core twitchio.Client attached, create this class using from_client().

Parameters

  • transport (WebsocketTransport | WebhookTransport) – The transport to use to receive notifications. For more information on each transport, read the corresponding documentation.

  • token_handler (twitchio.tokens.TokenHandler) – The token handler to use for requesting tokens during HTTP requests. When using the WebsocketTransport, this must have user tokens available for the targets of the subscriptions. When using the WebhookTransport, this must have a client token available, as that is what Twitch requires for webhooks.

  • proxy (str | None) – The optional proxy to use when making requests. This is passed directly to aiohttp.

  • proxy_auth (aiohttp.BasicAuth | None) – The auth to give to the proxy. This is passed directly to aiohttp.

  • trace (aiohttp.TraceConfig | None) – Trace information to configure aiohttp. This is passed directly to aiohttp.

classmethod from_client(transport: BaseTransport, client: _BaseClient) → Self#

Creates a Client that can interface with the Eventsub API system. When created using this method, the client will interact with the core Client, using its token handler, and additionally dispatching events through its event system (in addition to the standalone events).

Parameters

  • transport (WebsocketTransport | WebhookTransport) – The transport to use to receive notifications. For more information on each transport, read the corresponding documentation.

  • client (twitchio.Client | Twitchio.ext.commands.Bot) – The core client to attach this client to.

coroutine start() → None#

Starts the Eventsub Client, which will initialize the underlying transport and subscribe/listen to events.

coroutine stop() → None#

Stops the Eventsub Client, which tells the underlying transport to stop listening for events, and clean up after itself.

Note

The client cannot be restarted once it has been stopped.

subscribe_channel_bans(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_cheers(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_follows(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_goal_begin(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_goal_end(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_goal_progress(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_hypetrain_begin(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_hypetrain_end(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_hypetrain_progress(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_moderators_add(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_moderators_remove(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_poll_begin(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_poll_end(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_poll_progress(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_prediction_begin(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_prediction_end(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_prediction_lock(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_prediction_progress(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_reward_add(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_reward_redeem(broadcaster: BaseUser, moderator: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

  • broadcaster (PartialUser) – The channel to for this subscription to target.

  • moderator (PartialUser) – The moderator that is authorizing the action. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_reward_redeem_update(broadcaster: BaseUser, moderator: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

  • broadcaster (PartialUser) – The channel to for this subscription to target.

  • moderator (PartialUser) – The moderator that is authorizing the action. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_reward_remove(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_reward_update(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_shoutout_create(broadcaster: BaseUser, moderator: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

  • broadcaster (PartialUser) – The channel to for this subscription to target.

  • moderator (PartialUser) – The moderator that is authorizing the action. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_shoutout_receive(broadcaster: BaseUser, moderator: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

  • broadcaster (PartialUser) – The channel to for this subscription to target.

  • moderator (PartialUser) – The moderator that is authorizing the action. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_stream_end(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_stream_start(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_subscription_end(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_subscription_gifts(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_subscription_messages(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_subscriptions(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_unbans(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

subscribe_channel_update(broadcaster: BaseUser) → Awaitable[HTTPSubscribeResponse]#
Parameters

broadcaster (PartialUser) – The channel to for this subscription to target. This user must have authenticated your app.

Returns

  • dict The response from Twitch with the following keys

  • - data (list [Subscription dict] - The subscription that was created.)

  • - total (int - The total subscriptions created.)

  • - total_cost (int - The sum of the cost of existing subscriptions.)

  • - max_total_cost (int - The maximum allowed cost.)

Event Reference#

Attributes
class twitchio.eventsub.Subscription(payload: _SubscriptionPayload, transport: BaseTransport)#

Subscription info given when twitch fires an event. For info on the message itself, check meta

id#

The ID of the subscription.

Type

str

status#

The status of the subscription.

Type

str

type#

The subscription type. # TODO doc this better

Type

str

version#

The subscription version. This is relatively useless.

Type

int

cost#

The cost of the the subscription towards your total subscription points. If the user has authorized your application this is 0.

Type

int

condition#

The condition for this subscription to trigger an event. # TODO determine dicts on this.

Type

dict[str, Any]

created_at#

When the subscption was created.

Type

datetime

transport#

The transport that dispatched this event.

New in version 3.0.

Type

BaseTransport

session_id#

The id of the websocket this subscription is attached to. This is None when using the Webhook transport.

New in version 3.0.

Type

str | None

class twitchio.eventsub.WebsocketMeta(data: _WebsocketMessageMetadata)#
class twitchio.eventsub.WebhookMeta(hdrs: Mapping[str, str])#
Attributes
class twitchio.eventsub.RevocationEvent(transport: BaseTransport)#

Event created when someone revokes access for your app. This event has no special attributes, you can determine information about the revoked event via subscription. You can listen to this event via the event_eventsub_revocation event or via subclassing the EventSub client.

subscription#

The subscription that triggered this event.

Type

Subscription

meta#

The metadata associated with this event. There are slight differences between the webhook metadata and websocket metadata. This was previously known as headers.

Changed in version 3.0.

Type

WebhookMeta | WebsocketMeta

transport#

The transport that received this event.

New in version 3.0.

Type

BaseTransport

Attributes
class twitchio.eventsub.ChallengeEvent(transport: BaseTransport)#

This event is created to challenge your webhook authenticity (meaning it is only used when using the WebhookTransport transport). These challenges are handled by TwitchIO, so you shouldn’t need to deal with these. You can listen to this event via the event_eventsub_challenge event or via subclassing the EventSub client.

challenge#

The challenge string given by twitch.

Type

str

subscription#

The subscription that triggered this event.

Type

Subscription

meta#

The metadata associated with this event. There are slight differences between the webhook metadata and websocket metadata. This was previously known as headers.

Changed in version 3.0.

Type

WebhookMeta | WebsocketMeta

transport#

The transport that received this event.

New in version 3.0.

Type

BaseTransport

Attributes
class twitchio.eventsub.NotificationEvent(transport: BaseTransport)#

This event is created when a notification is received from twitch.

data#

The data for this event. This will change depending on the event in question

Type

A Model

subscription#

The subscription that triggered this event.

Type

Subscription

meta#

The metadata associated with this event. There are slight differences between the webhook metadata and websocket metadata. This was previously known as headers.

Changed in version 3.0.

Type

WebhookMeta | WebsocketMeta

transport#

The transport that received this event.

New in version 3.0.

Type

BaseTransport

Attributes
class twitchio.eventsub.ReconnectEvent(transport: BaseTransport)#

This event is created when the twitch websocket wants the client to reconnect. Reconnecting is automatically handled, this event is simply to inform you of it happening.

reconnect_url#

The URL provided by twitch to reconnect to. This will keep the existing subscriptions intact for us.

Type

class:str

subscription#

The subscription that triggered this event.

Type

Subscription

meta#

The metadata associated with this event. There are slight differences between the webhook metadata and websocket metadata. This was previously known as headers.

Changed in version 3.0.

Type

WebhookMeta | WebsocketMeta

transport#

The transport that received this event.

New in version 3.0.

Type

BaseTransport

Attributes
class twitchio.eventsub.KeepaliveEvent(transport: BaseTransport)#

This event is created to fill space and let you know twitch is still sending you events after a spout of silence. Nothing needs to be done.

subscription#

The subscription that triggered this event.

Type

Subscription

meta#

The metadata associated with this event. There are slight differences between the webhook metadata and websocket metadata. This was previously known as headers.

Changed in version 3.0.

Type

WebhookMeta | WebsocketMeta

transport#

The transport that received this event.

New in version 3.0.

Type

BaseTransport

Event Data Reference#

Attributes
class twitchio.eventsub.ChannelBan(transport: BaseTransport, payload: ChannelBanPayload)#

A channel ban or timeout. Indicates someone was banned from the channel’s chat.

user#

The user who was banned.

Type

PartialUser

broadcaster#

The channel from which the user was banned.

Type

PartialUser

moderator#

The moderator who banned the user.

Type

PartialUser

reason#

The reason the moderator banned the user.

Type

str

banned_at#

When the ban occurred.

Type

datetime.datetime

ends_at#

When the timeout ends. None if it is a ban (permanent).

Type

datetime.datetime | None

is_permanent#

Whether the ban is permanent or a timeout.

Type

bool

Attributes
class twitchio.eventsub.ChannelCheer(transport: BaseTransport, payload: ChannelCheerPayload)#

A cheer on a channel. Someone sent an amount of bits.

user#

The user who gave the gifts. Could be None if the gifter was anonymous.

Type

PartialUser | None

broadcaster#

The channel that the user subscribed to.f

Type

PartialUser

message#

The message sent to chat.

Type

str

bits#

The amount of bits sent.

Type

int

is_anonymous#

Whether the bits were anonymous or not.

Type

bool

Attributes
class twitchio.eventsub.ChannelCustomReward(transport: BaseTransport, payload: ChannelCustomRewardModifyPayload)#

A Custom Reward event

id#

The ID of the reward.

Type

str

broadcaster#

The channel on which the reward was modified.

Type

PartialUser

enabled#

Whether the reward is enabled.

Type

bool

paused#

Whether the reward redemptions are paused.

Type

bool

in_stock#

Whether the reward is in stock.

Type

bool

title#

The title of the reward

Type

str

cost#

How many channel points are required to redeem this custom reward.

Type

int

prompt#

The prompt given to users when redeeming this reward.

Type

str

user_input_required#

Whether the user will input a message when redeeming this reward.

Type

bool

redemptions_skip_request_queue#

Whether redemptions will bypass the redemption request queue.

Type

bool

cooldown_expires_at#

When the cooldown will expire, if on cooldown.

Type

datetime.datetime | None

amount_redeemed_current_stream#

How many of this reward have been redeemed during the current stream. None when not live.

Type

int | None

background_color#

The background colour of the reward to viewers.

Type

str

max_per_stream#

The max amount of this reward that can be redeemed in a stream.

Type

ChannelCustomReward_streamlimits

global_cooldown#

The global cooldown configuration for this reward.

Type

ChannelCustomReward_global_cooldown

image#

The image for this reward.

Type

ImageLinks

default_image#

The default image for this reward.

Type

ImageLinks

Attributes
class twitchio.eventsub.ChannelCustomRewardAdd(transport: BaseTransport, payload: ChannelCustomRewardModifyPayload)#

A Custom Reward event

id#

The ID of the reward.

Type

str

broadcaster#

The channel on which the reward was modified.

Type

PartialUser

enabled#

Whether the reward is enabled.

Type

bool

paused#

Whether the reward redemptions are paused.

Type

bool

in_stock#

Whether the reward is in stock.

Type

bool

title#

The title of the reward

Type

str

cost#

How many channel points are required to redeem this custom reward.

Type

int

prompt#

The prompt given to users when redeeming this reward.

Type

str

user_input_required#

Whether the user will input a message when redeeming this reward.

Type

bool

redemptions_skip_request_queue#

Whether redemptions will bypass the redemption request queue.

Type

bool

cooldown_expires_at#

When the cooldown will expire, if on cooldown.

Type

datetime.datetime | None

amount_redeemed_current_stream#

How many of this reward have been redeemed during the current stream. None when not live.

Type

int | None

background_color#

The background colour of the reward to viewers.

Type

str

max_per_stream#

The max amount of this reward that can be redeemed in a stream.

Type

ChannelCustomReward_streamlimits

global_cooldown#

The global cooldown configuration for this reward.

Type

ChannelCustomReward_global_cooldown

image#

The image for this reward.

Type

ImageLinks

default_image#

The default image for this reward.

Type

ImageLinks

Attributes
class twitchio.eventsub.ChannelCustomRewardRemove(transport: BaseTransport, payload: ChannelCustomRewardModifyPayload)#

A Custom Reward event

id#

The ID of the reward.

Type

str

broadcaster#

The channel on which the reward was modified.

Type

PartialUser

enabled#

Whether the reward is enabled.

Type

bool

paused#

Whether the reward redemptions are paused.

Type

bool

in_stock#

Whether the reward is in stock.

Type

bool

title#

The title of the reward

Type

str

cost#

How many channel points are required to redeem this custom reward.

Type

int

prompt#

The prompt given to users when redeeming this reward.

Type

str

user_input_required#

Whether the user will input a message when redeeming this reward.

Type

bool

redemptions_skip_request_queue#

Whether redemptions will bypass the redemption request queue.

Type

bool

cooldown_expires_at#

When the cooldown will expire, if on cooldown.

Type

datetime.datetime | None

amount_redeemed_current_stream#

How many of this reward have been redeemed during the current stream. None when not live.

Type

int | None

background_color#

The background colour of the reward to viewers.

Type

str

max_per_stream#

The max amount of this reward that can be redeemed in a stream.

Type

ChannelCustomReward_streamlimits

global_cooldown#

The global cooldown configuration for this reward.

Type

ChannelCustomReward_global_cooldown

image#

The image for this reward.

Type

ImageLinks

default_image#

The default image for this reward.

Type

ImageLinks

Attributes
class twitchio.eventsub.ChannelCustomRewardUpdate(transport: BaseTransport, payload: ChannelCustomRewardModifyPayload)#

A Custom Reward event

id#

The ID of the reward.

Type

str

broadcaster#

The channel on which the reward was modified.

Type

PartialUser

enabled#

Whether the reward is enabled.

Type

bool

paused#

Whether the reward redemptions are paused.

Type

bool

in_stock#

Whether the reward is in stock.

Type

bool

title#

The title of the reward

Type

str

cost#

How many channel points are required to redeem this custom reward.

Type

int

prompt#

The prompt given to users when redeeming this reward.

Type

str

user_input_required#

Whether the user will input a message when redeeming this reward.

Type

bool

redemptions_skip_request_queue#

Whether redemptions will bypass the redemption request queue.

Type

bool

cooldown_expires_at#

When the cooldown will expire, if on cooldown.

Type

datetime.datetime | None

amount_redeemed_current_stream#

How many of this reward have been redeemed during the current stream. None when not live.

Type

int | None

background_color#

The background colour of the reward to viewers.

Type

str

max_per_stream#

The max amount of this reward that can be redeemed in a stream.

Type

ChannelCustomReward_streamlimits

global_cooldown#

The global cooldown configuration for this reward.

Type

ChannelCustomReward_global_cooldown

image#

The image for this reward.

Type

ImageLinks

default_image#

The default image for this reward.

Type

ImageLinks

Attributes
class twitchio.eventsub.ChannelFollow(transport: BaseTransport, payload: ChannelFollowPayload)#

A channel follow. Indicates someone followed the broadcaster.

user#

The user who followed.

Type

PartialUser

broadcaster#

The user who received the follow.

Type

PartialUser

followed_at#

The time the follow happened.

Type

datetime.datetime

Attributes
class twitchio.eventsub.ChannelGoalBegin(transport: BaseTransport, payload: ChannelGoalBeginProgressPayload)#

A goal begin event

broadcaster#

The broadcaster that started the goal

Type

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

Attributes
class twitchio.eventsub.ChannelGoalEnd(transport: BaseTransport, payload: ChannelGoalEndPayload)#

A goal begin event

broadcaster#

The broadcaster that started the goal

Type

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

Attributes
class twitchio.eventsub.ChannelGoalProgress(transport: BaseTransport, payload: ChannelGoalBeginProgressPayload)#

A goal begin event

broadcaster#

The broadcaster that started the goal

Type

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

Attributes
class twitchio.eventsub.ChannelHypeTrainBegin(transport: BaseTransport, payload: ChannelHypeTrainBeginProgressPayload)#

A Hype Train Begin event

broadcaster#

The channel the Hype Train occurred in.

Type

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

Attributes
class twitchio.eventsub.ChannelHypeTrainEnd(transport: BaseTransport, payload: ChannelHypeTrainEndPayload)#

A Hype Train End event

broadcaster#

The channel the Hype Train occurred in.

Type

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

Attributes
class twitchio.eventsub.ChannelHypeTrainProgress(transport: BaseTransport, payload: ChannelHypeTrainBeginProgressPayload)#

A Hype Train Progress event

broadcaster#

The channel the Hype Train occurred in.

Type

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

Attributes
class twitchio.eventsub.ChannelModeratorAdd(transport: BaseTransport, payload: ChannelModeratorAddPayload)#

Moderator added to channel

user#

The user being added as a moderator.

Type

PartialUser

broadcaster#

The channel that is having a moderator added.

Type

PartialUser

Attributes
class twitchio.eventsub.ChannelModeratorRemove(transport: BaseTransport, payload: ChannelModeratorRemovePayload)#

Moderator removed from channel

user#

The user being removed from moderator status.

Type

PartialUser

broadcaster#

The channel that is having a moderator removed.

Type

PartialUser

Attributes
class twitchio.eventsub.ChannelPollBegin(transport: BaseTransport, payload: ChannelPollBeginPayload)#

A Poll Begin event

broadcaster#

The channel the poll occured in.

Type

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]

cost_per_vote#

How many channel points it takes to cast a vote.

Type

int

started_at#

When the poll started.

Type

datetime.datetime

ends_at#

When the poll is set to end.

Type

datetime.datetime

Attributes
class twitchio.eventsub.ChannelPollEnd(transport: BaseTransport, payload: ChannelPollEndPayload)#

A Poll End event

broadcaster#

The channel the poll occured in.

Type

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]

cost_per_vote#

How many channel points it takes to cast a vote.

Type

int

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

Attributes
class twitchio.eventsub.ChannelPollProgress(transport: BaseTransport, payload: ChannelPollBeginPayload)#

A Poll Progress event. dispatched when a poll received an update to votes

broadcaster#

The channel the poll occured in.

Type

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]

cost_per_vote#

How many channel points it takes to cast a vote.

Type

int

started_at#

When the poll started.

Type

datetime.datetime

ends_at#

When the poll is set to end.

Type

datetime.datetime

Attributes
class twitchio.eventsub.ChannelPredictionBegin(transport: BaseTransport, payload: ChannelPredictionBeginPayload)#

A Prediction Begin event

broadcaster#

The channel the prediction occured in.

Type

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

Attributes
class twitchio.eventsub.ChannelPredictionEnd(transport: BaseTransport, payload: ChannelPredictionEndPayload)#

A Prediction Begin/Progress event

broadcaster#

The channel the prediction occured in

Type

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

Attributes
class twitchio.eventsub.ChannelPredictionLock(transport: BaseTransport, payload: ChannelPredictionProgressLockPayload)#

A Prediction Lock 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

Attributes
class twitchio.eventsub.ChannelPredictionProgress(transport: BaseTransport, payload: ChannelPredictionBeginPayload)#

A Prediction Progress event

broadcaster#

The channel the prediction occured in.

Type

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

Attributes
class twitchio.eventsub.ChannelRaid(transport: BaseTransport, payload: ChannelRaidPayload)#

A Raid event

raider#

The person initiating the raid.

Type

PartialUser

reciever#

The person recieving the raid.

Type

PartialUser

viewer_count#

The amount of people raiding.

Type

int

Attributes
class twitchio.eventsub.ChannelShoutoutCreate(transport: BaseTransport, payload: ChannelShoutoutCreatePayload)#

A shoutout create event. This is created when a shoutout is created, not received.

broadcaster#

The broadcaster from which the shoutout is coming.

Type

PartialUser

moderator#

The moderator that created the shoutout.

Type

PartialUser

target#

The person receiving the shoutout.

Type

PartialUser

started_at#

When the shoutout started.

Type

datetime.datetime

viewer_count#

How many viewers saw the shoutout.

Type

int

cooldown_ends_at#

When another shoutout can happen.

Type

datetime.datetime

target_cooldown_ends_at#

When the target can have another shoutout towards them.

Type

datetime.datetime

Attributes
class twitchio.eventsub.ChannelShoutoutReceive(transport: BaseTransport, payload: ChannelShoutoutCreatePayload)#

A shoutout receive event. This is created when a shoutout is received, not created.

broadcaster#

The broadcaster receiving the shoutout.

Type

PartialUser

sender#

The person sending the shoutout.

Type

PartialUser

started_at#

When the shoutout started.

Type

datetime.datetime

viewer_count#

How many viewers saw the shoutout.

Type

int

Attributes
class twitchio.eventsub.ChannelSubscribe(transport: BaseTransport, payload: ChannelSubscribePayload)#

A channel subscription. Indicates someone subscribed to the channel. This does not include resubscriptions.

user#

The user who subscribed.

Type

PartialUser

broadcaster#

The channel that the user subscribed to.

Type

PartialUser

tier#

The tier of the subscription.

Type

Literal[1000, 2000, 3000]

is_gift#

Whether someone gifted the sub to the subscriber.

Type

bool

Attributes
class twitchio.eventsub.ChannelSubscribeEnd(transport: BaseTransport, payload: ChannelSubscribeEndPayload)#

The end of a channel subscription. Indicates that someone has unsubscribed from the channel.

user#

The user who subscribed.

Type

PartialUser

broadcaster#

The channel that the user subscribed to.

Type

PartialUser

tier#

The tier of the subscription.

Type

Literal[1000, 2000, 3000]

is_gift#

Whether someone gifted the sub to the subscriber.

Type

bool

Attributes
class twitchio.eventsub.ChannelSubscribeGift(transport: BaseTransport, payload: ChannelSubscriptionGiftPayload)#

A gifted subscription to a channel. This could be one or more gifts.

user#

The user who gave the gifts. Could be None if the gift is anonymous.

Type

PartialUser | None

broadcaster#

The channel that the user subscribed to.

Type

PartialUser

total#

How many gifts were given.

Type

int

cumulative_total#

How many gifts the user has given in total. This can be None if the gift is anonymous or the user doesn’t share this.

Type

int | None

tier#

The tier of the subscription.

Type

Literal[1000, 2000, 3000]

is_anonymous#

Whether the gifter is anonymous or not.

Type

bool

Attributes
class twitchio.eventsub.ChannelSubscribeMessage(transport: BaseTransport, payload: ChannelSubscriptionMessagePayload)#

A resubscription message, as seen in chat.

user#

The user who gave the gifts.

Type

PartialUser

broadcaster#

The channel that the user subscribed to.

Type

PartialUser

message#

The message sent to chat.

Type

str

emotes#

Emotes in the message.

Type

list[dict[Literal[“begin”, “end”, “id”], int | str]]

cumulative_months#

How many total months the user has subscribed to the channel.

Type

int

stream_moths#

How many months in a row the user has been subscribed to the channel. None if not shared by the user.

Type

int | None

tier#

The tier of the subscription.

Type

Literal[1000, 2000, 3000]

duration_months#

The month duration of the subscription.

Type

bool

Attributes
class twitchio.eventsub.ChannelUnban(transport: BaseTransport, payload: ChannelUnbanPayload)#

A Channel Unban event

user#

The user that was unbanned.

Type

PartialUser

broadcaster#

The channel the unban occurred in.

Type

PartialUser

moderator#

The moderator that performed the unban.

Type

:class`twitchio.PartialUser`

Attributes
class twitchio.eventsub.ChannelUpdate(transport: BaseTransport, payload: ChannelUpdatePayload)#

A Channel Update. You can listen to this event via the event_eventsub_channel_update event or via subclassing the EventSub client.

broadcaster#

The channel being updated

Type

PartialUser

title#

The updated title of the channel.

Type

str

language#

The language the channel is broadcasting in.

Type

str

category_id#

The ID of the category being streamed.

Type

str

category_name#

The name of the category being streamed (usually a game name).

Type

str

class twitchio.eventsub.EventData(transport: BaseTransport, payload: Any)#
Attributes
class twitchio.eventsub.HypeTrainContributor(transport: BaseTransport, payload: ChannelHypeTrain_ContributorPayload)#

A Contributor to a Hype Train

user#

The user.

Type

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

Attributes

Provides URLS for various image locations.

New in version 3.0.

size_1x#

The 1x size provided by twitch.

Type

str

size_2x#

The 2x size provided by twitch.

Type

str

size_4x#

The 4x size provided by twitch.

Type

str

Attributes
class twitchio.eventsub.PartialReward(payload: ChannelCustomRewardRedemptionModify_RewardPayload)#

A partial reward object, which provides limited information about the reward that was redeemed.

id#

The ID of the reward.

Type

str

title#

The title of the reward.

Type

:class:`str

cost#

The cost in channel points of the reward.

Type

int

prompt#

The prompt the user received when redeeming the reward.

Type

str

Attributes
class twitchio.eventsub.PollChoice(data: ChannelPollBegin_ChoicePayload)#

A Poll Choice

choice_id#

The ID of the choice

Type

str

title#

The title of the choice

Type

str

channel_points_votes#

How many votes were cast using Channel Points

Type

int

votes#

The total number of votes

Type

int

class twitchio.eventsub.PollStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

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.

Attributes
class twitchio.eventsub.PredictionOutcome(transport: BaseTransport, data: ChannelPredictionBegin_outcomesPayload)#

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.eventsub.PredictionStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

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.

Attributes
class twitchio.eventsub.Predictor(transport: BaseTransport, 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

Attributes
class twitchio.eventsub.StreamOffline(transport: BaseTransport, payload: StreamOfflinePayload)#

A Stream Offline event

broadcaster#

The channel that went live.

Type

PartialUser

Attributes
class twitchio.eventsub.StreamOnline(transport: BaseTransport, payload: StreamOnlinePayload)#

A Stream Start event

broadcaster#

The channel that went live.

Type

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#

The time when the stream started.

Type

datetime.datetime

Attributes
class twitchio.eventsub.UserAuthorizationGrant(transport: BaseTransport, payload: UserAuthorizationGrantPayload)#

An Authorization Granted event

This subscription type is only supported by webhooks. Provided client_id must match the client id in the application access token.

user#

The user that has granted authorization for your app.

Type

PartialUser

client_id#

The client id of the app that had its authorization granted.

Type

str

Attributes
class twitchio.eventsub.UserAuthorizationRevoke(transport: BaseTransport, payload: UserAuthorizationRevokePayload)#

An Authorization Revoke event

This subscription type is only supported by webhooks. Provided client_id must match the client id in the application access token.

user#

The user that has revoked authorization for your app.

Type

PartialUser

client_id#

The client id of the app that had its authorization revoked.

Type

str

Attributes
class twitchio.eventsub.UserUpdate(transport: BaseTransport, payload: UserUpdatePayload)#

A User Update event

user#

The user that was updated

Type

PartialUser

email#

The users email, if you have permission to read this information Requires the user:read:email scope

Type

Optional[str]

description#

The channels description (displayed as bio)

Type

str