Helix

class twitchio.CommercialStart(data: StartCommercialResponseData)

Represents a Commercial starting.

length

The length of the commercial you requested. If you request a commercial that’s longer than 180 seconds, the API uses 180 seconds.

Type

int

message

A message that indicates whether Twitch was able to serve an ad.

Type

str

retry_after

The number of seconds you must wait before running another commercial.

Type

int

class twitchio.AdSchedule(data: AdScheduleResponseData)

Represents ad schedule information.

snooze_count

The number of snoozes available for the broadcaster.

Type

int

snooze_refresh_at

The UTC datetime when the broadcaster will gain an additional snooze.

Type

datetime.datetime

duration

The length in seconds of the scheduled upcoming ad break.

Type

int

next_ad_at

The UTC datetime of the broadcaster’s next scheduled ad format. None if channel has no ad scheduled.

Type

datetime.datetime | None

last_ad_at

The UTC datetime of the broadcaster’s last ad-break. None if channel has not run an ad or is not live.

Type

datetime.datetime | None

preroll_free_time

The amount of pre-roll free time remaining for the channel in seconds. Returns 0 if they are currently not pre-roll free.

Type

int

class twitchio.SnoozeAd(data: SnoozeNextAdResponseData)

Represents ad schedule information.

snooze_count

The number of snoozes available for the broadcaster.

Type

int

snooze_refresh_at

The UTC datetime when the broadcaster will gain an additional snooze.

Type

datetime.datetime

next_ad_at

The UTC datetime of the broadcaster’s next scheduled ad. None if channel has no ad scheduled.

Type

datetime.datetime | None

class twitchio.ExtensionAnalytics(data: ExtensionAnalyticsResponseData)

Represents Extension Analytics.

id

An ID that identifies the extension that the report was generated for.

Type

str

url

The URL to download the report.

Type

str

type

The type of report.

Type

str

started_at

The start date of the reporting window.

Type

datetime.datetime

ended_at

The end date of the reporting window.

Type

datetime.datetime

class twitchio.GameAnalytics(data: GameAnalyticsResponseData)

Represents Game Analytics.

id

An ID that identifies the game that the report was generated for.

Type

str

url

The URL to download the report.

Type

str

type

The type of report.

Type

str

started_at

The start date of the reporting window.

Type

datetime.datetime

ended_at

The end date of the reporting window.

Type

datetime.datetime

class twitchio.BitsLeaderboard(data: BitsLeaderboardResponse, *, http: HTTPClient)

Represents a Bits leaderboard.

started_at

The time the leaderboard started.

Type

datetime.datetime | None

ended_at

The time the leaderboard ended.

Type

datetime.datetime | None

leaders

The current leaders of the Leaderboard.

Type

list[BitLeaderboardUser]

Attributes
class twitchio.BitLeaderboardUser(data: BitsLeaderboardResponseData, *, http: HTTPClient)

A user’s details within the Bit Leaderboard.

user

The user.

Type

PartialUser

rank

The user’s position on the leaderboard.

Type

int

score

The number of Bits the user has cheered.

Type

int

class twitchio.Cheermote(data: CheermotesResponseData, *, http: HTTPClient)

Represents a Cheermote

Type

Description

global_first_party

A Twitch-defined Cheermote that is shown in the Bits card.

global_third_party

A Twitch-defined Cheermote that is not shown in the Bits card.

channel_custom

A broadcaster-defined Cheermote.

display_only

Do not use; for internal use only.

sponsored

A sponsor-defined Cheermote. When used, the sponsor adds additional Bits to the amount that the user cheered. For example, if the user cheered Terminator100, the broadcaster might receive 110 Bits, which includes the sponsor’s 10 Bits contribution.

prefix

The string used to Cheer that precedes the Bits amount.

Type

str

tiers

The tiers this Cheermote has

Type

CheermoteTier

type

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

Type

str

order

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

Type

int

last_updated datetime.datetime

The date this cheermote was last updated.

charitable

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

Type

bool

class twitchio.CheermoteTier(data: CheermotesResponseTiers, *, http: HTTPClient)

Represents a Cheermote 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. There is an alias named color.

Type

Colour

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. cheermotetier.images["light"]["animated"]["1"]

Type

dict[str, dict[str, dict[str, str]]]

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

bool

get_image(*, theme: Literal['light', 'dark'] = 'light', scale: Literal['1', '1.5', '2', '3', '4'] = '2', format: Literal['default', 'static', 'animated'] = 'default') twitchio.assets.Asset | None

Creates an Asset for the cheermote, which can be used to download/save the cheermote image.

Parameters
  • theme (Literal["light", "dark"]) – The background theme of the cheermote. Defaults to “light”.

  • scale (str) – The scale (size) of the cheermote. Usually this will be one of: “1”, “1.5”, “2”, “3”, “4” Defaults to “2”.

  • format (Literal["default", "static", "animated"]) –

    The format of the image for the cheermote. E.g a static image (PNG) or animated (GIF).

    Use “default” to get the default format for the emote, which will be animated if available, otherwise static. Defaults to “default”.

Examples

cheermotes: list[twitchio.Cheermote] = await client.fetch_cheermotes()
cheermote: twitchio.Cheermote = cheermotes[0]

# Get and save the emote asset as an image
asset: twitchio.Asset = await cheeremote.tiers[0].get_image()
await asset.save()
Returns

The Asset for the cheermote. You can use the asset to read() or save() the cheermote image or return the generated URL with url.

Return type

Asset | None

class twitchio.ExtensionTransaction(data: ExtensionTransactionsResponseData, *, http: HTTPClient)

Represents an Extension Transaction.

id

An ID that identifies the transaction.

Type

str

timestamp

The UTC date and time of the transaction.

Type

datetime.datetime

broadcaster

The broadcaster that owns the channel where the transaction occurred.

Type

PartialUser

user

The user that purchased the digital product.

Type

PartialUser

product_type

The type of transaction. Currently only BITS_IN_EXTENSION

Type

str

product_data

Details about the digital product.

Type

ExtensionProductData

class twitchio.ExtensionProductData(data: ExtensionTransactionsResponseProductData)

Represents Product Data of an Extension Transaction.

domain

Set to twitch.ext. + <the extension’s ID>.

Type

str

sku

An ID that identifies the digital product.

Type

str

cost

Contains details about the digital product’s cost.

Type

ExtensionCost

in_development

Whether the product is in development.

Type

bool

display_name

The name of the digital product.

Type

str

expiration

This field is always empty since you may purchase only unexpired products.

Type

str

broadcast

Whether the data was broadcast to all instances of the extension.

Type

