PartialUser¶

Attributes

display_name
id
mention
name

Methods

asyncadd_blocked_term
asyncadd_moderator
asyncadd_suspicious_chat_user
asyncadd_vip
asyncapprove_automod_messages
asyncban_user
asyncblock_user
asynccancel_raid
asynccheck_automod_status
asynccreate_clip
asynccreate_custom_reward
asynccreate_poll
asynccreate_prediction
asynccreate_schedule_segment
asynccreate_stream_marker
asyncdelete_chat_messages
asyncdelete_custom_reward
asyncdelete_schedule_segment
asyncdeny_automod_messages
asyncend_poll
asyncend_prediction
asyncfetch_active_extensions
asyncfetch_ad_schedule
asyncfetch_auth
asyncfetch_automod_settings
asyncfetch_badges
async forfetch_banned_user
asyncfetch_bits_leaderboard
async forfetch_block_list
async forfetch_blocked_terms
asyncfetch_broadcaster_subscriptions
asyncfetch_channel_emotes
asyncfetch_channel_info
asyncfetch_channel_teams
asyncfetch_charity_campaign
async forfetch_charity_donations
asyncfetch_chat_settings
asyncfetch_chatters
async forfetch_clips
asyncfetch_custom_rewards
asyncfetch_editors
async forfetch_extension_analytics
asyncfetch_followed_channels
async forfetch_followed_streams
asyncfetch_followers
async forfetch_game_analytics
asyncfetch_goals
async forfetch_hype_train_events
asyncfetch_hype_train_status
async forfetch_moderated_channels
async forfetch_moderators
async forfetch_polls
async forfetch_predictions
asyncfetch_shared_chat_session
asyncfetch_shield_mode_status
asyncfetch_stream
asyncfetch_stream_key
async forfetch_stream_markers
async forfetch_stream_schedule
asyncfetch_subscription
async forfetch_unban_requests
async forfetch_user_emotes
async forfetch_vips
asyncmodify_channel
asyncremove_blocked_term
asyncremove_moderator
asyncremove_suspicious_chat_user
asyncremove_vip
asyncresolve_unban_request
asyncsend_announcement
asyncsend_message
asyncsend_shoutout
asyncsend_whisper
asyncsnooze_next_ad
asyncstart_commercial
asyncstart_raid
asynctimeout_user
asyncunban_user
asyncunblock_user
asyncupdate
asyncupdate_automod_settings
asyncupdate_chat_settings
asyncupdate_chatter_color
asyncupdate_custom_reward
asyncupdate_schedule_segment
asyncupdate_shield_mode_status
asyncupdate_stream_schedule
asyncuser
asyncwarn_user

class twitchio.PartialUser¶

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

Any API calls pertaining to a user / broadcaster / channel will be on this object.

id¶

The user’s ID.

Type: str | int

name¶

The user’s name. Also known as username or login name. In most cases, this is provided. There are however, rare cases where it is not.

Type: str | None

display_name¶

The user’s display name in chat. In most cases, this is provided otherwise fallsback to name. There are however, rare cases where it is not.

Type: str | None

property mention: str¶

Property returning the users display_name formatted to mention them in chat.

E.g. “@kappa”

async start_commercial(*, length: int) → CommercialStart¶

This function is a coroutine.

Starts a commercial on the specified channel.

Important

Only partners and affiliates may run commercials and they must be streaming live at the time.

Only the broadcaster may start a commercial; the broadcaster’s editors and moderators may not start commercials on behalf of the broadcaster.

Note

Requires user access token that includes the channel:edit:commercial scope.

Parameters: length (int) – The length of the commercial to run, in seconds. Max length is 180. If you request a commercial that’s longer than 180 seconds, the API uses 180 seconds.
Returns: A CommercialStart object.
Return type: CommercialStart

async fetch_ad_schedule() → AdSchedule¶

This function is a coroutine.

Fetch ad schedule related information, including snooze, when the last ad was run, when the next ad is scheduled, and if the channel is currently in pre-roll free time.

Important

A new ad cannot be run until 8 minutes after running a previous ad.

The user id in the user access token must match the id of this PartialUser object.

Note

Requires user access token that includes the channel:read:ads scope.

Returns: An AdSchedule object.
Return type: AdSchedule

async snooze_next_ad() → SnoozeAd¶

This function is a coroutine.

If available, pushes back the timestamp of the upcoming automatic mid-roll ad by 5 minutes. This endpoint duplicates the snooze functionality in the creator dashboard’s Ads Manager.

Important

The user id in the user access token must match the id of this PartialUser object.

Note

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

Returns: A SnoozeAd object.
Return type: SnoozeAd

fetch_extension_analytics(*, token_for: str | PartialUser, first: int = 20, extension_id: str | None = None, type: Literal['overview_v2'] = 'overview_v2', started_at: datetime.date | None = None, ended_at: datetime.date | None = None, max_results: int | None = None) → HTTPAsyncIterator[ExtensionAnalytics]¶

This function returns a HTTPAsyncIterator

Fetches an analytics report for one or more extensions. The response contains the URLs used to download the reports (CSV files)

Important

Both started_at and ended_at must be provided when requesting a date range. They are UTC timezone by default. If you omit both of these then the report includes all available data from January 31, 2018.

Because it can take up to two days for the data to be available, you must specify an end date that’s earlier than today minus one to two days. If not, the API ignores your end date and uses an end date that is today minus one to two days.

Note

Requires user access token that includes the analytics:read:extensions scope.

Parameters

token_for (str | PartialUser) – The user ID (or PartialUser) whose user access token should be used for this request. The token must include the analytics:read:extensions scope.
extension_id (str) – The extension’s client ID. If specified, the response contains a report for the specified extension. If not specified, the response includes a report for each extension that the authenticated user owns.
type (Literal["overview_v2"]) – The type of analytics report to get. This is set to overview_v2 by default.
started_at (datetime.date) – The date to start the report from. If you specify a start date, you must specify an end date.
ended_at (datetime.date) – The end date for the report, this is inclusive. Specify an end date only if you provide a start date.
first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Return type

HTTPAsyncIterator[ExtensionAnalytics]

Raises

ValueError – Both started_at and ended_at must be provided together.

fetch_game_analytics(*, token_for: str | PartialUser, first: int = 20, game_id: str | None = None, type: Literal['overview_v2'] = 'overview_v2', started_at: datetime.date | None = None, ended_at: datetime.date | None = None, max_results: int | None = None) → HTTPAsyncIterator[GameAnalytics]¶

This function returns a HTTPAsyncIterator

Fetches a game report for one or more games. The response contains the URLs used to download the reports (CSV files)

Important

Both started_at and ended_at must be provided when requesting a date range. If you omit both of these then the report includes all available data from January 31, 2018.

Note

Requires user access token that includes the analytics:read:games scope.

Parameters

token_for (str | PartialUser) – The user ID (or PartialUser) whose user access token should be used for this request. The token must include the analytics:read:games scope.
game_id (str) – The game’s client ID. If specified, the response contains a report for the specified game. If not specified, the response includes a report for each of the authenticated user’s games.
type (Literal["overview_v2"]) – The type of analytics report to get. This is set to overview_v2 by default.
started_at (datetime.date) – The date to start the report from. If you specify a start date, you must specify an end date.
ended_at (datetime.date) – The end date for the report, this is inclusive. Specify an end date only if you provide a start date.
first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Return type

twitchio.HTTPAsyncIterator[GameAnalytics]

Raises

ValueError – Both started_at and ended_at must be provided together.

async fetch_bits_leaderboard(count: int = 10, period: Literal['all', 'day', 'week', 'month', 'year'] = 'all', started_at: datetime.datetime | None = None, user: str | int | PartialUser | None = None) → BitsLeaderboard¶

This function is a coroutine.

Fetches the Bits leaderboard for this user.

Important

