Dataclass Reference#

ActiveExtension#

Attributes
class twitchio.ActiveExtension(data)#

Represents an active extension for a specified user

id#

ID of the extension.

Type

str

version#

Version of the extension.

Type

str

active#

Activation state of the extension.

Type

bool

name#

Name of the extension.

Type

str

x#

(Video-component Extensions only) X-coordinate of the placement of the extension. Could be None.

Type

int

y#

(Video-component Extensions only) Y-coordinate of the placement of the extension. Could be None.

Type

int

AdSchedule#

class twitchio.AdSchedule(data: dict)#

Represents a channel’s ad schedule.

next_ad_at#

When the next ad will roll. Will be None if the streamer does not schedule ads, or is not live.

Type

Optional[datetime.datetime]

last_ad_at#

When the last ad rolled. Will be None if the streamer has not rolled an ad. Will always be None when this comes from snoozing an ad.

Type

Optional[datetime.datetime]

duration#

How long the upcoming ad will be, in seconds.

Type

int

preroll_freeze_time#

The amount of pre-roll free time remaining for the channel in seconds. Will be 0 if the streamer is not pre-roll free. Will be None when this comes from snoozing an ad.

Type

Optional[int]

snooze_count#

How many snoozes the streamer has left.

Type

int

snooze_refresh_at#

When the streamer will gain another snooze.

Type

datetime.datetime

AutomodCheckMessage#

Attributes
class twitchio.AutomodCheckMessage(id: str, text: str, user: Union[PartialUser, int])#

Represents the message to check with automod

id#

Developer-generated identifier for mapping messages to results.

Type

str

text#

Message text.

Type

str

user_id#

User ID of the sender.

Type

int

AutomodCheckResponse#

Attributes
class twitchio.AutomodCheckResponse(data: dict)#

Represents the response to a message check with automod

id#

The message ID passed in the body of the check

Type

str

permitted#

Indicates if this message meets AutoMod requirements.

Type

bool

Ban#

class twitchio.Ban(http: TwitchHTTP, data: dict)#

Represents a ban for a broadcaster / channel

broadcaster#

The broadcaster whose chat room the user was banned from chatting in.

Type

PartialUser

moderator#

The moderator that banned the user.

Type

PartialUser

user#

The user that was banned.

Type

PartialUser

created_at#

Date and time of when the ban was created.

Type

datetime.datetime

BanEvent#

class twitchio.BanEvent(http: TwitchHTTP, data: dict, broadcaster: Optional[Union[PartialUser, User]])#

This has been deprecated.

Represents a user being banned from a channel.

id#

The event ID.

Type

str

type#

Type of ban event. Either moderation.user.ban or moderation.user.unban.

Type

str

timestamp#

The time the action occurred at.

Type

datetime.datetime

version#

The version of the endpoint.

Type

float

broadcaster#

The user whose channel the ban/unban occurred on.

Type

PartialUser

user#

The user who was banned/unbanned.

Type

PartialUser

moderator#

The user who performed the action.

Type

PartialUser

expires_at#

When the ban expires.

Type

Optional[datetime.datetime]

reason#

The reason the moderator banned/unbanned the user.

Type

str

BitLeaderboardUser#

class twitchio.BitLeaderboardUser(http: TwitchHTTP, data: dict)#

BitsLeaderboard#

class twitchio.BitsLeaderboard(http: TwitchHTTP, data: dict)#

Represents a Bits leaderboard from the twitch API.

started_at#

The time the leaderboard started.

Type

Optional[datetime.datetime]

ended_at#

The time the leaderboard ended.

Type

Optional[datetime.datetime]

leaders#

The current leaders of the Leaderboard.

Type

List[BitLeaderboardUser]

Channel#

Attributes
Methods
class twitchio.Channel(name: str, websocket: WSConnection)#
coroutine fetch_bits_leaderboard(token: str, period: str = 'all', user_id: Optional[int] = None, started_at: Optional[datetime] = None) BitsLeaderboard#

This function is a coroutine.

Fetches the bits leaderboard for the channel. This requires an OAuth token with the bits:read scope.

Parameters
  • token (str) – the OAuth token with the bits:read scope

  • period (Optional[str]) – one of day, week, month, year, or all, defaults to all

  • started_at (Optional[datetime.datetime]) – the timestamp to start the period at. This is ignored if the period is all

  • user_id (Optional[int]) – the id of the user to fetch for

get_chatter(name: str) Optional[Union[Chatter, PartialChatter]]#

Retrieve a chatter from the channels user cache.

Parameters

name (str) – The chatter’s name to try and retrieve.

Returns

Union[twitchio.chatter.Chatter, twitchio.chatter.PartialChatter] – Could be a twitchio.user.PartialChatter depending on how the user joined the channel. Returns None if no user was found.

coroutine send(content: str)#

This function is a coroutine.

Send a message to the destination associated with the dataclass.

Destination will either be a channel or user.

Parameters

content (str) – The content you wish to send as a message. The content must be a string.

Raises

InvalidContent – Invalid content.

coroutine user(force=False) User#

This function is a coroutine.

Fetches the User from the api.

Parameters

force (bool) – Whether to force a fetch from the api, or try and pull from the cache. Defaults to False

Returns

twitchio.User the user associated with the channel

coroutine whisper(content: str)#

This function is a coroutine.

Whispers the user behind the channel. This will not work if the channel is the same as the one you are sending the message from.

Parameters

content (str) – The content to send to the user

property chatters: Optional[Set[Union[Chatter, PartialChatter]]]#

The channels current chatters.

property name: str#

The channel name.

ChannelEmote#

class twitchio.ChannelEmote(http: TwitchHTTP, data: dict)#

Represents a Channel Emote

id#

The ID of the emote.

Type

str

name#

The name of the emote.

Type

str

images#

Contains the image URLs for the emote. These image URLs will always provide a static (i.e., non-animated) emote image with a light background.

Type

dict

tier#

The subscriber tier at which the emote is unlocked.

Type

str

type#

The type of emote.

Type

str

set_id#

An ID that identifies the emote set that the emote belongs to.

Type

str

format#

The formats that the emote is available in.

Type

List[str]

scale#

The sizes that the emote is available in.

Type

List[str]

theme_mode#

The background themes that the emote is available in.

Type

List[str]

ChannelFollowerEvent#

Attributes
class twitchio.ChannelFollowerEvent(http: TwitchHTTP, data: dict)#

Represents a ChannelFollowEvent Event.

user#

The user that followed another user.

Type

Union[User, PartialUser]

followed_at#

When the follow happened.

Type

datetime.datetime

ChannelFollowingEvent#

class twitchio.ChannelFollowingEvent(http: TwitchHTTP, data: dict)#

Represents a ChannelFollowEvent Event.

broadcaster#

The user that is following another user.

Type

Union[User, PartialUser]

followed_at#

When the follow happened.

Type

datetime.datetime

ChannelInfo#

class twitchio.ChannelInfo(http: TwitchHTTP, data: dict)#

Represents a channel’s current information

user#

The user whose channel information was requested.

Type

PartialUser

game_id#

Current game ID being played on the channel.

Type

int

game_name#

Name of the game being played on the channel.

Type

str

title#

Title of the stream.

Type

str

language#

Language of the channel.

Type

str

delay#

Stream delay in seconds. This defaults to 0 if the broadcaster_id does not match the user access token.

Type

int

tags#

The tags applied to the channel.

Type

List[str]

content_classification_labels#

The CCLs applied to the channel.

Type

List[str]

is_branded_content#

Boolean flag indicating if the channel has branded content.

Type

bool

ChannelTeams#

class twitchio.ChannelTeams(http: TwitchHTTP, data: dict)#

Represents the Twitch Teams of which the specified channel/broadcaster is a member

broadcaster#

User of the broadcaster.

Type

PartialUser

background_image_url#

URL for the Team background image.

Type

str

banner#

URL for the Team banner.

Type

str

created_at#

Date and time the Team was created.

Type

datetime.datetime

updated_at#

Date and time the Team was last updated.

Type

datetime.datetime

info#

Team description.

Type

str

thumbnail_url#

Image URL for the Team logo.

Type

str

team_name#

Team name.

Type

str

team_display_name#

Team display name.

Type

str

id#

Team ID.

Type

str

ChatBadge#

Attributes
class twitchio.ChatBadge(data: dict)#

Represents chat badges.

set_id#

An ID that identifies this set of chat badges. For example, Bits or Subscriber.

Type

str

versions#

The list of chat badges in this set.

Type

List[ChatBadgeVersions]

ChatBadgeVersions#

class twitchio.ChatBadgeVersions(data: dict)#

Represents the different versions of the chat badge.

id#

An ID that identifies this version of the badge. The ID can be any value.

Type

str

image_url_1x#

URL to the small version (18px x 18px) of the badge.

Type

str

image_url_2x#

URL to the medium version (36px x 36px) of the badge.

Type

str

image_url_4x#

URL to the large version (72px x 72px) of the badge.

Type

str

title#

The title of the badge.

Type

str

description#

The description of the badge.

Type

str

click_action#

The action to take when clicking on the badge. This can be None if no action is specified

Type

Optional[str]