bool

Attributes
class twitchio.ExtensionCost(data: ExtensionTransactionsResponseCost)

Represents Cost of an Extension Transaction.

amount

The amount exchanged for the digital product.

Type

int

type

The type of currency exchanged. Currently only bits

Type

str

Attributes
class twitchio.ContentClassificationLabel(data: ContentClassificationLabelData)

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

Attributes
class twitchio.RewardCooldown(enabled: bool, seconds: int)

NamedTuple that represents a custom reward’s cooldown settings.

enabled

Whether a coooldown between redemptions is enabled or not. Default is False.

Type

bool

seconds

The cooldown period in seconds. This only applies if is_enabled is True. Min value is 1; however, the minimum value is 60 for it to be shown in the Twitch UX.

Type

int

Attributes
class twitchio.RewardLimitSettings(enabled: bool, value: int)

NamedTuple that represents a custom reward’s stream limit settings.

enabled

Whether the stream setting is enabled or not.

Type

bool

value

The max number of redemptions allowed. Minimum value is 1.

Type

int

class twitchio.CustomReward(data: CustomRewardsResponseData, *, http: HTTPClient)

Represents a custom reward from a broadcaster’s channel.

broadcaster

The broadcaster that owns the CustomReward.

Type

PartialUser

id

The ID that uniquely identifies this custom reward.

Type

str

title

The title of the reward.

Type

str

prompt

The prompt shown to the viewer when they redeem the reward if user input is required.

Type

str

cost

The cost of the reward in Channel Points.

Type

int

default_image

A dictionary of default images for the reward. The keys are as follows: url_1x, url_2x and url_4x.

Type

dict[str, str]

colour

The background colour to use for the reward. There is an alias named color.

Type

Colour

enabled

A Boolean value that determines whether the reward is enabled. Is True if enabled; otherwise, False. Disabled rewards aren’t shown to the user.

Type

bool

input_required

A Boolean value that determines whether the user must enter information when redeeming the reward. Is True if the reward requires user input.

Type

bool

paused

A Boolean value that determines whether the reward is currently paused. Is True if the reward is paused. Viewers can’t redeem paused rewards.

Type

bool

in_stock

A Boolean value that determines whether the reward is currently in stock. Is True if the reward is in stock. Viewers can’t redeem out of stock rewards.

Type

bool

image

A dictionary of custom images for the reward. This will return None if the broadcaster did not upload any images. The keys, if available, are as follows: url_1x, url_2x and url_4x.

Type

dict[str, str] | None

skip_queue

A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If False, status is set to UNFULFILLED and follows the normal request queue process. The default is False.

Type

bool

current_stream_redeems

The number of redemptions redeemed during the current live stream. The number counts against the max_per_stream.max_value limit. This is None if the broadcaster’s stream isn’t live or max_per_stream_setting isn’t enabled.

Type

int | None

cooldown_until

The datetime of when the cooldown period expires. Is null if the reward isn’t in a cooldown state

Type

datetime.datetime | None

cooldown

The cooldown settings of a reward. This represents whether reward has a cooldown enabled and the cooldown period in seconds.

Type

RewardCooldown

max_per_stream

The settings of a reward over a live stream. This represents whether a reward has a max number of redemptions per stream and if the setting is enabled or not.

Type

RewardLimitSettings

max_per_user_stream

The settings of a reward over a live stream per user. This represents whether a reward has a max number of redemptions per user per stream and if the setting is enabled or not.

Type

RewardLimitSettings

get_image(size: Literal['1x', '2x', '4x'] = '2x', use_default: bool = False) Asset

Get an image Asset for the reward at a specified size.

Falls back to default images if no custom images have been uploaded.

Parameters
  • size (str) – The size key of the image. Options are “1x”, “2x”, “4x”. Defaults to “2x”.

  • use_default (bool) – Use default images instead of user uploaded images.

Returns

The Asset for the image. Falls back to default images if no custom images have been uploaded.

Return type

Asset

async delete() None

This function is a coroutine.

Delete the custom reward.

The app / client ID used to create the reward is the only app that may delete it. If the reward’s redemption status is UNFULFILLED at the time the reward is deleted, its redemption status is marked as FULFILLED.

Note

Requires a user access token that includes the channel:manage:redemptions scope.

async update(*, title: str | None = None, cost: int | None = None, prompt: str | None = None, enabled: bool | None = None, colour: str | twitchio.utils.Colour | None = None, input_required: bool | None = None, max_per_stream: int | None = None, max_per_user: int | None = None, global_cooldown: int | None = None, paused: bool | None = None, skip_queue: bool | None = None) CustomReward

This function is a coroutine.

Update the custom reward.

Important

The app / client ID used to create the reward is the only app that may update the reward.

Note

Requires a user access token that includes the channel:manage:redemptions scope.