started_at is converted to PST before being used, so if you set the start time to 2022-01-01T00:00:00.0Z and period to month, the actual reporting period is December 2021, not January 2022.

If you want the reporting period to be January 2022, you must set the start time to 2022-01-01T08:00:00.0Z or 2022-01-01T00:00:00.0-08:00.

When providing started_at, you must also change the period parameter to any value other than “all”.

Conversely, if period is set to anything other than “all”, started_at must also be provided.

Note

Requires user access token that includes the bits:read scope.

Period	Description
day	A day spans from 00:00:00 on the day specified in started_at and runs through 00:00:00 of the next day.
week	A week spans from 00:00:00 on the Monday of the week specified in started_at and runs through 00:00:00 of the next Monday.
month	A month spans from 00:00:00 on the first day of the month specified in started_at and runs through 00:00:00 of the first day of the next month.
year	A year spans from 00:00:00 on the first day of the year specified in started_at and runs through 00:00:00 of the first day of the next year.
all	Default. The lifetime of the broadcaster’s channel.

Parameters

count (int) – The number of results to return. The minimum count is 1 and the maximum is 100. The default is 10.
period (Literal["all", "day", "week", "month", "year"]) – The time period over which data is aggregated (uses the PST time zone).
started_at (datetime.datetime | None) – The start date, used for determining the aggregation period. Specify this parameter only if you specify the period query parameter. The start date is ignored if period is all. This can be timezone aware.
user (str | int | PartialUser | None) – A User ID that identifies a user that cheered bits in the channel. If count is greater than 1, the response may include users ranked above and below the specified user. To get the leaderboard’s top leaders, don’t specify a user ID.

Returns

BitsLeaderboard object for a user’s channel.

Return type

BitsLeaderboard

Raises

ValueError – Count must be between 10 and 100.
ValueError – The ‘period’ parameter must be set to anything other than ‘all’ if ‘started_at’ is provided, and vice versa.

async fetch_channel_info(*, token_for: str | PartialUser | None = None) → ChannelInfo¶

This function is a coroutine.

Retrieve channel information for this user.

Parameters: token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request.
Returns: ChannelInfo object representing the channel information.
Return type: ChannelInfo

async modify_channel(*, game_id: str | None = None, language: str | None = None, title: str | None = None, delay: int | None = None, tags: list[str] | None = None, classification_labels: list[dict[Literal['DebatedSocialIssuesAndPolitics', 'MatureGame', 'DrugsIntoxication', 'SexualThemes', 'ViolentGraphic', 'Gambling', 'ProfanityVulgarity'], bool]] | None = None, branded: bool | None = None) → None¶

This function is a coroutine.

Updates this user’s channel properties.

Important

A channel may specify a maximum of 10 tags. Each tag is limited to a maximum of 25 characters and may not be an empty string or contain spaces or special characters. Tags are case insensitive. For readability, consider using camelCasing or PascalCasing.

Note

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

Parameters

game_id (str | None) – The ID of the game that the user plays. The game is not updated if the ID isn’t a game ID that Twitch recognizes. To unset this field, use ‘0’ or ‘’ (an empty string).
language (str | None) – The user’s preferred language. Set the value to an ISO 639-1 two-letter language code (for example, en for English). Set to “other” if the user’s preferred language is not a Twitch supported language. The language isn’t updated if the language code isn’t a Twitch supported language.
title (str | None) – The title of the user’s stream. You may not set this field to an empty string.
delay (int | None) – The number of seconds you want your broadcast buffered before streaming it live. The delay helps ensure fairness during competitive play. Only users with Partner status may set this field. The maximum delay is 900 seconds (15 minutes).
tags (list[str] | None) –
A list of channel-defined tags to apply to the channel. To remove all tags from the channel, set tags to an empty array. Tags help identify the content that the channel streams. You may set a maximum of 10 tags, each limited to 25 characters. They can not be empty strings, contain spaces or special characters.

See here for more information
classification_labels (list[dict[Literal["DebatedSocialIssuesAndPolitics", "MatureGame", "DrugsIntoxication", "SexualThemes", "ViolentGraphic", "Gambling", "ProfanityVulgarity"], bool]] | None) – List of labels that should be set as the Channel’s CCLs.
branded (bool | None) – Boolean flag indicating if the channel has branded content.

async fetch_editors() → list[ChannelEditor]¶

This function is a coroutine.

Fetches a list of the user’s editors for their channel.

Note

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

Returns: A list of ChannelEditor objects.
Return type: list[ChannelEditor]

async fetch_followed_channels(broadcaster: str | int | None = None, first: int = 20, max_results: int | None = None) → FollowedChannels | None¶

This function is a coroutine.

Fetches information of who and when this user followed other channels.

Note

Requires user access token that includes the user:read:follows scope.

Parameters

broadcaster (str | int | PartialUser | None) – Provide a User ID, or PartialUser, to check whether the user follows this broadcaster.
first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

FollowedChannels object.

Return type

FollowedChannels

This function is a coroutine.

Fetches information of who and when users followed this channel.

Important

The user ID in the token must match that of the broadcaster or a moderator.

Note

Requires user access token that includes the moderator:read:followers scope.

Parameters

user (str | int | PartialUser | None) – Provide a User ID, or PartialUser, to check whether the user follows this broadcaster.
first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.
token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. This should usually be the moderator’s ID (matching the user in the access token).

Returns

A ChannelFollowers object.

Return type

ChannelFollowers

async create_custom_reward(title: str, cost: int, *, prompt: str | None = None, enabled: bool = True, background_color: str | Colour | None = None, max_per_stream: int | None = None, max_per_user: int | None = None, global_cooldown: int | None = None, redemptions_skip_queue: bool = False) → CustomReward¶

This function is a coroutine.

Creates a Custom Reward in the broadcaster’s channel.

Note

The maximum number of custom rewards per channel is 50, which includes both enabled and disabled rewards.

Note

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

Parameters