click_url#

The URL to navigate to when clicking on the badge. This can be None if no URL is specified.

Type

Optional[str]

ChatSettings#

class twitchio.ChatSettings(http: TwitchHTTP, data: dict)#

Represents current chat settings of a broadcaster / channel

broadcaster#

User of the broadcaster. Only returns the ID.

Type

PartialUser

emote_mode#

Indicates whether emote only mode is enabled.

Type

bool

follower_mode#

Indicates whether follower only chat is enabled.

Type

bool

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#

Indicates whether the chat is in slow mode.

Type

bool

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

bool

unique_chat_mode#

Indicates whether the broadcaster requires users to post only unique messages in the chat room.

Type

bool

moderator#

The User of the moderator, if provided. Only returns the ID.

Type

Optional[PartialUser]

non_moderator_chat_delay#

Indicates whether the broadcaster adds a short delay before chat messages appear in the chat room.

Type

Optional[bool]

non_moderator_chat_delay_duration#

The amount of time, in seconds, that messages are delayed from appearing in chat.

Type

Optional[int]

Chatter#

Attributes
Methods
class twitchio.PartialChatter(websocket, **kwargs)#
coroutine send(content: str)#

This function is a coroutine.

Send a message to the destination associated with the dataclass.

Destination will either be a channel or user.

Parameters

content (str) – The content you wish to send as a message. The content must be a string.

Raises

InvalidContent – Invalid content.

coroutine user() User#

This function is a coroutine.

Fetches a twitchio.User object based off the chatters channel name

Returns

twitchio.User

property channel#

The channel associated with the user.

property name#

The users name

class twitchio.Chatter(websocket: WSConnection, **kwargs)#
property badges: dict#

The users badges.

property color: str#

The users color.

property colour: str#

The users colour. Alias to color.

property display_name: Optional[str]#

The user’s display name.

property id: Optional[str]#

The user’s id.

property is_broadcaster: bool#

A boolean indicating whether the User is the broadcaster of the current channel.

property is_mod: bool#

A boolean indicating whether the User is a moderator of the current channel.

property is_subscriber: bool#

A boolean indicating whether the User is a subscriber of the current channel.

Note

changed in 2.1.0: return value is no longer optional. founders will now appear as subscribers

property is_turbo: Optional[bool]#

A boolean indicating whether the User is Turbo.

Could be None if no Tags were received.

property is_vip: bool#

A boolean indicating whether the User is a VIP of the current channel.

property mention: str#

Mentions the users display name by prefixing it with ‘@’

property name: str#

The users name. This may be formatted differently than display name.

property prediction: Optional[PredictionEnum]#

The users current prediction, if one exists.

Returns

Optional[twitchio.enums.PredictionEnum]

ChatterColor#

Attributes
class twitchio.ChatterColor(http: TwitchHTTP, data: dict)#

Represents chatters current name color.

user#

PartialUser of the chatter.

Type

PartialUser

color#

The color of the chatter’s name.

Type

str

CharityCampaign#

class twitchio.CharityCampaign(data: dict, http: TwitchHTTP, broadcaster: PartialUser | None = None)#

Represents a Charity Campaign on a channel.

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

current#

The current funds raised by this campaign.

Type

CharityValues

target#

The target funds to be raised for this campaign.

Type

CharityValues

class twitchio.CharityValues(data: dict)#

Represents the current/target funds of a charity campaign.

value#

The value of the campaign (either so far, or the target value).

Type

int

decimal_places#

The decimal places to be inserted into value.

Type

int

currency#

The currency this charity is raising funds in. eg USD, GBP, EUR.

Type

str

CheerEmote#

class twitchio.CheerEmote(http: TwitchHTTP, data: dict)#

Represents a Cheer Emote

prefix#

The string used to Cheer that precedes the Bits amount.

Type

str

tiers#

The tiers this Cheer Emote has

Type

CheerEmoteTier

type#

Shows whether the emote is global_first_party, global_third_party, channel_custom, display_only, or sponsored.

Type

str

order#

Order of the emotes as shown in the bits card, in ascending order.

Type

str

last_updated :class:`datetime.datetime`

The date this cheermote was last updated.

charitable#

Indicates whether this emote provides a charity contribution match during charity campaigns.

Type

bool

CheerEmoteTier#

class twitchio.CheerEmoteTier(data: dict)#

Represents a Cheer Emote tier.

min_bits#

The minimum bits for the tier

Type

int

id#

The ID of the tier

Type

str

colour#

The colour of the tier

Type

str

images#

contains two dicts, light and dark. Each item will have an animated and static item, which will contain yet another dict, with sizes 1, 1.5, 2, 3, and 4. Ex. cheeremotetier.images["light"]["animated"]["1"]

Type

dict

can_cheer#

Indicates whether emote information is accessible to users.

Type

bool

show_in_bits_card#

Indicates whether twitch hides the emote from the bits card.

Type

:class`bool`

Clip#

class twitchio.Clip(http: TwitchHTTP, data: dict)#

Represents a Twitch Clip

id#

The ID of the clip.

Type

str

url#

The URL of the clip.

Type

str

embed_url#

The URL to embed the clip with.

Type

str

broadcaster#

The user whose channel the clip was created on.

Type

PartialUser

creator#

The user who created the clip.

Type

PartialUser

video_id#

The ID of the video the clip is sourced from.

Type

str

game_id#

The ID of the game that was being played when the clip was created.

Type

str

language#

The language, in an ISO 639-1 format, of the stream when the clip was created.

Type

str

title#

The title of the clip.

Type

str

views#

The amount of views this clip has.

Type

int

created_at#

When the clip was created.

Type

datetime.datetime

thumbnail_url#

The url of the clip thumbnail.

Type

str

duration#

Duration of the Clip in seconds (up to 0.1 precision).

Type

float

vod_offset#

The zero-based offset, in seconds, to where the clip starts in the video (VOD) or stream. This can be None if the parent no longer exists

Type

Optional[int]

Indicates if the clip is featured or not.

Type

bool

ContentClassificationLabel#

Attributes
class twitchio.ContentClassificationLabel(data: dict)#

Represents a Content Classification Label.

id#

Unique identifier for the CCL.

Type

str

description#

Localized description of the CCL.

Type

str

name#

Localized name of the CCL.

Type

str

CustomReward#