Parameters
  • title (str | None) – The reward’s title. The title may contain a maximum of 45 characters and it must be unique amongst all of the broadcaster’s custom rewards.

  • cost (int | None) – The cost of the reward, in channel points. The minimum is 1 point.

  • prompt (str | None) – The prompt shown to the viewer when they redeem the reward. input_required needs to be set to True for this to work,

  • enabled (bool | None) – Boolean value that indicates whether the reward is enabled. Set to True to enable the reward. Viewers see only enabled rewards.

  • colour (str | Colour | None) – The background colour to use for the reward. Specify the color using Hex format (for example, #00E5CB). You can also pass a twitchio.Colour object.

  • input_required (bool | None) – A Boolean value that determines whether users must enter information to redeem the reward.

  • max_per_stream (int | None) – The maximum number of redemptions allowed per live stream. Setting this to 0 disables the maximum number of redemptions per stream.

  • max_per_user (int | None) – The maximum number of redemptions allowed per user per live stream. Setting this to 0 disables the maximum number of redemptions per user per stream.

  • global_cooldown (int | None) – The cooldown period, in seconds. The minimum value is 1; however, for it to be shown in the Twitch UX, the minimum value is 60. Setting this to 0 disables the global cooldown period.

  • paused (bool | None) – A Boolean value that determines whether to pause the reward. Set to True to pause the reward. Viewers can’t redeem paused rewards.

  • skip_queue (bool | None) – A Boolean value that determines whether redemptions should be set to FULFILLED status immediately when a reward is redeemed. If False, status is set to UNFULFILLED and follows the normal request queue process.

Return type

CustomReward

Raises
  • ValueError – title must be a maximum of 45 characters.

  • ValueError – prompt must be a maximum of 200 characters.

  • ValueError – Minimum value must be at least 1.

await .fetch_redemptions(...) -> list[T]
async for item in .fetch_redemptions(...):

async
fetch_redemptions(*, status: Literal['CANCELED', 'FULFILLED', 'UNFULFILLED'], ids: list[str] | None = None, sort: Literal['OLDEST', 'NEWEST'] = 'OLDEST', first: int = 20) HTTPAsyncIterator[CustomRewardRedemption]

This function returns a HTTPAsyncIterator

Fetch redemptions from the CustomReward.

Canceled and fulfilled redemptions are returned for only a few days after they’re canceled or fulfilled.

Note

Requires a user access token that includes the channel:read:redemptions or channel:manage:redemptions scope.

Parameters
  • status (Literal["CANCELED", "FULFILLED", "UNFULFILLED"]) – The state of the redemption. This can be one of the following: “CANCELED”, “FULFILLED”, “UNFULFILLED”

  • ids (list[str] | None) – A list of IDs to filter the redemptions by. You may specify up to 50.

  • sort (Literal["OLDEST", "NEWEST"]) – The order to sort the redemptions by. The default is OLDEST.

  • first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 50.

Return type

HTTPAsyncIterator[CustomRewardRedemption]

Raises

ValueError – You may only specify up to 50 redemption ids.

Methods
class twitchio.CustomRewardRedemption(data: CustomRewardRedemptionResponseData, parent_reward: CustomReward, http: HTTPClient)

Represents a custom reward redemption.

id

The ID that uniquely identifies this redemption.

Type

str

status

The state of the redemption. This can be one of the following: “CANCELED”, “FULFILLED”, “UNFULFILLED”

Type

Literal[“CANCELED”, “FULFILLED”, “UNFULFILLED”]

redeemed_at

The prompt shown to the viewer when they redeem the reward if user input is required.

Type

datetime.datetime

reward

This is the reward that the redemption is from.

Type

CustomReward

user

The user that made the redemption.

Type

PartialUser

async fulfill() CustomRewardRedemption

This function is a coroutine.

Updates a redemption’s status to FULFILLED.

Note

Requires a user access token that includes the channel:manage:redemptions scope.

Return type

CustomRewardRedemption

async refund() CustomRewardRedemption

This function is a coroutine.

Updates a redemption’s status to CANCELED.

Note

Requires a user access token that includes the channel:manage:redemptions scope.

Return type

CustomRewardRedemption

Attributes
class twitchio.ChannelEditor(data: ChannelEditorsResponseData, *, http: HTTPClient)

Represents an editor of a channel.

user

PartialUser who has editor permissions.

Type

PartialUser

created_at

The datetime of when the user became one of the broadcaster’s editors.

Type

datetime.datetime

class twitchio.FollowedChannelsEvent(data: FollowedChannelsResponseData, *, http: HTTPClient)

Represents a followed channel event.

broadcaster

PartialUser that identifies the channel that this user is following. If no results are found it returns an empty list.

Type

PartialUser

followed_at

The datetime of when the user followed the channel.

Type

datetime.datetime

Attributes
class twitchio.FollowedChannels(data: FollowedChannelsResponse, iterator: HTTPAsyncIterator[FollowedChannelsEvent])

Represents channels followed.

followed

HTTPAsyncIterator of PartialUsers that identifies channel’s this user follows. If no results are found it returns an empty list.

Type

HTTPAsyncIterator[FollowedChannelsEvent]

total

The total number of users that follow this broadcaster.

Type

int

Attributes
class twitchio.ChannelFollowerEvent(data: ChannelFollowersResponseData, *, http: HTTPClient)

Represents a ChannelFollowerEvent

user

PartialUser that identifies a user that follows this channel.

Type

PartialUser

followed_at

The datetime of when the user followed the channel.

Type

datetime.datetime

Attributes
class twitchio.ChannelFollowers(data: ChannelFollowersResponse, iterator: HTTPAsyncIterator[ChannelFollowerEvent])

Represents channel followers

followers

PartialUser that identifies a user that follows this channel.

Type

HTTPAsyncIterator[ChannelFollowerEvent]

total

The total number of users that follow this broadcaster.

Type

int

class twitchio.ChannelInfo(data: ChannelInformationResponseData, *, http: HTTPClient)

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]

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

async fetch_game() Game

This function is a coroutine.