title (str) – The custom 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) – 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. The prompt is limited to a maximum of 200 characters. If provided, the user must input a message when redeeming the reward.
enabled (bool) – A Boolean value that determines whether the reward is enabled. Viewers see only enabled rewards. The default is True.
background_color (str | Colour | None) – The background color to use for the reward. Specify the color using Hex format (for example, #9147FF). This can also be a [.Colour][twitchio.utils.Colour] object.
max_per_stream (int | None) – The maximum number of redemptions allowed per live stream. Minimum value is 1.
max_per_user (int | None) – The maximum number of redemptions allowed per user per stream. Minimum value is 1.
global_cooldown (int | None) – The cooldown period, in seconds. The minimum value is 1; however, the minimum value is 60 for it to be shown in the Twitch UX.
redemptions_skip_queue (bool) – 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.

Returns

Information regarding the custom reward.

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.

async fetch_custom_rewards(*, ids: list[str] | None = None, manageable: bool = False) → list[CustomReward]¶

This function is a coroutine.

Fetches list of custom rewards that the specified broadcaster created.

Note

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

Parameters

ids (list[str] | None) – A list of IDs to filter the rewards by. You may request a maximum of 50.
manageable (bool | None) – A Boolean value that determines whether the response contains only the custom rewards that the app (Client ID) may manage. Default is False.

Returns

_description_

Return type

list[CustomReward]

async fetch_charity_campaign() → CharityCampaign¶

This function is a coroutine.

Fetch the active charity campaign of a broadcaster.

Note

Requires user access token that includes the channel:read:charity scope.

Returns: A CharityCampaign object.
Return type: CharityCampaign

fetch_charity_donations(*, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[CharityDonation]¶

This function returns a HTTPAsyncIterator

Fetches information about all broadcasts on Twitch.

Note

Requires user access token that includes the channel:read:charity scope.

Parameters

first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Return type

HTTPAsyncIterator[CharityDonation]

async fetch_chatters(*, moderator: str | int | PartialUser, first: int = 100, max_results: int | None = None) → Chatters¶

This function is a coroutine.

Fetches users that are connected to the broadcaster’s chat session.

Note

Requires user access token that includes the moderator:read:chatters scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or one of the broadcaster’s moderators. This ID must match the user ID in the user access token.
first (int | None) – 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 1,000. The default is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

A Chatters object containing the information of a broadcaster’s connected chatters.

Return type

Chatters

async fetch_channel_emotes(token_for: str | PartialUser | None = None) → list[ChannelEmote]¶

This function is a coroutine.

Fetches the broadcaster’s list of custom emotes.

Broadcasters create these custom emotes for users who subscribe to or follow the channel or cheer Bits in the channel’s chat window.

Parameters: token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used.
Returns: A list of ChannelEmote objects
Return type: list[ChannelEmote]

fetch_user_emotes(*, broadcaster: str | int | PartialUser | None = None, max_results: int | None = None) → HTTPAsyncIterator[UserEmote]¶

This function returns a HTTPAsyncIterator

Fetches the broadcaster’s list of custom emotes.

Broadcasters create these custom emotes for users who subscribe to or follow the channel or cheer Bits in the channel’s chat window.

Note

Requires user access token that includes the user:read:emotes scope.

Parameters

broadcaster (str | int | PartialUser | None) – The User ID, or PartialUser, of a broadcaster you wish to get follower emotes of. Using this query parameter will guarantee inclusion of the broadcaster’s follower emotes in the response body.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Return type

HTTPAsyncIterator[UserEmote]

async fetch_badges(token_for: str | PartialUser | None = None) → list[ChatBadge]¶

This function is a coroutine.

Fetches the broadcaster’s list of custom chat badges.

If you wish to fetch globally available chat badges use If you wish to fetch a specific broadcaster’s chat badges use [client.fetch_badges][twitchio.client.fetch_badges]

Parameters: token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used.
Returns: A list of ChatBadge objects belonging to the user.
Return type: list[ChatBadge]

This function is a coroutine.

Fetches the broadcaster’s chat settings.

Note

If you wish to view non_moderator_chat_delay and non_moderator_chat_delay_duration then you will need to provide a moderator, which can be either the broadcaster’s or a moderators’. The token must include the moderator:read:chat_settings scope.

Parameters

moderator (str | int | PartialUser | None) – The ID, or PartialUser, of the broadcaster or one of the broadcaster’s moderators. This field is only required if you want to include the non_moderator_chat_delay and non_moderator_chat_delay_duration settings in the response. If you specify this field, this ID must match the user ID in the user access token.
token_for (str | PartialUser | None) – If you need the response to contain non_moderator_chat_delay and non_moderator_chat_delay_duration then you must provide the user ID (or PartialUser) for the user in moderator so a managed user token can be selected. The required scope is moderator:read:chat_settings. Otherwise it is an optional user ID (or PartialUser) used to select a managed user token for this request.

Returns

ChatSettings object of the broadcaster’s chat settings.

Return type

ChatSettings

This function is a coroutine.

Update the user’s chat settings.

Note

To set the slow_mode_wait_time or follower_mode_duration field to its default value, set the corresponding slow_mode or follower_mode field to True (and don’t include the slow_mode_wait_time or follower_mode_duration field).
To set the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field’s value, you must set the corresponding slow_mode, follower_mode, or non_moderator_chat_delay field to True.
To remove the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field’s value, set the corresponding slow_mode, follower_mode, or non_moderator_chat_delay field to False (and don’t include the slow_mode_wait_time, follower_mode_duration, or non_moderator_chat_delay_duration field).

Note

Requires a user access token that includes the moderator:manage:chat_settings scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of a user that has permission to moderate the broadcaster’s chat room, or the broadcaster’s ID if they’re making the update. This ID must match the user ID in the user access token.
emote_mode (bool | None) – A Boolean value that determines whether chat messages must contain only emotes.
follower_mode (bool | None) – A Boolean value that determines whether the broadcaster restricts the chat room to followers only.
follower_mode_duration (int | None) – The length of time, in minutes, that users must follow the broadcaster before being able to participate in the chat room. Set only if follower_mode is True. Possible values are: 0 (no restriction) through 129600 (3 months).
slow_mode (bool | None) – A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages. Set to True if the broadcaster applies a wait period between messages; otherwise, False.
slow_mode_wait_time (int | None) – The amount of time, in seconds, that users must wait between sending messages. Set only if slow_mode is True. Possible values are: 3 (3 second delay) through 120 (2 minute delay). The default is 30 seconds.
subscriber_mode (bool | None) – A Boolean value that determines whether only users that subscribe to the broadcaster’s channel may talk in the chat room. Set to True if the broadcaster restricts the chat room to subscribers only; otherwise, False.
unique_chat_mode (bool | None) – A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room. Set to True if the broadcaster allows only unique messages; otherwise, False.
non_moderator_chat_delay (bool | None) – 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. Set to True if the broadcaster applies a delay; otherwise, False.
non_moderator_chat_delay_duration (Literal[2, 4, 6] | None) – The amount of time, in seconds, that messages are delayed before appearing in chat. Set only if non_moderator_chat_delay is True. Possible values in seconds: 2 (recommended), 4 and 6.

Returns

The newly applied chat settings.

Return type

ChatSettings

Raises

ValueError – follower_mode_duration must be below 129600
ValueError – slow_mode_wait_time must be between 3 and 120

async fetch_shared_chat_session(token_for: str | PartialUser | None = None) → SharedChatSession¶

This function is a coroutine.

Fetches the active shared chat session for a channel.

Parameters: token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used.
Returns: Object representing the user’s shared chat session.
Return type: SharedChatSession

async send_announcement(*, moderator: str | int | twitchio.user.PartialUser, message: str, color: Optional[Literal['blue', 'green', 'orange', 'purple', 'primary']] = None) → None¶

This function is a coroutine.

Sends an announcement to the broadcaster’s chat room.

Note

Requires a user access token that includes the moderator:manage:announcements scope.

Parameters

moderator (str | int | PartialUser) –
The ID, or PartialUser, of a user who has permission to moderate the broadcaster’s chat room, or the broadcaster’’s ID if they’re sending the announcement.

This ID must match the user ID in the user access token.
message (str) – The announcement to make in the broadcaster’s chat room. Announcements are limited to a maximum of 500 characters; announcements longer than 500 characters are truncated.
color (Literal["blue", "green", "orange", "purple", "primary"] | None) – An optional colour to use for the announcement. If set to "primary” or None the channels accent colour will be used instead. Defaults to None.

async send_shoutout(*, to_broadcaster: str | int | twitchio.user.PartialUser, moderator: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Sends a Shoutout to the specified broadcaster.

Note

The broadcaster may send a Shoutout once every 2 minutes. They may send the same broadcaster a Shoutout once every 60 minutes.

Note

Requires a user access token that includes the moderator:manage:shoutouts scope.

Parameters

to_broadcaster (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster that’s receiving the Shoutout.
moderator (str | int | PartialUser) – The ID, or PartialUser, 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.

This function is a coroutine.

Send a message to the broadcaster’s chat room.

The PartialUser/User object this method is called on is the broadcaster / channel the message will be sent to.

Important

Requires an App Access Token or user access token that includes the user:write:chat scope. User access token is generally recommended.

If an App Access Token is used, then additionally requires user:bot scope from chatting user, and either channel:bot scope from broadcaster or moderator status. This means creating a user token for the “bot” account with the above scopes associated to the correct Client ID. This token does not need to be used.

Tip

Chat messages can also include emoticons. To include emoticons, use the name of the emote.

The names are case sensitive. Don’t include colons around the name e.g., :bleedPurple:

If Twitch recognizes the name, Twitch converts the name to the emote before writing the chat message to the chat room.

Parameters

message (str) – The message to send. The message is limited to a maximum of 500 characters. Chat messages can also include emoticons. To include emoticons, use the name of the emote. The names are case sensitive. Don’t include colons around the name e.g., :bleedPurple:. If Twitch recognizes the name, Twitch converts the name to the emote before writing the chat message to the chat room
sender (str | int | PartialUser) – The ID, or PartialUser, of the user sending the message. This ID must match the user ID in the user access token.
token_for (str | PartialUser | None) – The user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used. You can use an App Access Token which additionally requires user:bot scope from chatting user auth scopes, and either channel:bot scope from broadcaster or moderator status.
reply_to_message_id (str | None) – The ID of the chat message being replied to.
source_only (bool | None) – Determines if the chat message is sent only to the source channel (defined by the PartialUser this is called on) during a shared chat session. This has no effect if the message is sent during a shared chat session. This parameter can only be set when utilizing an App Access Token. It cannot be specified when a User Access Token is used, and will instead result in an HTTP 400 error. If this parameter is not set, when using an App Access Token, then it will use the default that Twitch has set, which will be True after 2025-05-19.

Returns

An object containing the response from Twitch regarding the sent message.

Return type

SentMessage

Raises

ValueError – The message is limited to a maximum of 500 characters.

async update_chatter_color(color: str) → None¶

This function is a coroutine.

Updates the color used for the user’s name in chat.

Available Colors

blue
blue_violet
cadet_blue
chocolate
coral
dodger_blue
firebrick
golden_rod
green
hot_pink
orange_red
red
sea_green
spring_green
yellow_green

Note

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

Parameters: color (str) – The color to use, to see the list of colors available please refer to the docs. If the user is a Turbo or Prime member then you may specify a Hex color code e.g. #9146FF

async create_clip(*, token_for: str | PartialUser, has_delay: bool = False, title: str | None = None, duration: float | None = None) → CreatedClip¶

This function is a coroutine.

Creates a clip from the broadcaster’s stream.

This API captures up to 90 seconds of the broadcaster’s stream. The 90 seconds spans the point in the stream from when you called the API. For example, if you call the API at the 4:00 minute mark, the API captures from approximately the 3:35 mark to approximately the 4:05 minute mark. Twitch tries its best to capture 90 seconds of the stream, but the actual length may be less. This may occur if you begin capturing the clip near the beginning or end of the stream.

By default, Twitch publishes up to the last 30 seconds of the 90 seconds window and provides a default title for the clip. You can now specify the title and the duration via this method, or specify the title and the portion of the 90 seconds window that’s used for the clip by using the URL in the CreatedClip’s edit_url attribute. You can specify a clip that’s from 5 seconds to 60 seconds in length. The URL is valid for up to 24 hours or until the clip is published, whichever comes first.

Creating a clip is an asynchronous process that can take a short amount of time to complete. To determine whether the clip was successfully created, call [fetch_clips][twitchio.user.PartialUser.fetch_clips] using the clip ID that this request returned. If [fetch_clips][twitchio.user.PartialUser.fetch_clips] returns the clip, the clip was successfully created. If after 15 seconds [fetch_clips][twitchio.user.PartialUser.fetch_clips] hasn’t returned the clip, assume it failed.

Note

Requires a user access token that includes the clips:edit scope.

Warning

The has_delay argument has been removed by Twitch and no longer has any effect. It has been retained to avoid breaking changes for users who still have it set.

Parameters

title (str | None) – The title of the clip.
duration (float | None) – The length of the clip in seconds. Possible values range from 5 to 60 inclusively with a precision of 0.1. The default is 30
has_delay (bool) – This has been been removed by Twitch and no longer has any effect. It has been retained to avoid breaking changes for users who still have it set.
token_for (str | PartialUser) – The user ID (or PartialUser) used to select a managed user token for this request. The token must include the clips:edit scope.

Returns

The CreatedClip object.

Return type

CreatedClip

Raises

ValueError – Clip duration must be between 5 and 60, with precision of 0.1

This function returns a HTTPAsyncIterator

Fetches clips from the broadcaster’s streams.

Parameters

started_at (datetime.datetime) – The start date used to filter clips. This can be timezone aware.
ended_at (datetime.datetime) – The end date used to filter clips. If not specified, the time window is the start date plus one week. This can be timezone aware.
featured (bool | None = None) – If True, returns only clips that are featured. If False, returns only clips that aren’t featured. All clips are returned if this parameter is not provided.
token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used.
first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Return type

HTTPAsyncIterator[Clip]

async fetch_goals() → list[Goal]¶

This function is a coroutine.

Fetches a list of the creator’s goals.

Note

Requires a user access token that includes the channel:read:goals scope.

Returns: List of Goal objects.
Return type: list[Goal]

fetch_hype_train_events(*, first: int = 1, max_results: int | None = None) → HTTPAsyncIterator[HypeTrainEvent]¶

This function returns a HTTPAsyncIterator

Warning

This endpoint is deprecated and will stop working on 2026-01-15. Please use fetch_hype_train_status() instead. This method may be removed in a future release.

Fetches information about the broadcaster’s current or most recent Hype Train event.

Parameters

first (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 items per page. The default is 1.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of HypeTrainEvent objects.

Return type

HTTPAsyncIterator[HypeTrainEvent]

async fetch_hype_train_status() → HypeTrainStatus | None¶

This function is a coroutine.

Fetches the current Hype Train status for the broadcaster.

Note

Requires a user access token that includes the channel:read:hype_train scope.

Returns: HypeTrainStatus object if a Hype Train is currently active, otherwise None.
Return type: HypeTrainStatus | None

async start_raid(to_broadcaster: str | int | twitchio.user.PartialUser) → Raid¶

This function is a coroutine.

Starts a raid to another channel.

Note

The limit is 10 requests within a 10-minute window.

When you call the API from a chat bot or extension, the Twitch UX pops up a window at the top of the chat room that identifies the number of viewers in the raid. The raid occurs when the broadcaster clicks Raid Now or after the 90-second countdown expires.

To determine whether the raid successfully occurred, you must subscribe to the Channel Raid event.

To cancel a pending raid, use the Cancel a raid endpoint.

Note

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

Parameters: to_broadcaster (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster to raid.
Returns: Raid object.
Return type: Raid

async cancel_raid() → None¶

This function is a coroutine.

Cancel a pending raid.

You can cancel a raid at any point up until the broadcaster clicks Raid Now in the Twitch UX or the 90-second countdown expires.

Note

The limit is 10 requests within a 10-minute window.

Note

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

Returns: Raid object.
Return type: Raid

This function returns a HTTPAsyncIterator

Fetches stream schedule information for a broadcaster.

Parameters

ids (list[str] | None) – List of scheduled segments ids to return.
start_time (datetime.datetime | None) – The datetime of when to start returning segments from the schedule. This can be timezone aware.
token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used.
first (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 25 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of Schedule objects.

Return type

HTTPAsyncIterator[Schedule]

Raises

ValueError – You may specify a maximum of 100 ids.

async update_stream_schedule(*, vacation: bool, vacation_start_time: datetime.datetime | None = None, vacation_end_time: datetime.datetime | None = None, timezone: str | None = None) → None¶

This function is a coroutine.

Updates the broadcaster’s schedule settings, such as scheduling a vacation.

Note

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

Parameters

vacation (bool) – A Boolean value that indicates whether the broadcaster has scheduled a vacation. Set to True to enable Vacation Mode and add vacation dates, or False to cancel a previously scheduled vacation.
vacation_start_time (datetime.datetime | None) – Datetime of when the broadcaster’s vacation starts. Required if vacation is True. This can be timezone aware.
vacation_end_time (datetime.datetime | None) – Datetime of when the broadcaster’s vacation ends. Required if vacation is True. This can be timezone aware.
timezone (str | None) – The time zone that the broadcaster broadcasts from. Specify the time zone using IANA time zone database format (for example, America/New_York). Required if vaction is True.

Raises

ValueError – When vacation is True, all of vacation_start_time, vacation_end_time, and timezone must be provided.

async create_schedule_segment(*, start_time: datetime.datetime, timezone: str, duration: int, recurring: bool = True, category_id: str | None = None, title: str | None = None) → Schedule¶

This function is a coroutine.

Adds a single or recurring broadcast to the broadcaster’s streaming schedule.

For information about scheduling broadcasts, see Stream Schedule.

Note

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

Parameters

start_time (datetime.datetime) – Datetime that the broadcast segment starts. This can be timezone aware.
timezone (str | None) –
The time zone that the broadcaster broadcasts from. Specify the time zone using IANA time zone database format (for example, America/New_York).
duration (int) – The length of time, in minutes, that the broadcast is scheduled to run. The duration must be in the range 30 through 1380 (23 hours)
recurring (bool) – A Boolean value that determines whether the broadcast recurs weekly. Is True if the broadcast recurs weekly. Only partners and affiliates may add non-recurring broadcasts. Default is True.
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.

Raises

ValueError – Duration must be between 30 and 1380.
ValueError – Title must not be greater than 140 characters.

This function is a coroutine.

Updates a scheduled broadcast segment.

Parameters

id (str) – The ID of the broadcast segment to update.
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 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_schedule_segment(id: str) → None¶

This function is a coroutine.

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

Note

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: id (str) – The ID of the segment to remove.

async fetch_channel_teams(*, token_for: str | PartialUser | None = None) → list[ChannelTeam]¶

This function is a coroutine.

Fetches the list of Twitch teams that the broadcaster is a member of.

Parameters: token_for (str | PartialUser | None) – An optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used.
Returns: List of ChannelTeam objects.
Return type: list[ChannelTeam]

async check_automod_status(*messages: list[AutomodCheckMessage]) → list[AutoModStatus]¶

This function is a coroutine.

Checks whether AutoMod would flag the specified message for review.

Rates are limited per channel based on the account type rather than per access token.

Account type	Limit per minute	Limit per hour
Normal	5	50
Affiliate	10	100
Partner	30	300

Note

AutoMod is a moderation tool that holds inappropriate or harassing chat messages for moderators to review. Moderators approve or deny the messages that AutoMod flags; only approved messages are released to chat. AutoMod detects misspellings and evasive language automatically.

For information about AutoMod, see How to Use AutoMod.

Note

Requires a user access token that includes the moderation:read scope.

Examples

my_user_id = "21734222"
user = await client.fetch_user(id=my_user_id)

msg_checks: list[AutomodCheckMessage]  = [AutomodCheckMessage(id="1234", text="Some Text"), AutomodCheckMessage(id="12345", text="Some More Text")]

checks: list[AutoModStatus] = await user.check_automod_status(messages=msg_checks, token_for=my_user_id)

Parameters: *messages (twitchio.AutomodCheckMessage) – An argument list of AutomodCheckMessage objects.
Returns: List of AutoModStatus objects.
Return type: list[AutoModStatus]

async approve_automod_messages(msg_id: str) → None¶

This function is a coroutine.

Allow the message that AutoMod flagged for review.

The PartialUser / User object to perform this task is the moderator.

Note

Requires a user access token that includes the moderator:manage:automod scope.

Parameters: msg_id (str) – The ID of the message to allow.

async deny_automod_messages(msg_id: str) → None¶

This function is a coroutine.

Deny the message that AutoMod flagged for review.

The PartialUser / User object to perform this task is the moderator.

Note

Requires a user access token that includes the moderator:manage:automod scope.

Parameters: msg_id (str) – The ID of the message to deny.

async fetch_automod_settings(*, moderator: str | int | PartialUser) → AutomodSettings¶

This function is a coroutine.

Fetches the broadcaster’s AutoMod settings.

The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Note

Requires a user access token that includes the moderator:read:automod_settings scope.

Parameters: moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
Returns: AutomodSettings object.
Return type: AutomodSettings

async update_automod_settings(*, moderator: str | int | PartialUser, settings: AutomodSettings) → AutomodSettings¶

This function is a coroutine.

Updates the broadcaster’s AutoMod settings.

The settings are used to automatically block inappropriate or harassing messages from appearing in the broadcaster’s chat room.

Perform a fetch with fetch_automod_settings() to obtain the AutomodSettings object to modify and pass to this method.

You may set either overall_level or the individual settings like aggression, but not both.

Setting overall_level applies default values to the individual settings. However, setting overall_level to 4 does not necessarily mean that it applies 4 to all the individual settings. Instead, it applies a set of recommended defaults to the rest of the settings. For example, if you set overall_level to 2, Twitch provides some filtering on discrimination and sexual content, but more filtering on hostility (see the first example response).

If overall_level is currently set and you update swearing to 3, overall_level will be set to null and all settings other than swearing will be set to 0. The same is true if individual settings are set and you update overall_level to 3 — all the individual settings are updated to reflect the default level.

Note that if you set all the individual settings to values that match what overall_level would have set them to, Twitch changes AutoMod to use the default AutoMod level instead of using the individual settings.

Valid values for all levels are from 0 (no filtering) through 4 (most aggressive filtering). These levels affect how aggressively AutoMod holds back messages for moderators to review before they appear in chat or are denied (not shown).

Note

Requires a user access token that includes the moderator:manage:automod_settings scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
settings (AutomodSettings) – AutomodSettings object containing the new settings for the broadcaster’s channel. You can fetch this using fetch_automod_settings()

Returns

AutomodSettings object.

Return type

AutomodSettings

fetch_banned_user(*, user_ids: list[str | int] | None = None, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[BannedUser]¶

This function returns a HTTPAsyncIterator

Fetch all users that the broadcaster has banned or put in a timeout.

Note

Requires a user access token that includes the moderation:read or moderator:manage:banned_users scope.

Parameters

user_ids (list[str | int] | None) –
A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each user you want to get. You may specify a maximum of 100 IDs.

The returned list includes only those users that were banned or put in a timeout. The list is returned in the same order that you specified the IDs.
first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of BannedUser objects.

Return type

HTTPAsyncIterator[BannedUser]

Raises

ValueError – You may only specify a maximum of 100 users.

async ban_user(*, moderator: str | PartialUser | None = None, user: str | PartialUser, reason: str | None = None) → Ban¶

This function is a coroutine.

Ban the provided user from the channel tied with this PartialUser.

Note

Requires a user access token that includes the moderator:manage:banned_users scope.

Parameters

moderator (str | PartialUser | None) –
An optional ID of or the PartialUser object of the moderator issuing this action. You must have a token stored with the moderator:manage:banned_users scope for this moderator.

If None, the ID of this PartialUser will be used.
user (str | PartialUser) – The ID of, or the PartialUser of the user to ban.
reason (str | None) – An optional reason this chatter is being banned. If provided the length of the reason must not be more than 500 characters long. Defaults to None.

Raises

ValueError – The length of the reason parameter exceeds 500 characters.
HTTPException – The request to ban the chatter failed.

Returns

The Ban object for this ban.

Return type

Ban

This function is a coroutine.

Timeout the provided user from the channel tied with this PartialUser.

Note

Requires a user access token that includes the moderator:manage:banned_users scope.

Parameters

moderator (str | PartialUser | None) –
An optional ID of or the PartialUser object of the moderator issuing this action. You must have a token stored with the moderator:manage:banned_users scope for this moderator.

If None, the ID of this PartialUser will be used.
user (str | PartialUser) – The ID of, or the PartialUser of the user to ban.
reason (str | None) – An optional reason this chatter is being banned. If provided the length of the reason must not be more than 500 characters long. Defaults to None.
duration (int) –
The duration of the timeout in seconds. The minimum duration is 1 second and the maximum is 1_209_600 seconds (2 weeks).

To end the chatters timeout early, set this field to 1, or use the unban_user() endpoint.

The default is 600 which is ten minutes.

Returns

The Timeout object.

Return type

Timeout

async unban_user(*, moderator: str | int | twitchio.user.PartialUser, user_id: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Unban a user from the broadcaster’s channel.

Note

Requires a user access token that includes the moderator:manage:banned_users scope.

Parameters

moderator (str | int | PartialUser) – The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
user_id (str | int | PartialUser) – The ID, or PartialUser, of the user to ban or put in a timeout.

This function returns a HTTPAsyncIterator

Fetches the unban requests of a broadcaster’s channel.

Note

Requires a user access token that includes the moderator:read:unban_requests or moderator:manage:unban_requests scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
status (Literal["pending", "approved", "denied", "acknowledged", "canceled"]) –
Filter by a status. Possible values are:
- pending
- approved
- denied
- acknowledged
- canceled
user (str | int | PartialUser | None) – An ID, or PartialUser, used to filter what unban requests are returned.
first (int) – The maximum number of items to return per page in response. Default 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of UnbanRequest objects.

Return type

HTTPAsyncIterator[UnbanRequest]

async resolve_unban_request(*, moderator: str | int | PartialUser, status: Literal['approved', 'denied'], unban_request_id: str, resolution_text: str | None = None) → UnbanRequest¶

This function is a coroutine.

Resolves an unban request by approving or denying it.

Note

Requires a user access token that includes the moderator:manage:unban_requests scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
status (Literal["approved", "denied"]) – Resolution status. This is either approved or denied.
unban_request_id (str) – The ID of the unban request.
resolution_text (str | None) – Message supplied by the unban request resolver. The message is limited to a maximum of 500 characters.

Returns

UnbanRequest object.

Return type

UnbanRequest

Raises

ValueError – Resolution text must be less than 500 characters.

fetch_blocked_terms(moderator: str | int | PartialUser, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[BlockedTerm]¶

This function returns a HTTPAsyncIterator

Fetches the broadcaster’s list of non-private, blocked words or phrases. These are the terms that the broadcaster or moderator added manually or that were denied by AutoMod.

Note

Requires a user access token that includes the moderator:read:blocked_terms` or ``moderator:manage:blocked_terms scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of BlockedTerm objects.

Return type

HTTPAsyncIterator[BlockedTerm]

async add_blocked_term(*, moderator: str | int | PartialUser, text: str) → BlockedTerm¶

This function is a coroutine.

Adds a word or phrase to the broadcaster’s list of blocked terms.

These are the terms that the broadcaster doesn’t want used in their chat room.

Note

Terms may include a wildcard character (*). The wildcard character must appear at the beginning or end of a word or set of characters. For example, *foo or foo*.

If the blocked term already exists, the response contains the existing blocked term.

Note

Requires a user access token that includes the moderator:manage:blocked_terms scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
text (str) –
The word or phrase to block from being used in the broadcaster’s chat room. The term must contain a minimum of 2 characters and may contain up to a maximum of 500 characters.

Terms may include a wildcard character (*). The wildcard character must appear at the beginning or end of a word or set of characters. For example, *foo or foo*.

If the blocked term already exists, the response contains the existing blocked term.

Returns

BlockedTerm object.

Return type

BlockedTerm

Raises

ValueError – Text must be more than 2 characters but less than 500 characters.

async remove_blocked_term(*, moderator: str | int | twitchio.user.PartialUser, id: str) → None¶

This function is a coroutine.

Removes the word or phrase from the broadcaster’s list of blocked terms.

Note

Requires a user access token that includes the oderator:manage:blocked_terms scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s unban requests. This ID must match the user ID in the user access token.
id (str) – The ID of the blocked term to remove from the broadcaste’s list of blocked terms.

async delete_chat_messages(*, moderator: str | int | twitchio.user.PartialUser, message_id: str | None = None) → None¶

This function is a coroutine.

Removes a single chat message or all chat messages from the broadcaster’s chat room.

Important

Restrictions:

The message must have been created within the last 6 hours.
The message must not belong to the broadcaster.
The message must not belong to another moderator.

If not specified, the request removes all messages in the broadcaster’s chat room.

Note

Requires a user access token that includes the moderator:manage:chat_messages scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.
message_id (str) – The ID of the message to remove.

fetch_moderated_channels(*, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[PartialUser]¶

This function returns a HTTPAsyncIterator

Fetches channels that the specified user has moderator privileges in.

Note

Requires a user access token that includes the user:read:moderated_channels scope. The user ID in the access token must match the broadcaster’s ID.

Parameters

first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of PartialUser objects.

Return type

HTTPAsyncIterator[PartialUser]

fetch_moderators(*, user_ids: list[str | int] | None = None, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[PartialUser]¶

This function returns a HTTPAsyncIterator

Fetches users allowed to moderate the broadcaster’s chat room.

Note

Requires a user access token that includes the moderation:read scope. If your app also adds and removes moderators, you can use the channel:manage:moderators scope instead. The user ID in the access token must match the broadcaster’s ID.

Parameters

user_ids (list[str | int] | None) – A list of user IDs used to filter the results. To specify more than one ID, include this parameter for each moderator you want to get. The returned list includes only the users from the list who are moderators in the broadcaster’s channel. You may specify a maximum of 100 IDs.
first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of PartialUser objects.

Return type

HTTPAsyncIterator[PartialUser]

Raises

ValueError – You may only specify a maximum of 100 user IDs.

async add_moderator(user: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Adds a moderator to the broadcaster’s chat room.

The broadcaster may add a maximum of 10 moderators within a 10-second window.

Note

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

Parameters: user (str | int | PartialUser) – The ID of the user to add as a moderator in the broadcaster’s chat room.

async remove_moderator(user: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Removes a moderator to the broadcaster’s chat room.

The broadcaster may remove a maximum of 10 moderators within a 10-second window.

Note

Requires a user access token that includes the channel:manage:moderators scope. The user ID in the access token must match the broadcaster’s ID.

Parameters: user (str | int | PartialUser) – The ID of the user to remove as a moderator in the broadcaster’s chat room.

fetch_vips(*, user_ids: list[str | int] | None = None, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[PartialUser]¶

This function returns a HTTPAsyncIterator

Fetches the broadcaster’s VIPs.

Note

Requires a user access token that includes the channel:read:vips scope. If your app also adds and removes moderators, you can use the channel:manage:vips scope instead. The user ID in the access token must match the broadcaster’s ID.

Parameters

user_ids (list[str | int] | None) – Filters the list for specific VIPs. You may specify a maximum of 100 IDs.
first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of PartialUser objects.

Return type

HTTPAsyncIterator[PartialUser]

Raises

ValueError – You may only specify a maximum of 100 user IDs.

async add_vip(user: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Adds a VIP to the broadcaster’s chat room.

The broadcaster may add a maximum of 10 VIPs within a 10-second window.

Note

Requires a user access token that includes the channel:manage:vips scope. The user ID in the access token must match the broadcaster’s ID.

Parameters: user (str | int) – The ID, or PartialUser, of the user to add as a VIP in the broadcaster’s chat room.

async remove_vip(user: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Removes a VIP to the broadcaster’s chat room.

The broadcaster may remove a maximum of 10 VIPs within a 10-second window.

Note

Requires a user access token that includes the channel:manage:vips scope. The user ID in the access token must match the broadcaster’s ID.

Parameters: user (str | int | PartialUser) – The ID, or PartialUser, of the user to remove as a VIP in the broadcaster’s chat room.

async update_shield_mode_status(*, moderator: str | int | PartialUser, active: bool) → ShieldModeStatus¶

This function is a coroutine.

Activates or deactivates the broadcaster’s Shield Mode.

Note

Requires a user access token that includes the moderator:manage:shield_mode scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, 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.
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

A ShieldModeStatus object.

Return type

ShieldModeStatus

async fetch_shield_mode_status(*, moderator: str | int | PartialUser) → ShieldModeStatus¶

This function is a coroutine.

Fetches the broadcaster’s Shield Mode activation status.

Note

Requires a user access token that includes the moderator:read:shield_mode or moderator:manage:shield_mode scope.

Parameters: moderator (str | int | PartialUser) – The ID, or PartialUser, 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: A ShieldModeStatus object.
Return type: ShieldModeStatus

This function is a coroutine.

Adds a suspicious user status to a chatter on the broadcaster’s channel.

Note

Requires an app access token or user access token that includes the moderator:manage:suspicious_users scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that is one of the broadcaster’s moderators.
user (str | int | PartialUser) – The ID, or PartialUser, of the user being given the suspicious status.
status (Literal["ACTIVE_MONITORING", "RESTRICTED"]) – The type of suspicious status. Possible values are: ACTIVE_MONITORING and RESTRICTED.
token_for (str | PartialUser | None) – Optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used. If provided, this should match the user in moderator and the token must include the moderator:manage:suspicious_users scope.

Returns

A SuspiciousChatUser object.

Return type

SuspiciousChatUser

This function is a coroutine.

Removes a suspicious user status from a chatter on the broadcaster’s channel.

Note

Requires an app access token or user access token that includes the moderator:manage:suspicious_users scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the broadcaster or a user that is one of the broadcaster’s moderators.
user (str | int | PartialUser) – The ID, or PartialUser, of the user being given the suspicious status.
token_for (str | PartialUser | None) – Optional user ID (or PartialUser) used to select a managed user token for this request. If None, the default app token is used. If provided, this should match the user in moderator and The token must include the moderator:manage:suspicious_users scope.

Returns

A SuspiciousChatUser object.

Return type

SuspiciousChatUser

fetch_polls(*, ids: list[str] | None = None, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[Poll]¶

This function returns a HTTPAsyncIterator

Fetches polls that the broadcaster created.

Polls are available for 90 days after they’re created.

Note

Requires a user access token that includes the channel:read:polls or channel:manage:polls scope. The user ID in the access token must match the broadcaster’s ID.

Parameters

ids (list[str] | None) – A list of IDs that identify the polls to return. You may specify a maximum of 20 IDs.
first (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 20 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of Poll objects.

Return type

HTTPAsyncIterator[Poll]

Raises

ValueError – You may only specify a maximum of 20 IDs.

async create_poll(*, title: str, choices: list[str], duration: int, channel_points_voting_enabled: bool = False, channel_points_per_vote: int | None = None) → Poll¶

This function is a coroutine.

Creates a poll that viewers in the broadcaster’s channel can vote on.

The poll begins as soon as it’s created. You may run only one poll at a time.

Note

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

Parameters

title (str) – The question that viewers will vote on. The question may contain a maximum of 60 characters.
choices (list[str]) – A list of choice titles that viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 5 choices. The title itself can only have a maximum of 25 characters.
duration (int) – The length of time (in seconds) that the poll will run for. The minimum is 15 seconds and the maximum is 1800 seconds (30 minutes).
channel_points_voting_enabled (bool) – A Boolean value that indicates whether viewers may cast additional votes using Channel Points. If True, the viewer may cast more than one vote but each additional vote costs the number of Channel Points specified in channel_points_per_vote. The default is False
channel_points_per_vote (int | None) – The number of points that the viewer must spend to cast one additional vote. The minimum is 1 and the maximum is 1000000. Only use this if channel_points_voting_enabled is True; otherwise it is ignored.

Returns

A Poll object.

Return type

Poll

Raises

ValueError – The question may contain a maximum of 60 characters.
ValueError – You must provide a minimum of 2 choices or a maximum of 5.
ValueError – Choice title may contain a maximum of 25 characters.
ValueError – Duration must be between 15 and 1800.
ValueError – Channel points per vote must be between 1 and 1000000.

async end_poll(*, id: str, status: Literal['ARCHIVED', 'TERMINATED']) → Poll¶

This function is a coroutine.

End an active poll. You have the option to end it or end it and archive it.

Status must be set to one of the below.

TERMINATED — Ends the poll before the poll is scheduled to end. The poll remains publicly visible.
ARCHIVED — Ends the poll before the poll is scheduled to end, and then archives it so it’s no longer publicly visible.

Tip

You can also call this method directly on a Poll object with [end_poll][twitchio.models.polls.Poll.end_poll]

Parameters

id (str) – The ID of the poll to end.
status (Literal["ARCHIVED", "TERMINATED"]) – The status to set the poll to. Possible case-sensitive values are: ARCHIVED and TERMINATED.

Returns

A Poll object.

Return type

Poll

fetch_predictions(*, ids: list[str] | None = None, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[Prediction]¶

This function returns a HTTPAsyncIterator

Fetches predictions that the broadcaster created.

If the number of outcomes is two, the color is BLUE for the first outcome and PINK for the second outcome. If there are more than two outcomes, the color is BLUE for all outcomes.

Note

Requires a user access token that includes the channel:read:predictions or channel:manage:predictions scope. The user ID in the access token must match the broadcaster’s ID.

Parameters

ids (list[str] | None) – A list of IDs that identify the predictions to return. You may specify a maximum of 20 IDs.
first (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 25 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of Prediction objects.

Return type

HTTPAsyncIterator[Prediction]

Raises

ValueError – You may only specify a maximum of 25 IDs.

async create_prediction(*, title: str, outcomes: list[str], prediction_window: int) → Prediction¶

This function is a coroutine.

Creates a prediction that viewers in the broadcaster’s channel can vote on.

The prediction begins as soon as it’s created. You may run only one prediction at a time.

Note

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

Parameters

title (str) – The question that viewers will vote on. The question may contain a maximum of 45 characters.
outcomes (list[str]) – A list of outcomes titles that viewers may choose from. The list must contain a minimum of 2 outcomes and up to a maximum of 10 outcomes. The title itself can only have a maximum of 25 characters.
prediction_window (int) – The length of time (in seconds) that the prediction will run for. The minimum is 30 seconds and the maximum is 1800 seconds (30 minutes).

Returns

A Prediction object.

Return type

Prediction

Raises

ValueError – The question may contain a maximum of 45 characters.
ValueError – You must provide a minimum of 2 choices or a maximum of 5.
ValueError – Choice title may contain a maximum of 25 characters.
ValueError – Duration must be between 15 and 1800.

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

This function is a coroutine.

End an active prediction.

The status to set the prediction to. Possible case-sensitive values are:

RESOLVED — The winning outcome is determined and the Channel Points are distributed to the viewers who predicted the correct outcome.
CANCELED — The broadcaster is canceling the prediction and sending refunds to the participants.
LOCKED — The broadcaster is locking the prediction, which means viewers may no longer make predictions.

The broadcaster can update an active prediction to LOCKED, RESOLVED, or CANCELED; and update a locked prediction to RESOLVED or CANCELED.

The broadcaster has up to 24 hours after the prediction window closes to resolve the prediction. If not, Twitch sets the status to CANCELED and returns the points.

A winning_outcome_id must be provided when setting to RESOLVED>

Tip

You can also call this method directly on a Prediction object with [end_poll][twitchio.models.predictions.Prediction.end_prediction]

Parameters

id (str) – The ID of the prediction to end.
Literal["RESOLVED" (status) – The status to set the prediction to. Possible case-sensitive values are: RESOLVED , CANCELED and LOCKED.
"CANCELED" – The status to set the prediction to. Possible case-sensitive values are: RESOLVED , CANCELED and LOCKED.
"LOCKED"] – The status to set the prediction to. Possible case-sensitive values are: RESOLVED , CANCELED and LOCKED.
winning_outcome_id (str) – The ID of the winning outcome. You must set this parameter if you set status to RESOLVED.

Returns

A Prediction object.

Return type

Prediction

async fetch_stream_key() → str¶

This function is a coroutine.

Fetches the channel’s stream key.

Note

Requires a user access token that includes the channel:read:stream_key scope

Returns: The channel’s stream key.
Return type: str

fetch_followed_streams(*, first: int = 100, max_results: int | None = None) → HTTPAsyncIterator[Stream]¶

This function returns a HTTPAsyncIterator

Fetches the broadcasters that the user follows and that are streaming live.

Note

Requires a user access token that includes the user:read:follows scope

Parameters

first (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 items per page. The default is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of Stream objects.

Return type

HTTPAsyncIterator[Stream]

async create_stream_marker(*, token_for: str | PartialUser, description: str | None = None) → StreamMarker¶

This function is a coroutine.

Adds a marker to a live stream.

A marker is an arbitrary point in a live stream that the broadcaster or editor wants to mark, so they can return to that spot later to create video highlights.

Important

You may not add markers:

If the stream is not live
If the stream has not enabled video on demand (VOD)
If the stream is a premiere (a live, first-viewing event that combines uploaded videos with live chat)
If the stream is a rerun of a past broadcast, including past premieres.

Note

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

Parameters

token_for (str | PartialUser) – This must be the user ID, or PartialUser, of the broadcaster or one of the broadcaster’s editors.
description (str | None) – A short description of the marker to help the user remember why they marked the location. The maximum length of the description is 140 characters.

Returns

Represents a StreamMarker

Return type

StreamMarker

Raises

ValueError – The maximum length of the description is 140 characters.

fetch_stream_markers(*, token_for: str | PartialUser, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[VideoMarkers]¶

This function returns a HTTPAsyncIterator

Fetches markers from the user’s most recent stream or from the specified VOD/video.

A marker is an arbitrary point in a live stream that the broadcaster or editor marked, so they can return to that spot later to create video highlights

Tip

To fetch by video ID please use [fetch_stream_markers][twitchio.client.fetch_stream_markers]

Note

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

Parameters

token_for (str | PartialUser) – This must be the user ID, or PartialUser, of the broadcaster or one of the broadcaster’s editors.
first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of VideoMarkers objects.

Return type

HTTPAsyncIterator[VideoMarkers]

async fetch_subscription(broadcaster: str | int | PartialUser) → UserSubscription | None¶

This function is a coroutine.

Checks whether the user subscribes to the broadcaster’s channel.

Note

Requires a user access token that includes the user:read:subscriptions scope.

Parameters: broadcaster (str | int | PartialUser) – The ID, or PartialUser, of a partner or affiliate broadcaster.
Returns: Returns UserSubscription if subscription exists; otherwise None.
Return type: UserSubscription | None
Raises: HTTPException –

async fetch_broadcaster_subscriptions(*, user_ids: list[str | int] | None = None, first: int = 20, max_results: int | None = None) → BroadcasterSubscriptions¶

This function is a coroutine.

Fetches all subscriptions for the broadcaster.

Note

Requires a user access token that includes the channel:read:subscriptions scope

Parameters

user_ids (list[str | int] | None) – Filters the list to include only the specified subscribers. You may specify a maximum of 100 subscribers.
first (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 items per page. The default is 20.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Return type

BroadcasterSubscriptions

Raises

ValueError – You may only provide a maximum of 100 user IDs.

async send_whisper(*, to_user: str | int | twitchio.user.PartialUser, message: str) → None¶

This function is a coroutine.

Send a whisper to a user.

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.

Important

The user sending the whisper must have a verified phone number (see the Phone Number setting in your Security and Privacy settings).

The API may silently drop whispers that it suspects of violating Twitch policies. (The API does not indicate that it dropped the whisper).

The message must not be empty.

The maximum message lengths are:

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.

Messages that exceed the maximum length are truncated.

Note

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

Parameters

to_user (str | int | PartialUser) – The ID or the PartialUser of the user to receive the whisper.
message (str) –
The whisper message to send. The message must not be empty.

The maximum message lengths are:
- 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.
Messages that exceed the maximum length are truncated.

async user() → User¶

This function is a coroutine.

Fetch the full User information for the PartialUser.

Returns: User object.
Return type: User

async update(description: str | None = None) → User¶

This function is a coroutine.

Update the user’s information.

Note

Requires a user access token that includes the user:edit scope.

Parameters: description (str | None) – The string to update the channel’s description to. The description is limited to a maximum of 300 characters. To remove the description then do not pass this kwarg.
Returns: User object.
Return type: User
Raises: ValueError – The description must be a maximum of 300 characters.

async fetch_auth() → UserAuthorisation¶

This function is a coroutine.

Fetches the user’s authentication information.

Returns: UserAuthorisation object.
Return type: UserAuthorisation

fetch_block_list(*, first: int = 20, max_results: int | None = None) → HTTPAsyncIterator[PartialUser]¶

This function returns a HTTPAsyncIterator

Fetches a list of users that the broadcaster has blocked.

Note

Requires a user access token that includes the user:read:blocked_users scope.

Parameters

first (int) – Maximum number of items to return per page. Default is 20. Min is 1 and Max is 100.
max_results (int | None) – Maximum number of total results to return. When this is set to None (default), then everything found is returned.

Returns

HTTPAsyncIterator of PartialUser objects.

Return type

HTTPAsyncIterator[PartialUser]

async block_user(*, user: str | int | twitchio.user.PartialUser, source: Optional[Literal['chat', 'whisper']] = None, reason: Optional[Literal['harassment', 'spam', 'other']] = None) → None¶

This function is a coroutine.

Blocks the specified user from interacting with or having contact with the broadcaster.

The user ID in the OAuth token identifies the broadcaster who is blocking the user.

Parameters

user (str | int | PartialUser) – The ID, or PartialUser, of the user to block.
source (Literal["chat", "whisper"] | None) –
The location where the harassment took place that is causing the brodcaster to block the user. Possible values are:
- chat
- whisper
reason (Literal["harassment", "spam", "other"] | None) –
The reason that the broadcaster is blocking the user. Possible values are:
- harassment
- spam
- other

Return type

None

async unblock_user(*, user: str | int | twitchio.user.PartialUser) → None¶

This function is a coroutine.

Removes the user from the broadcaster’s list of blocked users.

Parameters: user (str | int | PartialUser) – The ID, or PartialUser, of the user to unblock.
Return type: None

async fetch_active_extensions(token_for: str | twitchio.user.PartialUser | None = None) → ActiveExtensions¶

This function is a coroutine.

Fetches a user’s active extensions.

Tip

To include extensions that you have under development, you must specify a user access token that includes the user:read:broadcast or user:edit:broadcast scope.

Parameters: token_for (str | PartialUser | None) – Optional user ID (or PartialUser) used to select a managed user token for this request. To include extensions under development, The token must include the user:read:broadcast or user:edit:broadcast scope.
Returns: ActiveExtensions object.
Return type: ActiveExtensions

async warn_user(*, moderator: str | int | twitchio.user.PartialUser, user_id: str | int | twitchio.user.PartialUser, reason: str) → Warning¶

This function is a coroutine.

Warns a user in the specified broadcaster’s chat room, preventing them from chat interaction until the warning is acknowledged. New warnings can be issued to a user when they already have a warning in the channel (new warning will replace old warning).

Note

Requires a user access token that includes the moderator:manage:warnings scope. moderator id must match the user id in the user access token.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the user who requested the warning.
user_id (str | int | PartialUser) – The ID, or PartialUser, of the user being warned.
reason (str) – The reason provided for warning.

Returns

Warning object.

Return type

Warning

This function is a coroutine.

Update a specific custom reward for this broadcaster / streamer.

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

id (str) – The ID of the custom reward.
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.

async delete_custom_reward(id: str) → None¶

This function is a coroutine.

Delete a specific custom reward for this broadcaster / user.

The app 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.

Parameters: id (str) – The ID of the custom reward to delete.
Return type: None

async fetch_stream() → Stream | None¶

This function is a coroutine.

Fetches the current stream for this broadcaster / user. If the broadcaster is not streaming then it will return None.

Return type: Stream | None