class twitchio.CustomReward(http: TwitchHTTP, obj: dict, channel: 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

str

title#

The title of the custom reward

Type

str

image#

The url of the image of the custom reward

Type

str

background_color#

The background color of the custom reward

Type

str

enabled#

Whether the custom reward is enabled

Type

bool

cost#

The cost of the custom reward

Type

int

prompt#

The prompt of the custom reward

Type

str

input_required#

Whether the custom reward requires input

Type

bool

max_per_stream#

Whether the custom reward is limited to a certain amount per stream, and how many

Type

Tuple[bool, int]

max_per_user_stream#

Whether the custom reward is limited to a certain amount per user per stream, and how many

Type

Tuple[bool, int]

cooldown#

Whether the custom reward has a cooldown, and how long it is

Type

Tuple[bool, int]

paused#

Whether the custom reward is paused

Type

bool

in_stock#

Whether the custom reward is in stock

Type

bool

redemptions_skip_queue#

Whether the custom reward’s redemptions skip the request queue

Type

bool

redemptions_current_stream#

Whether the custom reward’s redemptions are only valid for the current stream

Type

bool

cooldown_until#

The datetime the custom reward’s cooldown will expire

Type

datetime.datetime

coroutine delete(token: str)#

Deletes the custom reward

Parameters

tokenstr the oauth token of the target channel

Returns

None

coroutine edit(token: str, title: Optional[str] = None, prompt: Optional[str] = None, cost: Optional[int] = None, background_color: Optional[str] = None, enabled: Optional[bool] = None, input_required: Optional[bool] = None, max_per_stream_enabled: Optional[bool] = None, max_per_stream: Optional[int] = None, max_per_user_per_stream_enabled: Optional[bool] = None, max_per_user_per_stream: Optional[int] = None, global_cooldown_enabled: Optional[bool] = None, global_cooldown: Optional[int] = None, paused: Optional[bool] = None, redemptions_skip_queue: Optional[bool] = None)#

Edits the reward. Note that apps can only modify rewards they have made.

Parameters
  • token (str) – The bearer token for the channel of the reward

  • title (Optional[str]) – The new title of the reward

  • prompt (Optional[str]) – The new prompt for the reward

  • cost (Optional[int]) – The new cost for the reward

  • background_color (Optional[str]) – The new background color for the reward

  • enabled (Optional[bool]) – Whether the reward is enabled or not

  • input_required (Optional[bool]) – Whether user input is required or not

  • max_per_stream_enabled (Optional[bool]) – Whether the stream limit should be enabled

  • max_per_stream (Optional[int]) – How many times this can be redeemed per stream

  • max_per_user_per_stream_enabled (Optional[bool]) – Whether the user stream limit should be enabled

  • max_per_user_per_stream (Optional[int]) – How many times a user can redeem this reward per stream

  • global_cooldown_enabled (Optional[bool]) – Whether the global cooldown should be enabled

  • global_cooldown (Optional[int]) – How many seconds the global cooldown should be

  • paused (Optional[bool]) – Whether redemptions on this reward should be paused or not

  • redemptions_skip_queue (Optional[bool]) – Whether redemptions skip the request queue or not

Returns

CustomReward itself.

coroutine get_redemptions(token: str, status: str, sort: str = 'OLDEST', first: int = 20)#

Gets redemptions for this reward

Parameters
  • tokenstr the oauth token of the target channel

  • statusstr one of UNFULFILLED, FULFILLED or CANCELED

  • sort – Optional[str] the order redemptions are returned in. One of OLDEST, NEWEST. Default: OLDEST.

  • firstint Number of results to be returned when getting the paginated Custom Reward Redemption objects for a reward. Limit: 50. Default: 20.

CustomRewardRedemption#

Methods
class twitchio.CustomRewardRedemption(obj: dict, http: TwitchHTTP, parent: Optional[CustomReward])#
coroutine fulfill(token: str)#

marks the redemption as fulfilled

Parameters

tokenstr the token of the target channel

Returns

itself.

coroutine refund(token: str)#

marks the redemption as cancelled

Parameters

tokenstr the token of the target channel

Returns

itself.

Emote#

class twitchio.Emote(data: dict)#

Represents an Emote.

Note

It seems twitch is sometimes returning duplicate information from the emotes endpoint. To deduplicate your emotes, you can call set() on the list of emotes (or any other hashmap), which will remove the duplicates.

my_list_of_emotes = await user.get_user_emotes(...)
deduplicated_emotes = set(my_list_of_emotes)
id#

The unique ID of the emote.

Type

str

set_id#

The ID of the set this emote belongs to. Will be None if the emote doesn’t belong to a set.

Type

Optional[str]

owner_id#

The ID of the channel this emote belongs to.

Type

Optional[str]

name#

The name of this emote, as the user sees it.

Type

str

type#

The reason this emote is available to the user. Some available values (twitch hasn’t documented this properly, there might be more):

  • follower

  • subscription

  • bitstier

  • hypetrain

  • globals (global emotes)

Type

str

scales#

The available scaling for this emote. These are typically floats (ex. “1.0”, “2.0”).

Type

list[str]

format_static#

Whether this emote is available as a static (PNG) file.

Type

bool

format_animated#

Whether this emote is available as an animated (GIF) file.

Type

bool

theme_light#

Whether this emote is available in light theme background mode.

Type

bool

theme_dark#

Whether this emote is available in dark theme background mode.

Type

bool

url_for(format: Literal['static', 'animated'], theme: Literal['dark', 'light'], scale: str) str#

Returns a cdn url that can be used to download or serve the emote on a website. This function validates that the arguments passed are possible values to serve the emote.

Parameters
  • format (Literal["static", "animated"]) – The format of the emote. You can check what formats are available using format_static and format_animated.

  • theme (Literal["dark", "light"]) – The theme of the emote. You can check what themes are available using format_dark and format_light.

  • scale (str) – The scale of the emote. This should be formatted in this format: "1.0". The scales available for this emote can be checked via scales.

Returns

str

Extension#

Attributes
class twitchio.Extension(data)#

Represents an extension for a specified user

id#

ID of the extension.

Type

str

version#

Version of the extension.

Type

str

active#

Activation state of the extension, for each extension type (component, overlay, mobile, panel).

Type

bool

ExtensionBuilder#

class twitchio.ExtensionBuilder(panels: Optional[List[Extension]] = None, overlays: Optional[List[Extension]] = None, components: Optional[List[Extension]] = None)#

Represents an extension to be updated for a specific user

panels#

List of panels to update for an extension.

Type

List[Extension]

overlays#

List of overlays to update for an extension.

Type

List[Extension]

components#

List of components to update for an extension.

Type

List[Extension]

FollowEvent#

class twitchio.FollowEvent(http: TwitchHTTP, data: dict, from_: Optional[Union[PartialUser, User]] = None, to: Optional[Union[PartialUser, User]] = 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

datetime.datetime

Game#

Attributes
Methods
class twitchio.Game(data: dict)#

Represents a Game on twitch

id#

Game ID.

Type

int

name#

Game name.

Type

str

box_art_url#

Template URL for the game’s box art.

Type

str

igdb_id#

The IGDB ID of the game. If this is not available to Twitch it will return None

Type

Optional[int]

art_url(width: int, height: int) str#

Adds width and height into the box art url

Parameters
  • width (int) – The width of the image

  • height (int) – The height of the image

Returns

str

GlobalEmote#

class twitchio.GlobalEmote(http: TwitchHTTP, data: dict)#

Represents a Global Emote

id#

The ID of the emote.

Type

str

name#

The name of the emote.

Type

str

images#

Contains the image URLs for the emote. These image URLs will always provide a static (i.e., non-animated) emote image with a light background.

Type

dict

format#

The formats that the emote is available in.

Type

List[str]

scale#

The sizes that the emote is available in.

Type

List[str]

theme_mode#

The background themes that the emote is available in.

Type

List[str]

Goal#

class twitchio.Goal(http: TwitchHTTP, data: dict)#

Represents a list of Goals for a broadcaster / channel

id#

An ID that uniquely identifies this goal.

Type

str

broadcaster#

User of the broadcaster.

Type

PartialUser

type#

The type of goal. Valid values: follower, subscription, subscription_count, new_subscription and new_subscription_count.

Type

str

description#

A description of the goal, if specified.

Type

str

current_amount#

The current value.

Type

int

target_amount#

Number of Bits required to vote once with Bits.

Type

int

created_at#

Date and time of when the broadcaster created the goal.

Type

datetime.datetime

HypeChatData

class twitchio.HypeChatData(tags: dict)#

Represents information about hype chats.

amount#

The amount paid.

Type

int

exponent#

Indicates how many decimal points this currency represents partial amounts in. Decimal points start from the right side of the value defined in pinned-chat-paid-amount.

Type

int

currency#

The currency paid in, uses ISO 4217 alphabetic currency code (eg. USD, EUR, GBP). The ISO 4217 alphabetic currency code the user has sent the Hype Chat in.

Type

str

is_system_message#

A Boolean value that determines if the message sent with the Hype Chat was filled in by the system. If True, the user entered no message and the body message was automatically filled in by the system. If False, the user provided their own message to send with the Hype Chat.

Type

bool

level#

The level of the Hype Chat, in English. e.g. ONE, TWO, THREE up to TEN.

Type

str

HypeTrainContribution#

Attributes
class twitchio.HypeTrainContribution(http: TwitchHTTP, 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 is SUBS, 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

int

type#

Identifies the contribution method, either BITS, SUBS or OTHER.

Type

str

user#

The user making the contribution.

Type

PartialUser

HypeTrainEvent#

class twitchio.HypeTrainEvent(http: TwitchHTTP, data: dict)#

Represents a Hype Train Event (progression)

id#

The ID of the event.

Type

str

event_id#

The ID of the Hype Train.

Type

str

type#

The type of the event. Currently only hypetrain.progression.

Type

str

version#

The version of the endpoint.

Type

str

broadcaster#

The user whose channel the Hype Train is occurring on.

Type

PartialUser

timestamp#

The time the event happened at.

Type

datetime.datetime

cooldown_end_time#

The time that another Hype Train can happen at.

Type

datetime.datetime

expiry#

The time that this Hype Train expires at.

Type

datetime.datetime

started_at#

The time that this Hype Train started at.

Type

datetime.datetime

last_contribution#

The last contribution to this Hype Train.

Type

HypeTrainContribution

level#

The level reached on this Hype Train (1-5).

Type

int

top_contributions#

The top contributors to the Hype Train.

Type

List[HypeTrainContribution]

contributions_total#

The total score towards completing the goal.

Type

int

goal#

The goal for the next Hype Train level

Type

int

Marker#

class twitchio.Marker(data: dict)#

Represents a stream Marker

id#

The ID of the marker.

Type

str

created_at#

When the marker was created.

Type

datetime.datetime

description#

The description of the marker.

Type

str

position#

The position of the marker, in seconds.

Type

int

url#

The url that leads to the marker.

Type

Optional[str]

MaybeActiveExtension#

class twitchio.MaybeActiveExtension(data)#

Represents an extension for a specified user that could be may be activated

id#

ID of the extension.

Type

str

version#

Version of the extension.

Type

str

name#

Name of the extension.

Type

str

can_activate#

Indicates whether the extension is configured such that it can be activated.

Type

bool

types#

Types for which the extension can be activated.

Type

List[str]

Message#

class twitchio.Message(**kwargs)#
content#

The content of this message.

Type

str

echo#

Boolean representing if this is a self-message or not.

Type

bool

first#

Boolean representing whether it’s a first message or not.

Type

bool

hype_chat_data#

Any hype chat information associated with the message. This will be None when the message is not a hype chat.

Type

Optional[HypeChatData]

property author: Union[Chatter, PartialChatter]#

The User object associated with the Message.

property channel: Channel#

The Channel object associated with the Message.

property id: str#

The Message ID.

property raw_data: str#

The raw data received from Twitch for this Message.

property tags: dict#

The tags associated with the Message.

Could be None.

property timestamp: datetime#

The Twitch timestamp for this Message.

Returns

timestamp – UTC datetime object of the Twitch timestamp.

ModEvent#

class twitchio.ModEvent(http: TwitchHTTP, data: dict, broadcaster: Union[PartialUser, User])#

Represents a mod add/remove action

id#

The ID of the event.

Type

str

type#

The type of the event.

Type

ModEventEnum

timestamp#

The timestamp of the event.

Type

datetime.datetime

version#

The version of the endpoint.

Type

str

broadcaster#

The user whose channel the event happened on.

Type

Union[PartialUser, User]

user#

The user being removed or added as a moderator.

Type

PartialUser

Poll#

class twitchio.Poll(http: TwitchHTTP, data: dict)#

Represents a list of Polls for a broadcaster / channel

Note

Twitch have removed support for voting with bits. By default bits_votes, bits_voting_enabled and bits_per_vote will be received as either 0 or False.

id#

ID of a poll.

Type

str

broadcaster#

User of the broadcaster.

Type

PartialUser

title#

Question displayed for the poll.

Type

str

choices#

The poll choices.

Type

List[PollChoice]

bits_voting_enabled#

Indicates if Bits can be used for voting.

Warning

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

Type

bool

bits_per_vote#

Number of Bits required to vote once with Bits.

Warning

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

Type

int

channel_points_voting_enabled#

Indicates if Channel Points can be used for voting.

Type

bool

channel_points_per_vote#

Number of Channel Points required to vote once with Channel Points.

Type

int

status#

Poll status. Valid values: ACTIVE, COMPLETED, TERMINATED, ARCHIVED, MODERATED, INVALID

Type

str

duration#

Total duration for the poll (in seconds).

Type

int

started_at#

Date and time the poll was started.

Type

datetime.datetime

ended_at#

Date and time the poll was ended.

Type

datetime.datetime

class twitchio.PollChoice(data: dict)#

Represents a polls choices

id#

ID for the choice.

Type

str

title#

Text displayed for the choice.

Type

str

votes#

Total number of votes received for the choice across all methods of voting.

Type

int

channel_points_votes#

Number of votes received via Channel Points.

Type

int

bits_votes#

Number of votes received via Bits.

Warning

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

Type

int

Predictions#

class twitchio.Prediction(http: TwitchHTTP, data: dict)#

Represents channel point predictions

user#

The user who is streaming.

Type

PartialUser

prediction_id#

ID of the Prediction.

Type

str

title#

Title for the Prediction.

Type

str

winning_outcome_id#

ID of the winning outcome

Type

str

outcomes#

List of possible outcomes for the Prediction.

Type

List[PredictionOutcome]

prediction_window#

Total duration for the Prediction (in seconds).

Type

int

prediction_status#

Status of the Prediction.

Type

str

created_at#

Time for when the Prediction was created.

Type

datetime.datetime

ended_at#

Time for when the Prediction ended.

Type

datetime.datetime

locked_at#

Time for when the Prediction was locked.

Type

datetime.datetime

class twitchio.Predictor(http: TwitchHTTP, data: dict)#

Represents a predictor

user#

The user who is streaming.

Type

PartialUser

channel_points_used#

Number of Channel Points used by the user.

Type

int

channel_points_won#

Number of Channel Points won by the user.

Type

int

Raid#

Attributes
class twitchio.Raid(data: dict)#

Represents a raid for a broadcaster / channel

created_at#

Date and time of when the raid started.

Type

datetime.datetime

is_mature#

Indicates whether the stream being raided is marked as mature.

Type

bool

Schedules#

Attributes
class twitchio.Schedule(http: TwitchHTTP, 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

PartialUser

vacation#

Vacation details of stream schedule.

Type

ScheduleVacation

class twitchio.ScheduleSegment(data: dict)#

Represents a list segments of a channel’s stream schedule

id#

The ID for the scheduled broadcast.

Type

str

start_time#

Scheduled start time for the scheduled broadcast

Type

datetime.datetime

end_time#

Scheduled end time for the scheduled broadcast

Type

Optional[datetime.datetime]

title#

Title for the scheduled broadcast.

Type

str

canceled_until#

Used with recurring scheduled broadcasts. Specifies the date of the next recurring broadcast.

Type

datetime.datetime

category#

The game or category details for the scheduled broadcast.

Type

ScheduleCategory

is_recurring#

Indicates if the scheduled broadcast is recurring weekly.

Type

bool

Attributes
class twitchio.ScheduleCategory(data: dict)#

Game or category details of a stream’s schedule

id#

The game or category ID.

Type

str

name#

The game or category name.

Type

str

Attributes
class twitchio.ScheduleVacation(data: dict)#

A schedule’s vacation details

start_time#

Start date of stream schedule vaction.

Type

datetime.datetime

end_time#

End date of stream schedule vaction.

Type

datetime.datetime

SearchUser#

class twitchio.SearchUser(http: TwitchHTTP, data: dict)#

Represents a User that has been searched for.

id#

The ID of the user.

Type

int

name#

The name of the user.

Type

str

display_name#

The broadcaster’s display name.

Type

str

game_id#

The ID of the game that the broadcaster is playing or last played.

Type

str

title#

The stream’s title. Is an empty string if the broadcaster didn’t set it.

Type

str

thumbnail_url :class:`str`

A URL to a thumbnail of the broadcaster’s profile image.

language :class:`str`

The ISO 639-1 two-letter language code of the language used by the broadcaster. For example, en for English.

live#

A Boolean value that determines whether the broadcaster is streaming live. Is true if the broadcaster is streaming live; otherwise, false.

Type

bool

started_at#

The UTC date and time of when the broadcaster started streaming.

Type

datetime.datetime

tag_ids#

Tag IDs that apply to the stream.

Warning

This field will be deprecated by twitch in 2023.

Type

List[str]

tags#

The tags applied to the channel.

Type

List[str]

ShieldStatus#

class twitchio.ShieldStatus(http: TwitchHTTP, data: dict)#

Represents a Shield Mode activation status.

moderator#

The moderator that last activated Shield Mode.

Type

PartialUser

display_name#

The moderator’s display name. Is an empty string if Shield Mode hasn’t been previously activated.

Type

str

last_activated_at#

The UTC datetime of when Shield Mode was last activated. Is an empty string if Shield Mode hasn’t been previously activated.

Type

datetime.datetime

is_active#

A Boolean value that determines whether Shield Mode is active. Is true if the broadcaster activated Shield Mode; otherwise, false.

Type

bool

Stream#

class twitchio.Stream(http: TwitchHTTP, data: dict)#

Represents a Stream

id#

The current stream ID.

Type

int

user#

The user who is streaming.

Type

PartialUser

game_id#

Current game ID being played on the channel.

Type

str

game_name#

Name of the game being played on the channel.

Type

str

type#

Whether the stream is “live” or not.

Type

str

title#

Title of the stream.

Type

str

viewer_count#

Current viewer count of the stream

Type

int

started_at#

UTC timestamp of when the stream started.

Type

datetime.datetime

language#

Language of the channel.

Type

str

thumbnail_url#

Thumbnail URL of the stream.

Type

str

tag_ids#

Tag IDs that apply to the stream.

Warning

This field will be deprecated by twitch in 2023.

Type

List[str]

is_mature#

Indicates whether the stream is intended for mature audience.

Type

bool

tags#

The tags applied to the channel.

Type

List[str]

SubscriptionEvent#

class twitchio.SubscriptionEvent(http: TwitchHTTP, data: dict, broadcaster: Optional[Union[PartialUser, User]] = None, user: Optional[Union[PartialUser, User]] = None)#

Represents a Subscription Event

broadcaster#

The user that was subscribed to.

Type

Union[User, PartialUser]

user#

The user who subscribed.

Type

Union[User, PartialUser]

tier#

The tier at which the user subscribed. Could be 1, 2, or 3.

Type

int

plan_name#

Name of the description. (twitch docs aren’t helpful, if you know what this is specifically please PR :) ).

Type

str

gift#

Whether the subscription is a gift.

Type

bool

Tag#

class twitchio.Tag(data: dict)#

Represents a stream tag

id#

An ID that identifies the tag.

Type

str

auto#

Indicates whether the tag is an automatic tag.

Type

bool

localization_names#

A dictionary that contains the localized names of the tag.

Type

Dict[str, str]

localization_descriptions#

A dictionary that contains the localized descriptions of the tag.

Type

str

Team#

class twitchio.Team(http: TwitchHTTP, data: dict)#

Represents information for a specific Twitch Team

users#

List of users in the specified Team.

Type

List[PartialUser]

background_image_url#

URL for the Team background image.

Type

str

banner#

URL for the Team banner.

Type

str

created_at#

Date and time the Team was created.

Type

datetime.datetime

updated_at#

Date and time the Team was last updated.

Type

datetime.datetime

info#

Team description.

Type

str

thumbnail_url#

Image URL for the Team logo.

Type

str

team_name#

Team name.

Type

str

team_display_name#

Team display name.

Type

str

id#

Team ID.

Type

str

Timeout#

class twitchio.Timeout(http: TwitchHTTP, data: dict)#

Represents a timeout for a broadcaster / channel

broadcaster#

The broadcaster whose chat room the user was timed out from chatting in.

Type

PartialUser

moderator#

The moderator that timed the user out.

Type

PartialUser

user#

The user that was timed out.

Type

PartialUser

created_at#

Date and time of when the timeout was created.

Type

datetime.datetime

end_time#

Date and time of when the timeout will end.

Type

datetime.datetime

User#

Attributes
Methods
class twitchio.PartialUser(http: TwitchHTTP, id: Union[int, str], name: Optional[str])#

A class that contains minimal data about a user from the API.

id#

The user’s ID.

Type

int

name#

The user’s name. In most cases, this is provided. There are however, rare cases where it is not.

Type

Optional[str]

coroutine add_channel_moderator(token: str, user_id: int)#

This function is a coroutine.

Adds a moderator to the specified channel/broadcaster. The channel may add a maximum of 10 moderators within a 10 seconds period.

Parameters
  • token (str) – An oauth token with the channel:manage:moderators scope. Must be the broadcaster’s token.

  • user_id (str) – The ID of the user to add as a moderator.

Returns

None

coroutine add_channel_vip(token: str, user_id: int)#

This function is a coroutine.

Adds a VIP to the specified channel/broadcaster. The channel may add a maximum of 10 VIPs within a 10 seconds period.

Parameters
  • token (str) – An oauth token with the channel:manage:vips scope. Must be the broadcaster’s token.

  • user_id (int) – The ID of the user to add as a VIP.

Returns

None

coroutine automod_check(token: str, query: list)#

This function is a coroutine.

Checks if a string passes the automod filter

Parameters
Returns

List[twitchio.AutomodCheckResponse]

coroutine ban_user(token: str, moderator_id: int, user_id, reason: str)#

This function is a coroutine.

Bans a user from the channel/broadcaster.

Parameters
  • token (str) – An oauth user access token with the moderator:manage:banned_users scope

  • moderator_id (int) – The ID of a user that has permission to moderate the broadcaster’s chat room. If the broadcaster wants to ban the user set this parameter to the broadcaster’s ID.

  • user_id (int) – The ID of the user to ban.

  • reason (str) – The reason for the ban.

Returns

twitchio.Ban

coroutine cancel_raid(token: str)#

This function is a coroutine.

Cancels a raid for the channel/broadcaster. The limit is 10 requests within a 10-minute window.

Parameters

token (str) – An oauth token with the channel:manage:raids scope Must be the broadcaster’s token.

Returns

None

coroutine chat_announcement(token: str, moderator_id: int, message: str, color: Optional[str] = None)#

This function is a coroutine.

Sends a chat announcement to the specified channel/broadcaster.

Parameters
  • token (str) – An oauth token with the moderator:manage:chat_settings scope.

  • moderator_id (int) – The ID of a user that has permission to moderate the broadcaster’s chat room. Requires moderator:manage:announcements scope.

  • message (str) – The message to be sent.

  • color (Optional[str]) – The color of the message. Valid values: blue, green orange, purple. The default is primary.

Returns

None

coroutine create_clip(token: str, has_delay=False) dict#

This function is a coroutine.

Creates a clip on the channel. Note that clips are not created instantly, so you will have to query get_clips() to confirm the clip was created. Requires an OAuth token with the clips:edit scope

Parameters
  • token (str) – the OAuth token

  • has_delay (bool) – Whether the clip should have a delay to match that of a viewer. Defaults to False

Returns

dict a dictionary with id and edit_url

coroutine create_custom_reward(token: str, title: str, cost: int, prompt: Optional[str] = None, enabled: Optional[bool] = True, background_color: Optional[str] = None, input_required: Optional[bool] = False, max_per_stream: Optional[int] = None, max_per_user_per_stream: Optional[int] = None, global_cooldown: Optional[int] = None, redemptions_skip_queue: Optional[bool] = False) CustomReward#

This function is a coroutine.

Creates a custom reward for the user.

Parameters
  • token (str) – An oauth token with the channel:manage:redemptions scope

  • title (str) – The title of the reward

  • cost (int) – The cost of the reward

  • prompt (Optional[str]) – The prompt for the reward. Defaults to None

  • enabled (Optional[bool]) – Whether the reward is enabled. Defaults to True

  • background_color (Optional[str]) – The background color of the reward. Defaults to None

  • input_required (Optional[bool]) – Whether the reward requires input. Defaults to False

  • max_per_stream (Optional[int]) – The maximum number of times the reward can be redeemed per stream. Defaults to None

  • max_per_user_per_stream (Optional[int]) – The maximum number of times the reward can be redeemed per user per stream. Defaults to None

  • global_cooldown (Optional[int]) – The global cooldown of the reward. Defaults to None

  • redemptions_skip_queue (Optional[bool]) – Whether the reward skips the queue when redeemed. Defaults to False

coroutine create_marker(token: str, description: Optional[str] = None)#

This function is a coroutine.

Creates a marker on the stream. This only works if the channel is live (among other conditions)

Parameters
  • token (str) – An oauth token with the user:edit:broadcast scope

  • description (str) – An optional description of the marker

Returns

twitchio.Marker

coroutine create_poll(token: str, title: str, choices: List[str], duration: int, bits_voting_enabled: Optional[bool] = False, bits_per_vote: Optional[int] = None, channel_points_voting_enabled: Optional[bool] = False, channel_points_per_vote: Optional[int] = None)#

This function is a coroutine.

Creates a poll for the specified channel/broadcaster.

Parameters
  • token (str) – An oauth token with the channel:manage:polls scope. User ID in token must match the broadcaster’s ID.

  • title (str) – Question displayed for the poll.

  • choices (List[str]) – List of choices for the poll. Must be between 2 and 5 choices.

  • duration (int) – Total duration for the poll in seconds. Must be between 15 and 1800.

  • bits_voting_enabled (Optional[bool]) – Indicates if Bits can be used for voting. Default is False.

  • bits_per_vote (Optional[int]) – Number of Bits required to vote once with Bits. Max 10000.

  • channel_points_voting_enabled (Optional[bool]) – Indicates if Channel Points can be used for voting. Default is False.

  • channel_points_per_vote (Optional[int]) – Number of Channel Points required to vote once with Channel Points. Max 1000000.

Returns

List[twitchio.Poll]

coroutine create_prediction(token: str, title: str, blue_outcome: str, pink_outcome: str, prediction_window: int) Prediction#

This function is a coroutine.

Creates a prediction for the channel.

Parameters
  • token (str) – An oauth token with the channel:manage:predictions scope

  • title (str) – Title for the prediction (max of 45 characters)

  • blue_outcome (str) – Text for the first outcome people can vote for. (max 25 characters)

  • pink_outcome (str) – Text for the second outcome people can vote for. (max 25 characters)

  • prediction_window (int) – Total duration for the prediction (in seconds)

Returns

twitchio.Prediction

coroutine delete_chat_messages(token: str, moderator_id: int, message_id: Optional[str] = None)#

This function is a coroutine.

Deletes a chat message, or clears chat, in the specified channel/broadcaster’s chat.

Parameters
  • token (str) – An oauth token with the moderator:manage:chat_settings scope.

  • moderator_id (int) – The ID of a user that has permission to moderate the broadcaster’s chat room. Requires moderator:manage:chat_messages scope.

  • message_id (Optional[str]) – The ID of the message to be deleted. The message must have been created within the last 6 hours. The message must not belong to the broadcaster. If not specified, the request removes all messages in the broadcaster’s chat room.

Returns

None

coroutine edit(token: str, description: str) None#

This function is a coroutine.

Edits a channels description

Parameters
  • token (str) – An oauth token for the user with the user:edit scope

  • description (str) – The new description for the user

coroutine end_poll(token: str, poll_id: str, status: str)#

This function is a coroutine.

Ends a poll for the specified channel/broadcaster.

Parameters
  • token (str) – An oauth token with the channel:manage:polls scope

  • poll_id (str) – ID of the poll.

  • status (str) – The poll status to be set. Valid values: TERMINATED: End the poll manually, but allow it to be viewed publicly. ARCHIVED: End the poll manually and do not allow it to be viewed publicly.

Returns

twitchio.Poll

coroutine end_prediction(token: str, prediction_id: str, status: str, winning_outcome_id: Optional[str] = None) Prediction#

This function is a coroutine.

End a prediction with an outcome.

Parameters
  • token (str) – An oauth token with the channel:manage:predictions scope

  • prediction_id (str) – ID of the prediction to end.

  • status (str) – Status of the prediction. Valid values are: RESOLVED - Winning outcome has been choson and points distributed. CANCELED - Prediction canceled and points refunded LOCKED - Viewers can no longer make predictions.

  • winning_outcome_id (Optional[str]) – ID of the winning outcome. This is required if status is RESOLVED

Returns

twitchio.Prediction

coroutine fetch(token: Optional[str] = None, force=False) User#

This function is a coroutine.

Fetches the full user from the api or cache

Parameters
  • token (str) – Optional OAuth token to be used instead of the bot-wide OAuth token

  • force (bool) – Whether to force a fetch from the api or try to get from the cache first. Defaults to False

Returns

twitchio.User The full user associated with this PartialUser

coroutine fetch_active_extensions(token: Optional[str] = None)#

This function is a coroutine.

Fetches active extensions the user has. Returns a dictionary containing the following keys: panel, overlay, component.

Parameters

token (Optional[str]) – An oauth token with the user:read:broadcast or user:edit:broadcast scope

Returns

Dict[str, Dict[int, twitchio.ActiveExtension]]

coroutine fetch_ad_schedule(token: str) AdSchedule#

This function is a coroutine.

Fetches the streamers’s ad schedule.

Parameters

token (str) – The user’s oauth token with the channel:read:ads scope.

Returns

twitchio.AdSchedule

coroutine fetch_ban_events(token: str, userids: Optional[List[int]] = None)#

This function is a coroutine.

This has been deprecated and will be removed in a future release.

Fetches ban/unban events from the User’s channel.

Parameters
  • token (str) – The oauth token with the moderation:read scope.

  • userids (List[int]) – An optional list of users to fetch ban/unban events for

Returns

List[twitchio.BanEvent]

coroutine fetch_bans(token: str, userids: Optional[List[Union[str, int]]] = None) List[UserBan]#

This function is a coroutine.

Fetches a list of people the User has banned from their channel.

Parameters
  • token (str) – The oauth token with the moderation:read scope.

  • userids (List[Union[str, int]]) – An optional list of userids to fetch. Will fetch all bans if this is not passed

coroutine fetch_bits_leaderboard(token: str, period: str = 'all', user_id: Optional[int] = None, started_at: Optional[datetime] = None) BitsLeaderboard#

This function is a coroutine.

Fetches the bits leaderboard for the channel. This requires an OAuth token with the bits:read scope.

Parameters
  • token (str) – the OAuth token with the bits:read scope

  • period (Optional[str]) – one of day, week, month, year, or all, defaults to all

  • started_at (Optional[datetime.datetime]) – the timestamp to start the period at. This is ignored if the period is all

  • user_id (Optional[int]) – the id of the user to fetch for

coroutine fetch_channel_emotes()#

This function is a coroutine.

Fetches channel emotes from the user

Returns

List[twitchio.ChannelEmote]

coroutine fetch_channel_follower_count(token: Optional[str] = None) int#

This function is a coroutine.

Fetches the total number of users that are following this user.

Parameters

token (Optional[str]) – An oauth token to use instead of the bots token.

Returns

int

coroutine fetch_channel_followers(token: str, user_id: Optional[int] = None) List[ChannelFollowerEvent]#

This function is a coroutine.

Fetches a list of users that are following this broadcaster. Requires a user access token that includes the moderator:read:followers scope. The ID in the broadcaster_id query parameter must match the user ID in the access token or the user must be a moderator for the specified broadcaster.

Parameters
  • token (str) – User access token that includes the moderator:read:followers scope for the channel.

  • user_id (Optional[int]) – Use this parameter to see whether the user follows this broadcaster.

Returns

List[twitchio.FollowEvent]

coroutine fetch_channel_following(token: str, broadcaster_id: Optional[int] = None) List[ChannelFollowingEvent]#

This function is a coroutine.

Fetches a list of users that this user follows. Requires a user access token that includes the user:read:follows scope. The ID in the broadcaster_id query parameter must match the user ID in the access token or the user must be a moderator for the specified broadcaster.

Parameters
  • token (str) – User access token that includes the moderator:read:follows scope for the channel.

  • broadcaster_id (Optional[int]) – Use this parameter to see whether the user follows this broadcaster.

Returns

List[twitchio.ChannelFollowingEvent]

coroutine fetch_channel_following_count(token: str) int#

This function is a coroutine.

Fetches the total number of users that the user is following.

Parameters

token (str) – Requires a user access token that includes the user:read:follows scope.

Returns

int

coroutine fetch_channel_teams()#

This function is a coroutine.

Fetches a list of Twitch Teams of which the specified channel/broadcaster is a member.

Returns

List[twitchio.ChannelTeams]

coroutine fetch_channel_vips(token: str, first: int = 20, user_ids: Optional[List[int]] = None)#

This function is a coroutine.

Fetches the list of VIPs for the specified channel/broadcaster.

Parameters
  • token (str) – An oauth token with the channel:read:vips or moderator:manage:chat_settings scope. Must be the broadcaster’s token.

  • first (Optional[int]) – The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 100. The default is 20.

  • user_ids (Optional[List[int]]) – A list of user IDs to filter the results by. The maximum number of IDs that you may specify is 100. Ignores those users in the list that aren’t VIPs.

Returns

List[twitchio.PartialUser]

coroutine fetch_charity_campaigns(token: str) List[CharityCampaign]#

This function is a coroutine.

Fetches a list of charity campaigns the broadcaster is running. Requires a user token with the channel:read:charity scope.

Returns

List[twitchio.CharityCampaign]

coroutine fetch_chat_badges()#

This function is a coroutine.

Fetches broadcaster’s list of custom chat badges. The list is empty if the broadcaster hasn’t created custom chat badges.

Returns

List[twitchio.ChatBadge]

coroutine fetch_chat_settings(token: Optional[str] = None, moderator_id: Optional[int] = None)#

This function is a coroutine.

Fetches the current chat settings for this channel/broadcaster.

Parameters
  • token (Optional[str]) – An oauth token with the moderator:read:chat_settings scope. Required if moderator_id is provided.

  • moderator_id (Optional[int]) – The ID of a user that has permission to moderate the broadcaster’s chat room. Requires moderator:read:chat_settings scope.

Returns

twitchio.ChatSettings

coroutine fetch_clips(started_at: Optional[datetime] = None, ended_at: Optional[datetime] = None, is_featured: Optional[bool] = None) List[Clip]#

This function is a coroutine.

Fetches clips from the api. This will only return clips from the specified user. Use Client.fetch_clips to fetch clips by id

Parameters
  • started_at (Optional[datetime.datetime]) – Starting date/time for returned clips. If this is specified, ended_at also should be specified; otherwise, the ended_at date/time will be 1 week after the started_at value.

  • ended_at (Optional[datetime.datetime]) – Ending date/time for returned clips. If this is specified, started_at also must be specified; otherwise, the time period is ignored.

  • is_featured (Optional[bool]) – Optional bool to only return only featured clips or not featured clips.

Returns

List[twitchio.Clip]

coroutine fetch_extensions(token: str)#

This function is a coroutine.

Fetches extensions the user has (active and inactive)

Parameters

token (str) – An oauth token with the user:read:broadcast scope

Returns

List[twitchio.Extension]

coroutine fetch_follow(to_user: PartialUser, token: Optional[str] = None)#

This function is a coroutine.

Check if a user follows another user or when they followed a user.

Warning

The endpoint this method uses has been deprecated by Twitch and is no longer available.

Parameters
  • to_user (PartialUser) –

  • token (Optional[str]) – An oauth token to use instead of the bots token

Returns

twitchio.FollowEvent

coroutine fetch_followed_streams(token: str)#

This function is a coroutine.

Fetches a list of broadcasters that the user follows and that are streaming live.

Parameters

token (str) – An oauth user token with the user:read:follows scope.

Returns

List[twitchio.Stream]

coroutine fetch_follower_count(token: Optional[str] = None) int#

This function is a coroutine.

Fetches the total number of users that are following this user.

Warning

The endpoint this method uses has been deprecated by Twitch and is no longer available.

Parameters

token (Optional[str]) – An oauth token to use instead of the bots token

Returns

int

coroutine fetch_followers(token: Optional[str] = None)#

This function is a coroutine.

Fetches a list of users that are following this user.

Warning

The endpoint this method uses has been deprecated by Twitch and is no longer available.

Parameters

token (Optional[str]) – An oauth token to use instead of the bots token

Returns

List[twitchio.FollowEvent]

coroutine fetch_following(token: Optional[str] = None) List[FollowEvent]#

This function is a coroutine.

Fetches a list of users that this user is following.

Warning

The endpoint this method uses has been deprecated by Twitch and is no longer available.

Parameters

token (Optional[str]) – An oauth token to use instead of the bots token

Returns

List[twitchio.FollowEvent]

coroutine fetch_following_count(token: Optional[str] = None) int#

This function is a coroutine.

Fetches a list of users that this user is following.

Warning

The endpoint this method uses has been deprecated by Twitch and is no longer available.

Parameters

token (Optional[str]) – An oauth token to use instead of the bots token

Returns

int

coroutine fetch_goals(token: str)#

This function is a coroutine.

Fetches a list of goals for the specified channel/broadcaster.

Parameters

token (str) – An oauth token with the channel:read:goals scope

Returns

List[twitchio.Goal]

coroutine fetch_hypetrain_events(id: Optional[str] = None, token: Optional[str] = None)#

This function is a coroutine.

Fetches hypetrain event from the api. Needs a token with the channel:read:hype_train scope.

Parameters
  • id (Optional[str]) – The hypetrain id, if known, to fetch for

  • token (Optional[str]) – The oauth token to use. Will default to the one passed to the bot/client.

Returns

List[twitchio.HypeTrainEvent]

coroutine fetch_markers(token: str, video_id: Optional[str] = None)#

This function is a coroutine.

Fetches markers from the given video id, or the most recent video. The Twitch api will only return markers created by the user of the authorized token

Parameters
  • token (str) – An oauth token with the user:edit:broadcast scope

  • video_id (str) – A specific video o fetch from. Defaults to the most recent stream if not passed

Returns

Optional[twitchio.VideoMarkers]

coroutine fetch_mod_events(token: str)#

This function is a coroutine.

Fetches mod events (moderators being added and removed) for this channel.

Parameters

token (str) – The oauth token with the moderation:read scope.

Returns

List[twitchio.ModEvent]

coroutine fetch_moderated_channels(token: str) List[PartialUser]#

This function is a coroutine.

Fetches channels that this user moderates.

Parameters

token (str) – An oauth token for this user with the user:read:moderated_channels scope.

Returns

List[twitchio.PartialUser]

coroutine fetch_moderators(token: str, userids: Optional[List[int]] = None)#

This function is a coroutine.

Fetches the moderators for this channel.

Parameters
  • token (str) – The oauth token with the moderation:read scope.

  • userids (List[int]) – An optional list of users to check mod status of

Returns

List[twitchio.PartialUser]

coroutine fetch_polls(token: str, poll_ids: Optional[List[str]] = None, first: Optional[int] = 20)#

This function is a coroutine.

Fetches a list of polls for the specified channel/broadcaster.

Parameters
  • token (str) – An oauth token with the channel:read:polls scope

  • poll_ids (Optional[List[str]]) – List of poll IDs to return. Maximum: 100

  • first (Optional[int]) – Number of polls to return. Maximum: 20. Default: 20.

Returns

List[twitchio.Poll]

coroutine fetch_schedule(segment_ids: Optional[List[str]] = None, start_time: Optional[datetime] = None, utc_offset: Optional[int] = None, first: int = 20)#

This function is a coroutine.

Fetches the schedule of a streamer :param segment_ids: List of segment IDs of the stream schedule to return. Maximum: 100 :type segment_ids: Optional[List[str]] :param start_time: A datetime object to start returning stream segments from. If not specified, the current date and time is used. :type start_time: Optional[datetime.datetime] :param utc_offset: A timezone offset for the requester specified in minutes. +4 hours from GMT would be 240 :type utc_offset: Optional[int] :param first: Maximum number of stream segments to return. Maximum: 25. Default: 20. :type first: Optional[int]

Returns

twitchio.Schedule

coroutine fetch_shield_mode_status(token: str, moderator_id: int)#

This function is a coroutine.

Fetches the user’s Shield Mode activation status.

Parameters
  • token (str) – An oauth user token with the moderator:read:shield_mode or moderator:manage:shield_mode scope.

  • moderator_id (int) – The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Returns

twitchio.ShieldStatus

coroutine fetch_stream_key(token: str)#

This function is a coroutine.

Fetches the users stream key

Parameters

token (str) – The oauth token with the channel:read:stream_key scope

Returns

str

coroutine fetch_subscriptions(token: str, userids: Optional[List[int]] = None)#

This function is a coroutine.

Fetches the subscriptions for this channel.

Parameters
  • token (str) – An oauth token with the channel:read:subscriptions scope

  • userids (Optional[List[int]]) – An optional list of userids to look for

Returns

List[twitchio.SubscriptionEvent]

coroutine fetch_tags()#

This function is a coroutine.

Fetches tags the user currently has active.

Returns

List[twitchio.Tag]

coroutine fetch_user_emotes(token: str, broadcaster: Optional[PartialUser] = None) List[Emote]#

This function is a coroutine.

Fetches emotes the user has access to. Optionally, you can filter by a broadcaster.

Note

As of writing, this endpoint seems extrememly unoptimized by twitch, and may (read: will) take a lot of API requests to load. See https://github.com/twitchdev/issues/issues/921 .

Parameters
  • token (str) – An OAuth token belonging to this user with the user:read:emotes scope.

  • broadcaster (Optional[PartialUser]) – A channel to filter the results with. Filtering will return all emotes available to the user on that channel, including global emotes.

Returns

List[Emote]

coroutine fetch_videos(period='all', sort='time', type='all', language=None)#

This function is a coroutine.

Fetches videos that belong to the user. If you have specific video ids use Client.fetch_videos()

Parameters
  • period (str) – The period for which to fetch videos. Valid values are all, day, week, month. Defaults to all

  • sort (str) – Sort orders of the videos. Valid values are time, trending, views, Defaults to time

  • type (Optional[str]) – Type of the videos to fetch. Valid values are upload, archive, highlight. Defaults to all

  • language (Optional[str]) – Language of the videos to fetch. Must be an ISO-639-1 two letter code.

Returns

List[twitchio.Video]

coroutine follow(userid: int, token: str, *, notifications=False)#

This function is a coroutine.

Follows the user

Warning

This method is obsolete as Twitch removed the endpoint.

Parameters
  • userid (int) – The user id to follow this user with

  • token (str) – An oauth token with the user:edit:follows scope

  • notifications (bool) – Whether to allow push notifications when this user goes live. Defaults to False

coroutine get_custom_rewards(token: str, *, only_manageable=False, ids: Optional[List[int]] = None, force=False) List[CustomReward]#

This function is a coroutine.

Fetches the channels custom rewards (aka channel points) from the api.

Parameters
  • token (str) – The users oauth token.

  • only_manageable (bool) – Whether to fetch all rewards or only ones you can manage. Defaults to false.

  • ids (List[int]) – An optional list of reward ids

  • force (bool) – Whether to force a fetch or try to get from cache. Defaults to False

Returns

List[twitchio.CustomReward]

coroutine get_predictions(token: str, prediction_id: Optional[str] = None) List[Prediction]#

This function is a coroutine.

Gets information on a prediction or the list of predictions if none is provided.

Parameters
  • token (str) – An oauth token with the channel:manage:predictions scope

  • prediction_id (str) – ID of the prediction to receive information about.

Returns

twitchio.Prediction

coroutine modify_stream(token: str, game_id: Optional[int] = None, language: Optional[str] = None, title: Optional[str] = None, content_classification_labels: Optional[List[Dict[str, Union[str, bool]]]] = None, is_branded_content: Optional[bool] = None)#

This function is a coroutine.

Modify stream information

Parameters
  • token (str) – An oauth token with the channel:manage:broadcast scope

  • game_id (int) – Optional game ID being played on the channel. Use 0 to unset the game.

  • language (str) – Optional language of the channel. A language value must be either the ISO 639-1 two-letter code for a supported stream language or “other”.

  • title (str) – Optional title of the stream.

  • content_classification_labels (List[Dict[str, Union[str, bool]]]) – List of labels that should be set as the Channel’s CCLs.

  • is_branded_content (bool) –

    Boolean flag indicating if the channel has branded content.

    Note

    Example of a content classification labels .. code:: py

    ccl = [{“id”: “Gambling”, “is_enabled”: False}, {“id”: “DrugsIntoxication”, “is_enabled”: False}] await my_partial_user.modify_stream(token=”abcd”, content_classification_labels=ccl)

coroutine remove_channel_moderator(token: str, user_id: int)#

This function is a coroutine.

Removes a moderator from the specified channel/broadcaster. The channel may remove a maximum of 10 moderators within a 10 seconds period.

Parameters
  • token (str) – An oauth token with the channel:manage:moderators scope. Must be the broadcaster’s token.

  • user_id (str) – The ID of the user to remove as a moderator.

Returns

None

coroutine remove_channel_vip(token: str, user_id: int)#

This function is a coroutine.

Removes a VIP from the specified channel/broadcaster. The channel may remove a maximum of 10 vips within a 10 seconds period.

Parameters
  • token (str) – An oauth token with the channel:manage:vips scope. Must be the broadcaster’s token.

  • user_id (int) – The ID of the user to remove as a VIP.

Returns

None

coroutine replace_tags(token: str, tags: List[Union[str, Tag]])#

This function is a coroutine.

Replaces the channels active tags. Tags expire 72 hours after being applied, unless the stream is live during that time period.

Parameters
  • token (str) – An oauth token with the user:edit:broadcast scope

  • tags (List[Union[twitchio.Tag, str]]) – A list of twitchio.Tag or tag ids to put on the channel. Max 100

coroutine send_whisper(token: str, user_id: int, message: str)#

This function is a coroutine.

Sends a whisper to a user. Important Notes: - The user sending the whisper must have a verified phone number. - The API may silently drop whispers that it suspects of violating Twitch policies. - You may whisper to a maximum of 40 unique recipients per day. Within the per day limit. - You may whisper a maximum of 3 whispers per second and a maximum of 100 whispers per minute.

Parameters
  • token (str) – An oauth user token with the user:manage:whispers scope.

  • user_id (int) – The ID of the user to send the whisper to.

  • message (str) – The message to send. 500 characters if the user you’re sending the message to hasn’t whispered you before. 10,000 characters if the user you’re sending the message to has whispered you before.

Returns

None

coroutine shoutout(token: str, to_broadcaster_id: int, moderator_id: int)#

This function is a coroutine. Sends a Shoutout to the specified broadcaster. Rate Limits: The broadcaster may send a Shoutout once every 2 minutes. They may send the same broadcaster a Shoutout once every 60 minutes. Requires a user access token that includes the moderator:manage:shoutouts scope.

Parameters
  • token (str) – An oauth user token with the moderator:manage:shoutouts scope.

  • to_broadcaster (int) – The ID of the broadcaster that is recieving the shoutout.

  • moderator_id (int) – The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

Returns

None

coroutine snooze_ad(token: str) List[AdSchedule]#

This function is a coroutine.

Snoozes an ad on the streamer’s channel.

Note

The resulting AdSchedule only has data for the snooze_count, snooze_refresh_at, and next_ad_at attributes.

Parameters

token (str) – The user’s oauth token with the channel:manage:ads scope.

Returns

twitchio.AdSchedule

coroutine start_commercial(token: str, length: int) dict#

This function is a coroutine.

Starts a commercial on the channel. Requires an OAuth token with the channel:edit:commercial scope.

Parameters
  • token (str) – the OAuth token

  • length (int) – the length of the commercial. Should be one of 30, 60, 90, 120, 150, 180

Returns

dict a dictionary with length, message, and retry_after

coroutine start_raid(token: str, to_broadcaster_id: int)#

This function is a coroutine.

Starts a raid for the channel/broadcaster. The UTC date and time, in RFC3339 format, when the raid request was created. A Boolean value that indicates whether the channel being raided contains mature content.

Rate Limit: The limit is 10 requests within a 10-minute window.

Parameters
  • token (str) – An oauth token with the channel:manage:raids scope Must be the broadcaster’s token.

  • to_broadcaster_id (int) – The ID of the broadcaster to raid.

Returns

twitchio.Raid

coroutine timeout_user(token: str, moderator_id: int, user_id: int, duration: int, reason: str)#

This function is a coroutine.

Timeouts a user from the channel/broadcaster.

Parameters
  • token (str) – An oauth user access token with the moderator:manage:banned_users scope

  • moderator_id (int) – The ID of a user that has permission to moderate the broadcaster’s chat room. If the broadcaster wants to timeout the user set this parameter to the broadcaster’s ID.

  • user_id (int) – The ID of the user that you wish to timeout.

  • duration (int) – The duration of the timeout in seconds. The minimum timeout is 1 second and the maximum is 1,209,600 seconds (2 weeks). To end a user’s timeout early, set this field to 1, or send an Unban user request.

  • reason (str) – The reason for the timeout.

Returns

twitchio.Timeout

coroutine unban_user(token: str, moderator_id: int, user_id)#

This function is a coroutine.

Unbans a user or removes a timeout from the channel/broadcaster.

Parameters
  • token (str) – An oauth user access token with the moderator:manage:banned_users scope

  • moderator_id (int) – The ID of a user that has permission to moderate the broadcaster’s chat room. If the broadcaster wants to ban the user set this parameter to the broadcaster’s ID.

  • user_id (int) – The ID of the user to unban.

Returns

None

coroutine unfollow(userid: int, token: str)#

This function is a coroutine.

Unfollows the user

Warning

This method is obsolete as Twitch removed the endpoint.

Parameters
  • userid (int) – The user id to unfollow this user with

  • token (str) – An oauth token with the user:edit:follows scope

coroutine update_chat_settings(token: str, moderator_id: int, emote_mode: Optional[bool] = None, follower_mode: Optional[bool] = None, follower_mode_duration: Optional[int] = None, slow_mode: Optional[bool] = None, slow_mode_wait_time: Optional[int] = None, subscriber_mode: Optional[bool] = None, unique_chat_mode: Optional[bool] = None, non_moderator_chat_delay: Optional[bool] = None, non_moderator_chat_delay_duration: Optional[int] = None)#

This function is a coroutine.

Updates the current chat settings for this channel/broadcaster.

Parameters
  • token (str) – An oauth token with the moderator:manage:chat_settings scope.

  • moderator_id (int) – The ID of a user that has permission to moderate the broadcaster’s chat room. Requires moderator:manage:chat_settings scope.

  • emote_mode (Optional[bool]) – A boolean to determine whether chat must contain only emotes or not.

  • follower_mode (Optional[bool]) – A boolean to determine whether chat must contain only emotes or not.

  • follower_mode_duration (Optional[int]) – The length of time, in minutes, that the followers must have followed the broadcaster to participate in chat. Values: 0 (no restriction) through 129600 (3 months). The default is 0.

  • slow_mode (Optional[bool]) – A boolean to determine whether the broadcaster limits how often users in the chat room are allowed to send messages.

  • slow_mode_wait_time (Optional[int]) – The amount of time, in seconds, that users need to wait between sending messages. Values: 3 through 120 (2 minute delay). The default is 30 seconds.

  • subscriber_mode (Optional[bool]) – A boolean to determine whether only users that subscribe to the broadcaster’s channel can talk in chat.

  • unique_chat_mode (Optional[bool]) – A boolean to determine whether the broadcaster requires users to post only unique messages in chat.

  • non_moderator_chat_delay (Optional[bool]) – A boolean to determine whether the broadcaster adds a short delay before chat messages appear in chat.

  • non_moderator_chat_delay_duration (Optional[int]) – The amount of time, in seconds, that messages are delayed from appearing in chat. Valid values: 2, 4 and 6.

Returns

twitchio.ChatSettings

coroutine update_extensions(token: str, extensions: ExtensionBuilder)#

This function is a coroutine.

Updates a users extensions. See the twitchio.ExtensionBuilder

Parameters
Returns

Dict[str, Dict[int, twitchio.ActiveExtension]]

coroutine update_shield_mode_status(token: str, moderator_id: int, is_active: bool)#

This function is a coroutine.

Updates the user’s Shield Mode activation status.

Parameters
  • token (str) – An oauth user token with the moderator:read:shield_mode or moderator:manage:shield_mode scope.

  • moderator_id (int) – The ID of the broadcaster or a user that is one of the broadcaster’s moderators. This ID must match the user ID in the access token.

  • is_active (bool) – A Boolean value that determines whether to activate Shield Mode. Set to True to activate Shield Mode; otherwise, False to deactivate Shield Mode.

Returns

twitchio.ShieldStatus

property channel: Optional[Channel]#

Returns the twitchio.Channel associated with this user. Could be None if you are not part of the channel’s chat

Returns

Optional[twitchio.Channel]

class twitchio.User(http: TwitchHTTP, data: dict)#

A full user object, containing data from the users endpoint.

id#

The user’s ID

Type

int

name#

The user’s login name

Type

str

display_name#

The name that is displayed in twitch chat. For the most part, this is simply a change of capitalization

Type

str

type#

The user’s type. This will normally be none, unless they are twitch staff or admin

Type

UserTypeEnum

broadcaster_type#

What type of broacaster the user is. none, affiliate, or partner

Type

BroadcasterTypeEnum

description#

The user’s bio

Type

str

profile_image#

The user’s profile image URL

Type

str

offline_image#

The user’s offline image splash URL

Type

str

view_count#

The amount of views this channel has

Warning

This field has been deprecated by twitch, and is no longer updated. See here for more information.

Note

This field is a tuple due to a mistake when creating the models. Due to semver principals, this cannot be fixed until version 3.0 (at which time we will be removing the field entirely).

Type

Tuple[int]

created_at#

When the user created their account

Type

datetime.datetime

email#

The user’s email. This is only returned if you have the user:read:email scope on the token used to make the request

Type

Optional[class:str]

UserBan#

class twitchio.UserBan(http: TwitchHTTP, data: dict)#

Represents a banned user or one in timeout.

id#

The ID of the banned user.

Type

int

name#

The name of the banned user.

Type

str

created_at#

The date and time the ban was created.

Type

datetime.datetime

expires_at#

The date and time the timeout will expire. Is None if it’s a ban.

Type

Optional[datetime.datetime]

reason#

The reason for the ban/timeout.

Type

str

moderator#

The moderator that banned the user.

Type

PartialUser

Video#

class twitchio.Video(http: TwitchHTTP, data: dict, user: Optional[Union[PartialUser, User]] = None)#

Represents video information

id#

The ID of the video.

Type

int

user#

User who owns the video.

Type

PartialUser

title#

Title of the video

Type

str

description#

Description of the video.

Type

str

created_at#

Date when the video was created.

Type

datetime.datetime

published_at#

Date when the video was published.

Type

datetime.datetime

url#

URL of the video.

Type

str

thumbnail_url#

Template URL for the thumbnail of the video.

Type

str

viewable#

Indicates whether the video is public or private.

Type

str

view_count#

Number of times the video has been viewed.

Type

int

language#

Language of the video.

Type

str

type#

The type of video.

Type

str

duration#

Length of the video.

Type

str

coroutine delete(token: str)#

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

VideoMarkers#

Attributes
class twitchio.VideoMarkers(data: dict)#

Represents markers contained in a video

id#

The video id.

Type

str

markers#

The markers contained in the video.

Type

List[Marker]

WebhookSubscription#

class twitchio.WebhookSubscription(data: dict)#