Fetches the :class:~twitchio.Game` associated with this ChannelInfo.

Returns

The game associated with this ChannelInfo.

Return type

Game

class twitchio.CharityCampaign(data: CharityCampaignResponseData, *, http: HTTPClient)

Represents a charity campaign.

id

An ID that identifies the charity campaign.

Type

str

broadcaster

The broadcaster that’s running the campaign.

Type

PartialUser

name

The charity’s name.

Type

str

description

A description of the charity.

Type

str

A logo for the charity campaign that is of size 100px X 100px.

Type

Asset

website

A URL to the charity’s website.

Type

str

current_amount

The current amount of donations that the campaign has received.

Type

CharityValues

target_amount

The campaign’s fundraising goal. This is None if the broadcaster has not defined a fundraising goal.

Type

CharityValues | None

class twitchio.CharityValues(data: CharityCampaignResponseCurrentAmount | CharityCampaignResponseTargetAmount | CharityCampaignDonationsResponseAmount | ChatCharityAmountData)

Represents the current/target funds of a charity campaign.

value

The monetary amount. The amount is specified in the currency’s minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550.

Type

int

decimal_places

The number of decimal places used by the currency.

Type

int

currency

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

Type

str

property decimal_value: str

Returns the value in decimal format with 2 decimal places.

Attributes
class twitchio.CharityDonation(data: CharityCampaignDonationsResponseData, *, http: HTTPClient)

Represents a charity campaign donation.

id

An ID that identifies the donation. The ID is unique across campaigns.

Type

str

user

The user who donated money to the campaign.

Type

PartialUser

campaign_id

The ID of the charity campaign that the donation applies to.

Type

str

amount

The the amount of money that the user donated.

Type

str

class twitchio.Chatters(iterator: HTTPAsyncIterator[PartialUser], data: ChattersResponse)

Represents a channel’s chatters.

Returns

  • users (HTTPAsyncIterator[PartialUser]) – The PartialUser object of the chatter.

  • total (int) – The the total number of users that are connected to the chat room. This may vary as you iterate through pages.

Attributes
class twitchio.ChatterColor(data: UserChatColorResponseData, *, http: HTTPClient)

Represents chatters current name color.

user

PartialUser of the chatter.

Type

PartialUser

colour

The Colour. There is an alias to this named color.

Type

Colour

Attributes
class twitchio.ChatBadge(data: GlobalChatBadgesResponseData | ChannelChatBadgesResponseData, http: HTTPClient)

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]

class twitchio.ChatBadgeVersions(data: ChannelChatBadgesResponseVersions | GlobalChatBadgesResponseVersions, http: HTTPClient)

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

str | None

click_url

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

Type

str | None

get_image(scale: Literal['1x', '2x', '4x'] = '2x') Asset

Retrieves an Asset object for the chat badge image at the specified scale.

Parameters

scale (str) –

The scale (size) of the emote. Usually this will be one of: - “1x” (Small) - “2x” (Medium) - “4x” (Large)

Defaults is “2x”.

Example

chat_badges: list[twitchio.ChatBadge] = await client.fetch_global_chat_badges()
chat_badge: twitchio.ChatBadge = chat_badges[0]

# Get and save the chat badge asset as an image
asset: twitchio.Asset = await emote.get_image()
await asset.save()
Returns

The Asset for the chat badge. You can use the asset to read() or save() the chat badge image or return the generated URL with url.

Return type

Asset

Methods
class twitchio.Emote(data: GlobalEmotesResponseData | EmoteSetsResponseData | UserEmotesResponseData, template: str, http: HTTPClient)

Represents the basics of an Emote.

id

The ID of the emote.

Type

str

name

The name of the emote.

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]

get_image(*, theme: Literal['light', 'dark'] = 'light', scale: str = '2.0', format: Literal['default', 'static', 'animated'] = 'default') Asset

Creates an Asset for the emote, which can be used to download/save the emote image.

Parameters
  • theme (Literal["light", "dark"]) – The background theme of the emote. Defaults to “light”.

  • scale (str) –

    The scale (size) of the emote. Usually this will be one of: - “1.0” (Small) - “2.0” (Medium) - “3.0” (Large)

    Defaults to “2.0”.

  • format (Literal["default", "static", "animated"]) –

    The format of the image for the emote. E.g a static image (PNG) or animated (GIF).

    Use “default” to get the default format for the emote, which will be animated if available, otherwise static. Defaults to “default”.

Examples

emotes: list[twitchio.GlobalEmote] = await client.fetch_global_emotes()
emote: twitchio.GlobalEmote = emotes[0]

# Get and save the emote asset as an image
asset: twitchio.Asset = await emote.get_image()
await asset.save()
Returns

The Asset for the chat emote. You can use the asset to read() or save() the chat emote image or return the generated URL with url.

Return type

Asset

class twitchio.GlobalEmote(data: GlobalEmotesResponseData, *, template: str, http: HTTPClient)

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[str, 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]

class twitchio.EmoteSet(data: EmoteSetsResponseData, *, template: str, http: HTTPClient)

Represents an emote set.

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[str, str]

set_id

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

Type

str

type

The type of emote. The possible values are: bitstier, follower, subscriptions.

Type

str

owner

The PartialUser who owns this emote set.

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]

class twitchio.ChannelEmote(data: ChannelEmotesResponseData, *, template: str, http: HTTPClient)

Represents an emote set.

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[str, str]

tier

This field contains the tier information only if type is set to subscriptions, otherwise it’s None.

Type

Literal[“1000”, “2000”, “3000”] | None

set_id

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

Type

str

type

The type of emote. The possible values are:

  • bitstier — A custom Bits tier emote.

  • follower — A custom follower emote.

  • subscriptions — A custom subscriber emote.

Type

Literal[“bitstier”, “follower”, “subscriptions”]

owner

The PartialUser who owns this emote.

Type

PartialUser

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]

class twitchio.UserEmote(data: UserEmotesResponseData, *, template: str, http: HTTPClient)

Represents an emote set.

Type

Description

none

No emote type was assigned to this emote.

bitstier

A Bits tier emote.

follower

A follower emote.

subscriptions

A subscriber emote.

channelpoints

An emote granted by using channel points.

rewards

An emote granted to the user through a special event.

hypetrain

An emote granted for participation in a Hype Train.

prime

An emote granted for linking an Amazon Prime account.

turbo

An emote granted for having Twitch Turbo.

smilies

Emoticons supported by Twitch.

globals

An emote accessible by everyone.

owl2019

Emotes related to Overwatch League 2019.

twofactor

Emotes granted by enabling two-factor authentication on an account.

limitedtime

Emotes that were granted for only a limited time.

id

The ID of the emote.

Type

str

name

The name of the emote.

Type

str

type

The type of emote. Please see docs for full list of possible values.

Type

str

set_id

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

Type

str

owner

The ID of the broadcaster who owns the emote.

Type

PartialUser

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]

class twitchio.ChatSettings(data: ChatSettingsResponseData, *, http: HTTPClient)

Represents the settings of a broadcaster’s chat settings.

broadcaster

The PartialUser object of the broadcaster, this will only contain the ID.

Type

PartialUser

moderator

The PartialUser object of the moderator, this will only contain the ID.

Type

PartialUser

slow_mode

A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages.

Type

bool

slow_mode_wait_time

The amount of time, in seconds, that users must wait between sending messages. Is None if slow_mode is False.

Type

int | None

follower_mode

A Boolean value that determines whether the broadcaster restricts the chat room to followers only. Is True if the broadcaster restricts the chat room to followers only; otherwise, False.

Type

bool

follower_mode_duration

The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Is None if follower_mode is False.

Type

int | None

subscriber_mode

A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room.

Type

bool

emote_mode

A Boolean value that determines whether chat messages must contain only emotes. Is True if chat messages may contain only emotes; otherwise, False.

Type

bool

unique_chat_mode

A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Is True if the broadcaster requires unique messages only; otherwise, False.

Type

bool

non_moderator_chat_delay

A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room. This gives chat moderators and bots a chance to remove them before viewers can see the message. See the non_moderator_chat_delay_duration field for the length of the delay.

Is True if the broadcaster applies a delay; otherwise, False.

The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators.

Type

bool

non_moderator_chat_delay_duration

The amount of time, in seconds, that messages are delayed before appearing in chat. Is None if non_moderator_chat_delay is False.

The response includes this field only if the request specifies a user access token that includes the moderator:read:chat_settings scope and the user in the moderator_id query parameter is one of the broadcaster’s moderators.

Type

int | None

class twitchio.SentMessage(data: SendChatMessageResponseData)

Represents the settings of a broadcaster’s chat settings.

id

The ID for the message that was sent.

Type

str

sent

Whether the message passed all checks and was sent.

Type

bool

dropped_code

Code for why the message was dropped.

Type

str | None

dropped_message

Message for why the message was dropped.

Type

str | None

class twitchio.SharedChatSession(data: SharedChatSessionResponseData, *, http: HTTPClient)

Represents a shared chat session.

id

The unique identifier for the shared chat session.

Type

str

host

The User of the host channel.

Type

PartialUser

participants

The list of participants / users in the session.

Type

list[PartialUser]

created_at

When the session was created.

Type

datetime.datetime

updated_at

When the session was last updated.

Type

datetime.datetime

class twitchio.Clip(data: ClipsResponseData, *, http: HTTPClient)

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

twitchio.PartialUser

creator

The user who created the clip.

Type

twitchio.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

The Asset that can be used to read or save the thumbnail associated with this Clip.

Type

twitchio.Asset

Indicates if the clip is featured or not.

Type

bool

async fetch_game() Game

This function is a coroutine.

Fetches the Game associated with this Clip.

Returns

The game associated with this Clip.

Return type

Game

async fetch_video() Video | None

This function is a coroutine.

Fetches the Video associated with this clip, if it can be found.

Returns

  • Video – The video associated with this Clip.

  • None – The video was not found.

class twitchio.Entitlement(data: DropsEntitlementsResponseData, *, http: HTTPClient)

Represents a drops entitlement.

id

An ID that identifies the entitlement.

Type

str

benefit_id

An ID that identifies the benefit (reward).

Type

str

timestamp

Datetime of when the entitlement was granted.

Type

datetime.datetime

user

PartialUser of who was granted the entitlement.

Type

PartialUser

game_id

An ID that identifies the game the user was playing when the reward was entitled.

Type

str

fulfillment_status

The entitlement’s fulfillment status. Can be either CLAIMED or FULFILLED.

Type

Literal[“CLAIMED”, “FULFILLED”]

last_updated

Datetime of when the entitlement was last updated.

Type

datetime.datetime

async fetch_game() Game

This function is a coroutine.

Fetches the Game associated with this drop entitlement.

Returns

The game associated with this drop entitlement.

Return type

Game

Attributes
class twitchio.EntitlementStatus(data: UpdateDropsEntitlementsResponseData)

The status of entitlements after an update.

status

Indicates whether the status of the entitlements in the ids field were successfully updated.

Status

Description

INVALID_ID

The entitlement IDs in the ids field are not valid.

NOT_FOUND

The entitlement IDs in the ids field were not found.

SUCCESS

The status of the entitlements in the ids field were successfully updated.

UNAUTHORIZED

The user or organization identified by the user access token is not authorized to update the entitlements.

UPDATE_FAILED

The update failed. These are considered transient errors and the request should be retried later.

Type

Literal[“INVALID_ID”, “NOT_FOUND”, “SUCCESS”, “UNAUTHORIZED”, “UPDATE_FAILED”]

ids

The list of entitlement ids that the status in the status field applies to.

Type

list[str]

Attributes
class twitchio.Game(data: GamesResponseData, *, http: HTTPClient)

Represents a Game on Twitch.

You can retrieve a game by its ID, name or IGDB ID using the fetch_games() method or the various .fetch_game() methods of other models.

To fetch a list of games, see: fetch_games()

Supported Operations

Operation

Usage(s) | Description

__str__

str(game), f”{game}”

Returns the games name.

__repr__

repr(game), f”{game!r}”

Returns the games official representation.

__eq__

game == game2, game != game2

Checks if two games are equal.

id

The ID of the game provided by Twitch.

Type

str

name

The name of the game.

Type

str

box_art

The box art of the game as an Assets.

Type

Asset

igdb_id

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

Type

str | None

class twitchio.Goal(data: CreatorGoalsResponseData, http: HTTPClient)

Represents a broadcaster’s goal.

The goal’s type determines how the current_target is increased or decreased.

  • If type is follower, this field is set to the broadcaster’s current number of followers. This number increases with new followers and decreases when users unfollow the broadcaster.

  • If type is subscription, this field is increased and decreased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased or decreased by 2, not 1.

  • If type is subscription_count, this field is increased by 1 for each new subscription and decreased by 1 for each user that unsubscribes.

  • If type is new_subscription, this field is increased by the points value associated with the subscription tier. For example, if a tier-two subscription is worth 2 points, this field is increased by 2, not 1.

  • If type is new_subscription_count, this field is increased by 1 for each new subscription.

Type

Description

follower

The goal is to increase followers.

subscription

The goal is to increase subscriptions. This type shows the net increase or decrease in tier points associated with the subscriptions.

subscription_count

The goal is to increase subscriptions. This type shows the net increase or decrease in the number of subscriptions.

new_subscription

The goal is to increase subscriptions. This type shows only the net increase in tier points associated with the subscriptions (it does not account for users that unsubscribed since the goal started).

new_subscription_count

The goal is to increase subscriptions. This type shows only the net increase in the number of subscriptions (it does not account for users that unsubscribed since the goal started).

id

An ID that identifies this goal.

Type

str

broadcaster

The broadcaster that created the goal.

Type

PartialUser

type

The type of goal. Possible values are: follower, subscription, subscription_count, new_subscription, new_subscription_count Please refer to the documentation for more details.

Type

Literal[“follower”, “subscription”, “subscription_count”, “new_subscription”, “new_subscription_count”]

description

A description of the goal. Is an empty string if not specified.

Type

str

current_amount

The goal’s current value.

Type

int

target_amount

The goal’s target value. For example, if the broadcaster has 200 followers before creating the goal, and their goal is to double that number, this field is set to 400.

Type

int

created_at

The datetime that the broadcaster created the goal.

Type

datetime.datetime

class twitchio.HypeTrainEvent(data: HypeTrainEventsResponseData, *, http: HTTPClient)

Represents a Hype Train Event.

id

The ID of the event.

Type

str

hype_train_id

The ID of the Hype Train.

Type

str

type

The type of the event, in the form, hypetrain.{event_name} (i.e. 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]

total_contributed

The current total amount raised.

Type

int

goal

The goal for the next Hype Train level

Type

int

Attributes
class twitchio.HypeTrainContribution(data: HypeTrainEventsResponseContributions, *, http: HTTPClient)

A Contribution to a Hype Train

total

The total amount contributed. If type is BITS, total represents the amount of Bits used. If type is SUBS, total is 500, 1000, or 2500 to represent tier 1, 2, or 3 subscriptions, respectively.

Type

int

type

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

Type

Literal[“BITS”, “SUBS”, “OTHER”]

user

The user making the contribution.

Type

PartialUser

Attributes
class twitchio.AutoModStatus(data: CheckAutomodStatusResponseData)

Represents the Automod status of a message.

msg_id

A caller-defined ID passed in the request.

Type

str

permitted

A Boolean value that indicates whether Twitch would approve the message for chat or hold it for moderator review or block it from chat. Is True if Twitch would approve the message; otherwise, False if Twitch would hold the message for moderator review or block it from chat.

Type

bool

Attributes
class twitchio.AutomodCheckMessage(id: str, text: str)

Represents the message to check with automod

id

Developer-generated identifier for mapping messages to results.

Type

str

text

Message text.

Type

str

class twitchio.AutomodSettings(data: AutomodSettingsResponseData, *, http: HTTPClient)

Represents the AutoModSettings of a broadcaster’s chat room.

broadcaster

The PartialUser instance representing the broadcaster.

Type

PartialUser

moderator

The PartialUser instance representing the moderator.

Type

PartialUser

overall_level

The overall moderation level, which could be None if the broadcaster has set one or more of the individual settings.

Type

int | None

disability

The Automod level for discrimination against disability.

Type

int

aggression

The Automod level for hostility involving aggression.

Type

int

sexuality_sex_or_gender

The AutoMod level for discrimination based on sexuality, sex, or gender.

Type

int

misogyny

The Automod level for discrimination against women.

Type

int

bullying

The Automod level for hostility involving name calling or insults.

Type

int

swearing

The Automod level for profanity.

Type

int

race_ethnicity_or_religion

The Automod level for racial discrimination.

Type

int

sex_based_terms

The Automod level for sexual content.

Type

int

to_dict(use_ids: bool = False) dict[str, str | int | None]

Returns the AutomodSettings as a dictionary. This is the equivalent of the raw payload returned by Twitch.

Parameters

use_ids (bool) – Whether to include the broadcaster and moderator IDs in the dictionary.

Returns

Dictionary data type of AutomodSettings

Return type

dict[str, str | int | None]

class twitchio.BannedUser(data: BannedUsersResponseData, *, http: HTTPClient)

Represents a BannedUser.

user

The user banned or timed out.

Type

PartialUser

moderator

The moderator who banned or put the user in timeout.

Type

PartialUser

expires_at

Datetime of when the timeout will end. This is None if permanently banned.

Type

datetime.datetime | None

created_at

Datetime of when the user was banned.

Type

datetime.datetime

reason

The reason the user was banned or put in a timeout if the moderator provided one.

Type

str

class twitchio.Ban(data: BanUserResponseData, *, http: HTTPClient)

Represents a Ban.

broadcaster

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

Type

PartialUser

user

The user banned or timed out.

Type

PartialUser

moderator

The moderator who banned or put the user in timeout.

Type

PartialUser

created_at

Datetime of when the user was banned.

Type

datetime.datetime

class twitchio.Timeout(data: BanUserResponseData, *, http: HTTPClient)

Represents a Timeout.

broadcaster

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

Type

PartialUser

user

The user timed out.

Type

PartialUser

moderator

The moderator who put the user in timeout.

Type

PartialUser

end_time

Datetime of when the timeout will end.

Type

datetime.datetime

created_at

Datetime of when the user was timed out.

Type

datetime.datetime

class twitchio.UnbanRequest(data: UnbanRequestsResponseData | ResolveUnbanRequestsResponseData, *, http: HTTPClient)

Represents an unban request.

id

Unban request ID.

Type

str

broadcaster

The broadcaster whose channel is receiving the unban request.

Type

PartialUser

moderator

The moderator who approved/denied the request.

Type

PartialUser

user

The requestor who is asking for an unban.

Type

PartialUser

text

Text of the request from requesting user.

Type

str

status

Status of the request. One of: pending, approved, denied, acknowledged, canceled

Type

Literal[“pending”, “approved”, “denied”, “acknowledged”, “canceled”]

created_at

Datetime of when the unban request was created.

Type

datetime.datetime

resolved_at

Datetime of when moderator/broadcaster approved or denied the request.

Type

datetime.datetime | None

resolution_text

Text input by the resolver (moderator) of the unban request.

Type

str | None

class twitchio.BlockedTerm(data: BlockedTermsResponseData, http: HTTPClient)

Represents a blocked term.

id

An ID that identifies this blocked term.

Type

str

broadcaster

The broadcaster that owns the list of blocked terms.

Type

PartialUser

moderator

The moderator that blocked the word or phrase from being used in the broadcaster’s chat room.

Type

PartialUser

text

The blocked word or phrase.

Type

str

created_at

Datetime that the term was blocked.

Type

datetime.datetime

updated_at

Datetime that the term was updated. When the term is added, this timestamp is the same as created_at. The timestamp changes as AutoMod continues to deny the term.

Type

datetime.datetime

expires_at

Datetime that the blocked term is set to expire. After the block expires, users may use the term in the broadcaster’s chat room. Is None if the term was added manually or was permanently blocked by AutoMod.

Type

datetime.datetime | None

class twitchio.ShieldModeStatus(data: ShieldModeStatusResponseData, *, http: HTTPClient)

Represents a shield mode status..

active

Whether Shield Mode is active. Is true if Shield Mode is active;

Type

bool

moderator

The moderator that last activated Shield Mode.

Type

PartialUser

last_activated_at

When Shield Mode was last activated.

Type

datetime.datetime

class twitchio.Warning(data: WarnChatUserResponseData, *, http: HTTPClient)

Represents a warning to a user.

broadcaster

The channel in which the warning will take effect.

Type

PartialUser

user

The warned user.

Type

PartialUser

moderator

The moderator who applied the warning.

Type

PartialUser

reason

The reason provided for warning.

Type

str

class twitchio.Poll(data: PollsResponseData, *, http: HTTPClient)

Represents a Poll

Status

Description

ACTIVE

The poll is running.

COMPLETED

The poll ended on schedule.

TERMINATED

The poll was terminated before its scheduled end.

ARCHIVED

The poll has been archived and is no longer visible on the channel.

MODERATED

The poll was deleted.

INVALID

Something went wrong while determining the state.

id

An ID that identifies the poll.

Type

str

broadcaster

The broadcaster that created the poll.

Type

PartialUser

title

The question that viewers are voting on.

Type

str

choices

A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.

Type

list[PollChoice]

channel_points_voting_enabled

A Boolean value that indicates whether viewers may cast additional votes using Channel Points.

Type

bool

channel_points_per_vote

The number of points the viewer must spend to cast one additional vote.

Type

int

status

The poll’s status. Valid values are ACTIVE, COMPLETED, TERMINATED, ARCHIVED, MODERATED and INVALID.

Type

Literal[“ACTIVE”, “COMPLETED”, “TERMINATED”, “ARCHIVED”, “MODERATED”, “INVALID”]

duration

The length of time (in seconds) that the poll will run for.

Type

int

started_at

The datetime of when the poll began.

Type

datetime.datetime

ended_at

The datetime of when the poll ended. This is None if status is ACTIVE.

Type

datetime.datetime | None

async end_poll(*, status: Literal['ARCHIVED', 'TERMINATED']) Poll

This function is a coroutine.

End an active poll.

Note

Requires user access token that includes the channel:manage:polls scope.

Parameters
  • typing.Literal["ARCHIVED" (status) – The status to set the poll to. Possible case-sensitive values are: “ARCHIVED” and “TERMINATED”.

  • "TERMINATED"] – The status to set the poll to. Possible case-sensitive values are: “ARCHIVED” and “TERMINATED”.

Returns

A Poll object.

Return type

Poll

class twitchio.PollChoice(data: PollsResponseChoices | PollChoiceData)

Represents a poll choice.

This model is shared between Helix and Eventsub.

Note

channel_points_votes and votes will both be None for a Channel Poll Begin event.

id

An ID that identifies the choice.

Type

str

title

The choice’s title.

Type

str

channel_points_votes

Number of votes received via channel points. This is None for a Channel Poll Begin event.

Type

int | None

votes

Total number of votes received for the choice across all methods of voting. This is None for a Channel Poll Begin event.

Type

int | None

class twitchio.Prediction(data: PredictionsResponseData, *, http: HTTPClient)

Represents a Prediction

Status

Description

ACTIVE

The Prediction is running and viewers can make predictions.

CANCELED

The broadcaster canceled the Prediction and refunded the Channel Points to the participants.

LOCKED

The broadcaster locked the Prediction, which means viewers can no longer make predictions.

RESOLVED

The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.

id

An ID that identifies this prediction.

Type

str

broadcaster

The broadcaster that created the prediction.

Type

PartialUser

title

The question that the prediction asks.

Type

str

winning_outcome_id

The ID of the winning outcome. Is None unless status is RESOLVED.

Type

str | None

outcomes

The list of possible outcomes for the prediction.

Type

list[PredictionOutcome]

prediction_window

The length of time (in seconds) that the prediction will run for.

Type

int

created_at

The datetime of when the prediction began.

Type

datetime.datetime

ended_at

The datetime of when the prediction ended. This is None if status is ACTIVE.

Type

datetime.datetime | None

locked_at

The datetime of when the prediction locked. If status is not LOCKED, this is set to None.

Type

datetime.datetime | None

async end_prediction(*, status: Literal['RESOLVED', 'CANCELED', 'LOCKED'], winning_outcome_id: str | None = None) Prediction

This function is a coroutine.

End an active prediction.

Note

Requires user access token that includes the channel:manage:predictions scope.

Parameters

status (Literal["RESOLVED", "CANCELED", "LOCKED"]) – The status to set the prediction to. Possible case-sensitive values are: RESOLVED, CANCELED, LOCKED

Returns

A Prediction object.

Return type

Prediction

class twitchio.PredictionOutcome(data: PredictionsResponseOutcomes | PredictionOutcomeData, *, http: HTTPClient)

Represents a prediction outcome.

id

An ID that identifies the choice.

Type

str

title

The choice’s title.

Type

str

users

The number of unique viewers that chose this outcome.

Type

int | None

channel_points

The number of Channel Points spent by viewers on this outcome.

Type

int | None

top_predictors

A list of viewers who were the top predictors; otherwise, None if none.

Type

list[Predictor]

colour

The number of votes cast using Channel Points.

Type

Literal[“BLUE”, “PINK”, “blue”, “pink”]

property color: str

The color of the prediction. Alias to colour.

class twitchio.Predictor(data: PredictionsResponseTopPredictors | PredictorData, *, http: HTTPClient)

Represents a predictor

user

The viewer.

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 | None

Attributes
class twitchio.Raid(data: StartARaidResponseData)

Represents a raid for a broadcaster / channel

created_at

Datetime of when the raid started.

Type

datetime.datetime

mature

Indicates whether the stream being raided is marked as mature.

Type

bool

class twitchio.Schedule(data: ChannelStreamScheduleResponseData, *, http: HTTPClient)

Represents a channel’s stream schedule

segments

The list of broadcasts in the broadcaster’s streaming schedule.

Type

list[ScheduleSegment]

broadcaster

The broadcaster that owns the broadcast schedule.

Type

PartialUser

vacation

The dates when the broadcaster is on vacation and not streaming. Is set to None if vacation mode is not enabled.

Type

ScheduleVacation | None

class twitchio.ScheduleSegment(data: ChannelStreamScheduleResponseSegments, *, http: HTTPClient, broadcaster_id: str)

Represents a segment 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

datetime.datetime

title

Title for the scheduled broadcast.

Type

str

canceled_until

Indicates whether the broadcaster canceled this segment of a recurring broadcast. If the broadcaster canceled this segment, this field is set to the same value that’s in the end_time field; otherwise, it’s None.

Type

datetime.datetime | None

category

The game or category details for the scheduled broadcast.

Type

ScheduleCategory | None

is_recurring

Indicates if the scheduled broadcast is recurring weekly.

Type

bool

async update_segment(*, start_time: datetime.datetime | None = None, duration: int | None = None, category_id: str | None = None, title: str | None = None, canceled: bool | None = None, timezone: str | None = None) Schedule

This function is a coroutine.

Updates a scheduled broadcast segment.

Note

Requires a user access token that includes the channel:manage:schedule scope.

Parameters
  • token_for (str | PartialUser) – User access token that includes the channel:manage:schedule scope.

  • start_time (datetime.datetime | None) – The datetime that the broadcast segment starts. This can be timezone aware.

  • duration (int | None) – he length of time, in minutes, that the broadcast is scheduled to run. The duration must be in the range 30 through 1380 (23 hours)

  • category_id (str | None) – The ID of the category that best represents the broadcast’s content. To get the category ID, use the [Search Categories][twitchio.client.search_categories].

  • title (str | None) – The broadcast’s title. The title may contain a maximum of 140 characters.

  • canceled (bool | None) – A Boolean value that indicates whether the broadcast is canceled. Set to True to cancel the segment.

  • timezone (str | None) – The time zone where the broadcast takes place. Specify the time zone using IANA time zone database format (for example, America/New_York).

Returns

Schedule object.

Return type

Schedule

Raises
  • ValueError – Duration must be between 30 and 1380.

  • ValueError – Title must not be greater than 140 characters.

async delete() None

This function is a coroutine.

Removes a broadcast segment from the broadcaster’s streaming schedule.

For recurring segments, removing a segment removes all segments in the recurring schedule.

Note

Requires a user access token that includes the channel:manage:schedule scope.

Parameters

token_for (str | PartialUser) – User access token that includes the channel:manage:schedule scope.

Attributes
class twitchio.ScheduleCategory(data: ChannelStreamScheduleResponseCategory)

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: ChannelStreamScheduleResponseVacation)

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

class twitchio.SearchChannel(data: SearchChannelsResponseData, *, http: HTTPClient)

Represents a channel via a search.

broadcaster

The broadcaster / channel.

Type

PartialUser

title

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

Type

str

game_id

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

Type

str

game_name

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

Type

str

live

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

Type

bool

tags

The tags applied to the channel.

Type

list[str]

thumbnail

An Asset for the thumbnail of the broadcaster’s profile image.

Type

Asset

language

The ISO 639-1 two-letter language code of the language used by the broadcaster. For example, en for English. If the broadcaster uses a language not in the list of supported stream languages, the value is other.

Type

str

started_at

Datetime of when the broadcaster started streaming. Is None if the broadcaster is not streaming live.

Type

datetime.datetime | None

async fetch_game() Game

This function is a coroutine.

Fetches the Game associated with this channel.

The Game returned is current from the time the SearchChannel instance was created.

Returns

The game associated with this SearchChannel instance.

Return type

twitchio.Game

class twitchio.Stream(data: StreamsResponseData, *, http: HTTPClient)

Represents a Stream

id

The current stream ID.

Type

str

user

The user who is streaming.

Type

twitchio.PartialUser

game_id

Current game ID being played on the channel. Could be None if no category / game has been set.

Type

str | None

game_name

Name of the game being played on the channel. Could be None if no category / game has been set.

Type

str | None

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

The Asset which can be used to read or save the thumbnail associated with this stream.

Type

Asset

is_mature

Indicates whether the stream is intended for mature audience.

Type

bool

tags

The tags applied to the channel.

Type

list[str]

async fetch_game() twitchio.models.games.Game | None

This function is a coroutine.

Fetches the Game associated with this stream.

The Game returned is current from the time the Stream instance was created.

Could be None if no category / game was set at the time the Stream instance was created.

Returns

The game associated with this Stream instance, or None.

Return type

twitchio.Game | None

Attributes
class twitchio.StreamMarker(data: CreateStreamMarkerResponseData | StreamMarkersResponseMarkers)

Represents a stream marker.

id

An ID that identifies the single market you added.

Type

str

created_at

Datetime of when the user created the stream marker.

Type

datetime.datetime

position

The relative offset (in seconds) of the marker from the beginning of the stream.

Type

int

url

A URL that opens the video in Twitch Highlighter. This is None on creation but populated when fetched.

Type

str | None

Attributes
class twitchio.VideoMarkers(data: StreamMarkersResponseData, *, http: HTTPClient)

Represents stream markers for the latest stream.

user

The user that created the stream marker.

Type

PartialUser

video_id

An ID that identifies this video.

Type

str

markers

The list of markers in this video. The list in ascending order by when the marker was created.

Type

list[StreamMarker]

class twitchio.UserSubscription(data: BroadcasterSubscriptionsResponseData | CheckUserSubscriptionResponseData, *, http: HTTPClient)

Represents a subscription of a user.

broadcaster

The broadcaster being subscribed to.

Type

PartialUser

gift

A Boolean value that determines whether the subscription is a gift subscription. Is True if the subscription was gifted.

Type

bool

tier

The type of subscription. Possible values are:

  • 1000: Tier 1

  • 2000: Tier 2

  • 3000: Tier 3

Type

Literal[“1000”, “2000”, “3000”]

gifter

The user who gifted the subscription. This is None if gift is False.

Type

PartialUser | None

property rounded_tier: int

Returns the tier as a single digit. e.g. Tier 1000 = 1.

class twitchio.BroadcasterSubscription(data: BroadcasterSubscriptionsResponseData, *, http: HTTPClient)

Represents a subscription of a user.

broadcaster

The broadcaster being subscribed to.

Type

PartialUser

gift

A Boolean value that determines whether the subscription is a gift subscription. Is True if the subscription was gifted.

Type

bool

tier

The type of subscription. Possible values are:

  • 1000: Tier 1

  • 2000: Tier 2

  • 3000: Tier 3

Type

Literal[“1000”, “2000”, “3000”]

gifter

The user who gifted the subscription. This is None if gift is False.

Type

PartialUser | None

plan_name

The name of the subscription.

Type

str

user

The subscribing user.

Type

PartialUser

class twitchio.BroadcasterSubscriptions(data: BroadcasterSubscriptionsResponse, iterator: HTTPAsyncIterator[BroadcasterSubscription])

Represents all the users that subscribe to a broadcaster.

Note

total and points are None if user_ids is provided.

subscriptions

HTTPAsyncIterator of [BroadcasterSubscription][] objects.

Type

HTTPAsyncIterator[BroadcasterSubscription]

total

The total number of users that subscribe to this broadcaster. This is None if user_ids is provided.

Type

int | None

points

The current number of subscriber points earned by this broadcaster. Points are based on the subscription tier of each user that subscribes to this broadcaster.

For example, a Tier 1 subscription is worth 1 point, Tier 2 is worth 2 points, and Tier 3 is worth 6 points. The number of points determines the number of emote slots that are unlocked for the broadcaster (see Subscriber Emote Slots).

This is None if user_ids is provided.

Type

int | None

class twitchio.Team(data: TeamsResponseData, *, http: HTTPClient)

Represents information for a specific Twitch Team

users

List of users in the specified Team.

Type

list[PartialUser]

background_image

URL for the Team background image.

Type

Asset | None

banner

URL for the Team banner.

Type

Asset | None

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

Image URL for the Team logo.

Type

Asset | None

name

Team name.

Type

str

display_name

Team display name.

Type

str

id

Team ID.

Type

str

class twitchio.ChannelTeam(data: ChannelTeamsResponseData, http: HTTPClient)

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

broadcaster

The broadcaster.

Type

PartialUser

background_image

Asset for the team background image.

Type

Asset | None

banner

Asset for the team banner.

Type

Asset | None

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

Asset for the team logo.

Type

Asset | None

name

Team name.

Type

str

display_name

Team display name.

Type

str

id

Team ID.

Type

str

class twitchio.Video(data: VideosResponseData, *, http: HTTPClient)

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

async delete(token_for: str) None

Deletes the video. For bulk deletion see delete_videos()

Parameters

token_for (str) – A user oauth token with the channel:manage:videos scope.