Minor models reference#
This page contains all the models that are considered less often used in daily usage of the library. This generally includes models that are returned by API requests.
- class twitchio.ActiveExtension(data)#
Represents an active extension for a specified user
- x#
(Video-component Extensions only) X-coordinate of the placement of the extension. Could be None.
- Type
- class twitchio.AutomodCheckMessage(id: str, text: str, user: twitchio.models.PartialUser | int)#
Represents the message to check with automod
- class twitchio.AutomodCheckResponse(data: dict)#
Represents the response to a message check with automod
- class twitchio.BanEvent(http: HTTPHandler, data: dict, broadcaster: PartialUser | User | None)#
Represents a user being banned from a channel.
- timestamp#
The time the action occurred at.
- Type
- broadcaster#
The user whose channel the ban/unban occurred on.
- Type
- user#
The user who was banned/unbanned.
- Type
PartialUser
- moderator#
The user who performed the action.
- Type
- expires_at#
When the ban expires.
- Type
Optional[
datetime.datetime]
- asyncget
- class twitchio.BaseToken(access_token: str)#
A base token container. This base class takes an access token, and does no validation on it before allowing it to be used for requests. This is useful for passing app access tokens.
- x == y
Checks if the token is equal to another.
- x != y
Checks if the token is not equal to another.
- str(x)
Returns the token.
- hash(x)
Returns the hash of the access token
New in version 3.0.
- coroutine get(http: HTTPHandler, handler: BaseTokenHandler, session: aiohttp.ClientSession) str#
This function is a coroutine. Ensures the token is still within the validation period, and then returns the current access token.
- Parameters
http (
HTTPHandler) – The HTTP sessionhandler (
BaseTokenHandler) – The handler passed to your Client/Botsession (
ClientSession) – The session to use for validating the token
- Raises
InvalidToken – This token is invalid
- Returns
The access token
- Return type
- class twitchio.BaseUser(id: int | str)#
A barebones representation of a user. This doesn’t have much use outside of being passed to methods that require a user object that simply contains an ID.
- .. versionadded:: 3.0
- class twitchio.BitLeaderboardUser(http: HTTPHandler, data: dict)#
A representation of a user on the Bit Leaderboard. This contains all the methods of the
PartialUser, but also contains therankandscoreattributes.
- class twitchio.BitsLeaderboard(http: HTTPHandler, data: dict)#
Represents a Bits leaderboard from the twitch API.
- started_at#
The time the leaderboard started.
- Type
- ended_at#
The time the leaderboard ended.
- Type
:class`datetime.datetime`
- leaders#
The current leaders of the Leaderboard.
- Type
list[
BitLeaderboardUser]
- class twitchio.ChannelInfo(http: HTTPHandler, data: dict)#
Represents a channel’s current information
- user#
The user whose channel information was requested.
- Type
- class twitchio.ChannelTeams(http: HTTPHandler, data: dict)#
Represents the Twitch Teams of which the specified channel/broadcaster is a member
- broadcaster#
User of the broadcaster.
- Type
- created_at#
Date and time the Team was created.
- Type
- updated_at#
Date and time the Team was last updated.
- Type
- class twitchio.ChatBadge(data: dict)#
Represents chat badges.
- versions#
The list of chat badges in this set.
- Type
List[
ChatBadgeVersion]
- class twitchio.ChatBadgeVersion(data: dict)#
Represents the different versions of the chat badge.
- class twitchio.ChatSettings(http: HTTPHandler, data: dict)#
Represents current chat settings of a broadcaster / channel
- broadcaster#
User of the broadcaster. Only returns the ID
- Type
- follower_mode_duration#
The length of time, in minutes, that the followers must have followed the broadcaster to participate in chat
- Type
Optional[
int]
- slow_mode_wait_time#
The amount of time, in seconds, that users need to wait between sending messages
- Type
Optional[
int]
- subscriber_mode#
Indicates whether only users that subscribe to the broadcaster’s channel can talk in chat
- Type
- unique_chat_mode#
Indicates whether the broadcaster requires users to post only unique messages in the chat room
- Type
- moderator#
The User of the moderator, if provided. Only returns the ID
- Type
Optional[
PartialUser]
- class twitchio.ChatterColor(http: HTTPHandler, data: dict)#
Represents chatters current name color.
- user#
PartialUser of the chatter.
- Type
- class twitchio.CheerEmote(http: HTTPHandler, data: dict)#
Represents a Cheer Emote
- tiers#
The tiers this Cheer Emote has
- Type
- type#
Shows whether the emote is
global_first_party,global_third_party,channel_custom,display_only, orsponsored.- Type
- last_updated :class:`datetime.datetime`
The date this cheermote was last updated.
- class twitchio.CheerEmoteTier(data: dict)#
Represents a Cheer Emote tier.
- images#
contains two dicts,
lightanddark. Each item will have ananimatedandstaticitem, which will contain yet another dict, with sizes1,1.5,2,3, and4. Ex.cheeremotetier.images["light"]["animated"]["1"]- Type
- show_in_bits_card#
Indicates whether twitch hides the emote from the bits card.
- Type
:class`bool`
- class twitchio.Clip(http: HTTPHandler, data: dict)#
Represents a Twitch Clip
- broadcaster#
The user whose channel the clip was created on.
- Type
- creator#
The user who created the clip.
- Type
- created_at#
When the clip was created.
- Type
- asyncdelete
- asyncedit
- asyncget_redemptions
- class twitchio.CustomReward(http: HTTPHandler, obj: dict, user: PartialUser)#
Represents a Custom Reward object, as given by the api. Use
get_custom_rewards()to fetch these- id#
The ID of the Custom Reward
- Type
class:str
- image#
The image of the Custom Reward. If none has been uploaded, this defaults to the default image provided
- Type
- max_per_stream#
A tuple that indicates whether there is a maximum enabled (index 0) and what the maximum is, if enabled (index 1)
- max_per_user_stream#
A tuple that indicates whether there is a per user maximum enabled (index 0) and what the maximum is, if enabled (index 1)
- paused#
When True, users cannot redeem this reward
- Type
:class`bool`
- redemptions_skip_queue#
Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status
- Type
:class:`bool
- redemptions_current_stream#
How many times this reward has been redeemed in the current stream. Will be
Noneif the stream is not live or max_per_stream is disabled- Type
Optional[
int]
- cooldown_until#
If not
None, a timestamp that indicates when the cooldown for this reward ends- Type
Optional[
datetime.datetime]
- coroutine edit(title: str | None = None, prompt: str | None = None, cost: int | None = None, background_color: str | None = None, enabled: bool | None = None, input_required: bool | None = None, max_per_stream_enabled: bool | None = None, max_per_stream: int | None = None, max_per_user_per_stream_enabled: bool | None = None, max_per_user_per_stream: int | None = None, global_cooldown_enabled: bool | None = None, global_cooldown: int | None = None, paused: bool | None = None, redemptions_skip_queue: bool | None = None) Self#
Edits the reward. Note that apps can only modify rewards they have made.
- Parameters
title (Optional[
str]) – the new title of the rewardprompt (Optional[
str]) – the new prompt for the rewardcost (Optional[
int]) – the new cost for the rewardbackground_color (Optional[
str]) – the new background color for the rewardenabled (Optional[
bool]) – whether the reward is enabled or notinput_required (Optional[
bool]) – whether user input is required or notmax_per_stream_enabled (Optional[
bool]) – whether the stream limit should be enabledmax_per_stream (Optional[
int]) – how many times this can be redeemed per streammax_per_user_per_stream_enabled (Optional[
bool]) – whether the user stream limit should be enabledmax_per_user_per_stream (Optional[
int]) – how many times a user can redeem this reward per streamglobal_cooldown_enabled (Optional[
bool]) – whether the global cooldown should be enabledglobal_cooldown (Optional[
int]) – how many seconds the global cooldown should bepaused (Optional[
bool]) – whether redemptions on this reward should be paused or notredemptions_skip_queue (Optional[
bool]) – whether redemptions skip the request queue or not
- Return type
CustomRewarditself.
- coroutine get_redemptions(status: Literal['UNFULFILLED', 'FULFILLED', 'CANCELLED'], sort: Literal['OLDEST', 'NEWEST'] = 'OLDEST') HTTPAwaitableAsyncIterator[CustomRewardRedemption]#
Gets redemptions for this reward
- class twitchio.CustomRewardRedemption(http: HTTPHandler, obj: dict, parent: CustomReward | None)#
A redemption of a
CustomReward- user#
The user who redeemed the reward
- Type
- input#
The input from the user, if the reward requires it. Otherwise this is an empty string
- Type
- status#
The status of the redemption
- Type
Literal[“UNFULFILLED”, “FULFILLED”, “CANCELLED”]
- redeemed_at#
When the reward was redeemed
- Type
- reward#
The reward this was redeemed with. This will always be a
CustomRewardwhen fetched withCustomReward.get_redemptions()- Type
Union[
PartialCustomReward,CustomReward]
- class twitchio.Extension(data)#
Represents an extension for a specified user
- class twitchio.ExtensionBuilder(panels: list[twitchio.models.Extension] | None = None, overlays: list[twitchio.models.Extension] | None = None, components: list[twitchio.models.Extension] | None = None)#
Represents an extension to be updated for a specific user
- class twitchio.FollowEvent(http: HTTPHandler, data: dict, from_: User | PartialUser | None = None, to: User | PartialUser | None = None)#
Represents a Follow Event.
- from_user#
The user that followed another user.
- Type
Union[
User,PartialUser]
- to_user#
The user that was followed.
- Type
Union[
User,PartialUser]
- followed_at#
When the follow happened.
- Type
- defart_url
- class twitchio.Game(http: HTTPHandler, data: dict)#
Represents a Game on twitch
- class twitchio.Goal(http: HTTPHandler, data: dict)#
Represents a list of Goals for a broadcaster / channel
- broadcaster#
The broadcaster
- Type
- type#
The type of goal
- Type
Literal[“follower”, “subscription”, “new_subscription”]
- created_at#
Date and time of when the broadcaster created the goal
- Type
- class twitchio.HypeTrainContribution(http: HTTPHandler, data: dict)#
A Contribution to a Hype Train
- total#
Total aggregated amount of all contributions by the top contributor. If type is
BITS, total represents aggregate amount of bits used. If type isSUBS, aggregate total where 500, 1000, or 2500 represent tier 1, 2, or 3 subscriptions respectively. For example, if top contributor has gifted a tier 1, 2, and 3 subscription, total would be 4000.- Type
- user#
The user making the contribution.
- Type
- class twitchio.HypeTrainEvent(http: HTTPHandler, data: dict)#
Represents a Hype Train Event (progression)
- broadcaster#
The user whose channel the Hype Train is occurring on.
- Type
- timestamp#
The time the event happened at.
- Type
- cooldown_end_time#
The time that another Hype Train can happen at.
- Type
- expiry#
The time that this Hype Train expires at.
- Type
- started_at#
The time that this Hype Train started at.
- Type
- last_contribution#
The last contribution to this Hype Train.
- top_contributions#
The top contributors to the Hype Train.
- Type
list[
HypeTrainContribution]
- asyncevent_token_expired
- asyncevent_token_refreshed
- asyncget_client_credentials
- asyncget_client_token
- asyncget_irc_token
- asyncget_user_token
- class twitchio.IRCTokenHandler(access_token: str)#
A token handler to be used for IRC-only connections. You will not be able to make API calls while using this token handler. This handler does not accept a Client ID, or refresh token. If you want functionality such as refreshing your token, use the
SimpleTokenHandler, or subclassBaseTokenHandler- coroutine event_token_expired(token: Token) twitchio.tokens.Token | None#
This function is a coroutine. Method to be overriden in a subclass.
This function is a special event hook into the HTTP system. It is called when a token expires and cannot be refreshed automatically. From here, you may return a new token for the HTTP system to use instead. Alternatively, you may return
Noneto signal the HTTP system to callget_user_token()instead.Note
This typically means that user interaction is required to acquire a new token. An exception to this is if you have not provided a client_secret in
get_client_credentials(), then the library will not attempt to refresh tokens.
- coroutine event_token_refreshed(old: Token, new: Token) None#
This function could be a coroutine. Method to be overriden in a subclass.
This function is called whenever the library refreshes a user token. You do not need to do anything from this event, however this can be used to perform actions with the token. For example, this can be used to update tokens in a database, or inform a user.
When this is called, the token has already been refeshed
- coroutine get_client_credentials() tuple[str, str | None]#
This function could be a coroutine. Method to be overriden in a subclass.
This should return a
tupleof (client id, client secret). The client secret is not required, however the client id is required to make requests to the twitch API. The client secret is required to automatically refresh user tokens when they expire, however it is not required to access the twitch API.
- coroutine get_client_token() BaseToken#
This function could be a coroutine. Method to be overriden in a subclass.
This should return a client token (generated with client id and client secret). If not implemented, the library will attempt to generate one with the credentials returned from
get_client_credentials().Warning
If the library is unable to fetch any client token, it will hard crash. If you do not have means to generate a client token, you may not be able to use certain methods. You will also need to ensure any
Clientmethods have atargetparameter specified, as client tokens are used when no target user is specified.- Returns
The client token.
- Return type
- coroutine get_irc_token(shard_id: int) Token#
This function could be a coroutine. Method to be overriden in a subclass.
This should return a
Tokencontaining an OAuth token with thechat:loginscope.- Parameters
user_name (
str|None) – The name of the user to return a chat token for. Typically, this will beNonewhen using the default shard manager. For a more in-depth explanation, see the shard manager documentation.- Returns
The token with which to connect
- Return type
- coroutine get_user_token(user: BaseUser | PartialUser, scopes: tuple[str]) Token#
This function could be a coroutine. Method to be overriden in a subclass.
This function receives a user and a list of scopes that the request needs any one of to make the request. It should return a
Tokenobject.Note
It is a good idea to pass a refresh token if you have one available, the library will automatically handle refreshing tokens if one is provided.
- Parameters
- Returns
The token for the associated user.
- Return type
- class twitchio.Marker(data: dict)#
Represents a stream Marker
- created_at#
When the marker was created.
- Type
- class twitchio.MaybeActiveExtension(data)#
Represents an extension for a specified user that could be may be activated
- can_activate#
Indicates whether the extension is configured such that it can be activated.
- Type
- class twitchio.ModEvent(http: HTTPHandler, data: dict, broadcaster: PartialUser | User)#
Represents a mod add/remove action
- type#
The type of the event.
- Type
ModEventEnum
- timestamp#
The timestamp of the event.
- Type
- broadcaster#
The user whose channel the event happened on.
- Type
Union[
PartialUser,User]
- user#
The user being removed or added as a moderator.
- Type
- class twitchio.Poll(http: HTTPHandler, data: dict)#
Represents a list of Polls for a broadcaster / channel
- broadcaster#
User of the broadcaster.
- Type
- choices#
The poll choices.
- Type
list[
PollChoice]
- channel_points_per_vote#
Number of Channel Points required to vote once with Channel Points.
- Type
- status#
Poll status. Valid values: ACTIVE, COMPLETED, TERMINATED, ARCHIVED, MODERATED, INVALID
- Type
- started_at#
Date and time the the poll was started.
- Type
- ended_at#
Date and time the the poll was ended.
- Type
- class twitchio.Prediction(http: HTTPHandler, data: dict)#
Represents channel point predictions
- user#
The user who is streaming.
- Type
- outcomes#
List of possible outcomes for the Prediction.
- Type
list[
PredictionOutcome]
- created_at#
Time for when the Prediction was created.
- Type
- ended_at#
Time for when the Prediction ended.
- Type
datetime.datetime|None
- locked_at#
Time for when the Prediction was locked.
- Type
datetime.datetime|None
- class twitchio.Predictor(http: HTTPHandler, data: dict)#
Represents a predictor
- user#
The user who is streaming.
- Type
- class twitchio.Raid(data: dict)#
Represents a raid for a broadcaster / channel
- created_at#
Date and time of when the raid started.
- Type
- class twitchio.Schedule(http: HTTPHandler, data: dict)#
Represents a channel’s stream schedule.
- segments#
List of segments of a channel’s stream schedule.
- Type
list[
ScheduleSegment]
- user#
The user of the channel associated to the schedule.
- Type
- vacation#
Vacation details of stream schedule.
- Type
ScheduleVacation|Null
- class twitchio.ScheduleSegment(data: dict)#
Represents a list segments of a channel’s stream schedule
- start_time#
Scheduled start time for the scheduled broadcast
- Type
- end_time#
Scheduled end time for the scheduled broadcast
- Type
- canceled_until#
Used with recurring scheduled broadcasts. Specifies the date of the next recurring broadcast.
- Type
- category#
The game or category details for the scheduled broadcast.
- Type
- class twitchio.ScheduleVacation(data: dict)#
A schedule’s vacation details
- start_time#
Start date of stream schedule vaction.
- Type
- end_time#
End date of stream schedule vaction.
- Type
- asyncevent_token_expired
- asyncevent_token_refreshed
- asyncget_client_credentials
- asyncget_client_token
- asyncget_irc_token
- asyncget_user_token
- class twitchio.SimpleTokenHandler(access_token: str, client_id: str, refresh_token: str | None = None, client_token: str | None = None, client_secret: str | None = None)#
A simple token handler, it takes an access token (and optionally a refresh token), and uses that access token for every request. You may also pass a client_token, which will be used for all requests that do not use a user token. If not provided, the user access token will be used for all requests.
- client_token#
The token to use for all client credential requests (requests that don’t require user authorization)
- Type
Optional[
str]
- client_secret#
The client secret associated with the client id. This can be used to refresh tokens if they expire
- Type
Optional[
str]
- coroutine event_token_expired(token: Token) twitchio.tokens.Token | None#
This function is a coroutine. Method to be overriden in a subclass.
This function is a special event hook into the HTTP system. It is called when a token expires and cannot be refreshed automatically. From here, you may return a new token for the HTTP system to use instead. Alternatively, you may return
Noneto signal the HTTP system to callget_user_token()instead.Note
This typically means that user interaction is required to acquire a new token. An exception to this is if you have not provided a client_secret in
get_client_credentials(), then the library will not attempt to refresh tokens.
- coroutine event_token_refreshed(old: Token, new: Token) None#
This function could be a coroutine. Method to be overriden in a subclass.
This function is called whenever the library refreshes a user token. You do not need to do anything from this event, however this can be used to perform actions with the token. For example, this can be used to update tokens in a database, or inform a user.
When this is called, the token has already been refeshed
- coroutine get_client_credentials() tuple[str, str | None]#
This function could be a coroutine. Method to be overriden in a subclass.
This should return a
tupleof (client id, client secret). The client secret is not required, however the client id is required to make requests to the twitch API. The client secret is required to automatically refresh user tokens when they expire, however it is not required to access the twitch API.
- coroutine get_client_token() BaseToken#
This function could be a coroutine. Method to be overriden in a subclass.
This should return a client token (generated with client id and client secret). If not implemented, the library will attempt to generate one with the credentials returned from
get_client_credentials().Warning
If the library is unable to fetch any client token, it will hard crash. If you do not have means to generate a client token, you may not be able to use certain methods. You will also need to ensure any
Clientmethods have atargetparameter specified, as client tokens are used when no target user is specified.- Returns
The client token.
- Return type
- coroutine get_irc_token(shard_id: int) Token#
This function could be a coroutine. Method to be overriden in a subclass.
This should return a
Tokencontaining an OAuth token with thechat:loginscope.- Parameters
user_name (
str|None) – The name of the user to return a chat token for. Typically, this will beNonewhen using the default shard manager. For a more in-depth explanation, see the shard manager documentation.- Returns
The token with which to connect
- Return type
- coroutine get_user_token(user: BaseUser | PartialUser, scopes: tuple[str]) Token#
This function could be a coroutine. Method to be overriden in a subclass.
This function receives a user and a list of scopes that the request needs any one of to make the request. It should return a
Tokenobject.Note
It is a good idea to pass a refresh token if you have one available, the library will automatically handle refreshing tokens if one is provided.
- Parameters
- Returns
The token for the associated user.
- Return type
- class twitchio.Stream(http: HTTPHandler, data: dict)#
Represents a Stream
- user#
The user who is streaming.
- Type
- started_at#
UTC timestamp of when the stream started.
- Type
- class twitchio.SubscriptionEvent(http: HTTPHandler, data: dict, broadcaster: User | PartialUser | None = None)#
Represents a Subscription Event. This is for when someone subscribes to the target user.
- broadcaster#
The user that was subscribed to.
- Type
Union[
User,PartialUser]
- user#
The user who subscribed.
- Type
Union[
User,PartialUser]
- plan_name#
Name of the description. (twitch docs aren’t helpful, if you know what this is specifically please PR :) ).
- Type
- gifter#
The user that gifted the sub, if applicable.
- Type
PartialUser|None
- class twitchio.Team(http: HTTPHandler, data: dict)#
Represents information for a specific Twitch Team
- users#
List of users in the specified Team.
- Type
list[
PartialUser]
- created_at#
Date and time the Team was created.
- Type
- updated_at#
Date and time the Team was last updated.
- Type
- class twitchio.Token(access_token: str, refresh_token: str | None = None)#
A container around user OAuth tokens. This class will automatically ensure tokens are valid before allowing the library to use them, and will refresh tokens if possible.
- x == y
Checks if the token is equal to another.
- x != y
Checks if the token is not equal to another.
- str(x)
Returns the token.
- hash(x)
Returns the hash of the access token.
New in version 3.0.
- refresh_token#
The refresh token associated with the access token. This is not useful unless you have provided a Client Secret from
TokenHandler.get_client_credentials.- Type
str|None
- coroutine get(http: HTTPHandler, handler: BaseTokenHandler, session: aiohttp.ClientSession) str#
This function is a coroutine. Ensures the token is still within the validation period, and then returns the current access token.
- Parameters
http (
HTTPHandler) – The HTTP sessionhandler (
BaseTokenHandler) – The handler passed to your Client/Botsession (
ClientSession) – The session to use for validating the token
- Raises
InvalidToken – This token is invalid
- Returns
The access token
- Return type
- has_scope(scope: str) bool | None#
A helper function which determines whether the given token has a given scope or not. If the token has not previously been validated, this function will return
None
- coroutine refresh(handler: BaseTokenHandler, session: ClientSession) str#
This function is a coroutine. Refreshes the access token, if a refresh token has been provided. If one hasn’t been provided, this will raise
InvalidToken.- Parameters
handler (
BaseTokenHandler) – The token handler being used to refresh this token. This should be the same handler that was passed to your Client/Botsession (
ClientSession) – The session to use to refresh the token
- Return type
- Raises
RefreshFailure – The token could not be refreshed.
- coroutine validate(http: HTTPHandler, handler: BaseTokenHandler, session: aiohttp.ClientSession) None#
This function is a coroutine. Validates the token, caching information on how this token is to be used. Tokens must be validated every hour, as per the dev docs.
- Parameters
http (:class:`~twitchio.http.HTTPManager) – The HTTP session
handler (
BaseTokenHandler) – The handler that was passed to your Client/Botsession (
ClientSession) – The session to use for validating the token
- Raises
InvalidToken – This token is invalid
- class twitchio.UserBan(http: HTTPHandler, data: dict)#
Represents a banned user or one in timeout. This contains all the methods of the
PartialUser, but also contains information about the banned user.- created_at#
The date and time the ban was created.
- Type
- expires_at#
The date and time the timeout will expire. Is None if it’s a ban.
- Type
Optional[
datetime.datetime]
- moderator#
The moderator that banned the user.
- Type
- asyncdelete
- class twitchio.Video(http: HTTPHandler, data: dict, user: PartialUser | User | None = None)#
Represents video information
- user#
User who owns the video.
- Type
- created_at#
Date when the video was created.
- Type
- published_at#
Date when the video was published.
- Type
- coroutine delete() None#
This function is a coroutine.
Deletes the video. For bulk deletion see
Client.delete_videos()- Parameters
token (
str) – The users oauth token with the channel:manage:videos