User Reference¶
- asyncadd_blocked_term
- asyncadd_moderator
- 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_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
- async forfetch_moderated_channels
- async forfetch_moderators
- async forfetch_polls
- async forfetch_predictions
- asyncfetch_shared_chat_session
- asyncfetch_shield_mode_status
- 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_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(id: str | int, name: str | None = None, display_name: str | None = None, *, http: HTTPClient)¶
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.
- name¶
The user’s 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
- 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
- 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
-
await .fetch_extension_analytics(...) -> list[T]
async for item in .fetch_extension_analytics(...):
async 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
andended_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) – A user access token that includes 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
- Raises
ValueError – Both started_at and ended_at must be provided together.
-
await .fetch_game_analytics(...) -> list[T]
async for item in .fetch_game_analytics(...):
async 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
andended_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.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) – A user access token that includes the
analytics:read:extensions
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
- Raises
ValueError – Both started_at and ended_at must be provided together.
- async fetch_bits_leaderboard(token_for: str | PartialUser, 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 theperiod
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.
token_for (str | PartialUser) – User token to use that includes the
bits:read
scope.
- Returns
BitsLeaderboard object for a user’s channel.
- Return type
- 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 token to use instead of the default app token.
- Returns
ChannelInfo object representing the channel information.
- Return type
- 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.Examples
import twitchio users: list[ChannelInfo] = await client.fetch_channels([21734222]) msg_checks: list[AutomodCheckMessage] = [AutomodCheckMessage(id="1234", text="Some Text"), AutomodCheckMessage(id="12345", text="Some More Text")] checks: list[AutoModStatus] = await users[0].check_automod_status(messages=msg_checks, token_for="21734222")
- 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).
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.
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
- 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
- async fetch_followers(user: str | int | PartialUser | None = None, first: int = 20, max_results: int | None = None) ChannelFollowers ¶
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.
- Returns
A ChannelFollowers object.
- Return type
- 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.
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
- 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
orchannel:manage:redemptions
scope.- Parameters
- Returns
_description_
- Return type
- 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
-
await .fetch_charity_donations(...) -> list[T]
async for item in .fetch_charity_donations(...):
async 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
- Return type
- 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
- 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 token to use instead of the default app token.
- Returns
A list of ChannelEmote objects
- Return type
-
await .fetch_user_emotes(...) -> list[T]
async for item in .fetch_user_emotes(...):
async 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
- 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 token to use instead of the default app token.
- Returns
A list of ChatBadge objects belonging to the user.
- Return type
- async fetch_chat_settings(*, moderator: str | int | PartialUser | None = None, token_for: str | PartialUser | None = None) ChatSettings ¶
This function is a coroutine.
Fetches the broadcaster’s chat settings.
Note
If you wish to view
non_moderator_chat_delay
andnon_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 themoderator:read:chat_settings
scope. the toke- 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
andnon_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
andnon_moderator_chat_delay_duration
then you will provide a token for the user inmoderator
. The required scope ismoderator:read:chat_settings
. Otherwise it is an optional user token to use instead of the default app token.
- Returns
ChatSettings object of the broadcaster’s chat settings.
- Return type
- async update_chat_settings(moderator: str | int | PartialUser, emote_mode: bool | None = None, follower_mode: bool | None = None, follower_mode_duration: int | None = None, slow_mode: bool | None = None, slow_mode_wait_time: int | None = None, subscriber_mode: bool | None = None, unique_chat_mode: bool | None = None, non_moderator_chat_delay: bool | None = None, non_moderator_chat_delay_duration: Literal[2, 4, 6] | None = None) ChatSettings ¶
This function is a coroutine.
Update the user’s chat settings.
Note
To set the
slow_mode_wait_time
orfollower_mode_duration
field to its default value, set the correspondingslow_mode
orfollower_mode
field to True (and don’t include theslow_mode_wait_time
orfollower_mode_duration
field).To set the
slow_mode_wait_time
,follower_mode_duration
, ornon_moderator_chat_delay_duration
field’s value, you must set the correspondingslow_mode
,follower_mode
, ornon_moderator_chat_delay
field to True.To remove the
slow_mode_wait_time
,follower_mode_duration
, ornon_moderator_chat_delay_duration
field’s value, set the correspondingslow_mode
,follower_mode
, ornon_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
- Raises
ValueError – follower_mode_duration must be below 129600
ValueError – slow_mode_wait_time must be between 3 and 120
This function is a coroutine.
Fetches the active shared chat session for a channel.
- Parameters
token_for (str | PartialUser | None) – An optional user token to use instead of the default app token.
- Returns
Object representing the user’s shared chat session.
- Return type
- 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.
- async send_message(*, sender: str | int | PartialUser, message: str, token_for: str | PartialUser | None = None, reply_to_message_id: str | None = None) SentMessage ¶
This function is a coroutine.
Send a message to the broadcaster’s chat room.
Important
Requires an app access token or user access token that includes the
user:write:chat
scope. User access token is generally recommended.If app access token used, then additionally requires
user:bot scope
from chatting user, and eitherchannel: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
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.
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
token_for (str | PartialUser | None) – User access token that includes the
user:write:chat
scope. You can use an app access token which additionally requiresuser:bot scope
from chatting user, and eitherchannel:bot scope
from broadcaster or moderator status.reply_to_message_id (str | None) – The ID of the chat message being replied to.
- Returns
An object containing the response from Twitch regarding the sent message.
- Return type
- 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) 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. To specify the title and the portion of the 90 seconds window that’s used for the clip, use 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.- Parameters
has_delay (bool) – A Boolean value that determines whether the API captures the clip at the moment the viewer requests it or after a delay. If False (default), Twitch captures the clip at the moment the viewer requests it (this is the same clip experience as the Twitch UX). If True, Twitch adds a delay before capturing the clip (this basically shifts the capture window to the right slightly).
token_for (str | PartialUser) – User access token that includes the
clips:edit
scope.
- Returns
The CreatedClip object.
- Return type
CreatedClip
-
await .fetch_clips(...) -> list[T]
async for item in .fetch_clips(...):
async fetch_clips(*, started_at: datetime.datetime | None = None, ended_at: datetime.datetime | None = None, featured: bool | None = None, token_for: str | PartialUser | None = None, first: int = 20, max_results: int | None = None) HTTPAsyncIterator[Clip] ¶ 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 token to use instead of the default app token.
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
- 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.
-
await .fetch_hype_train_events(...) -> list[T]
async for item in .fetch_hype_train_events(...):
async fetch_hype_train_events(*, first: int = 1, max_results: int | None = None) HTTPAsyncIterator[HypeTrainEvent] ¶ This function returns a
HTTPAsyncIterator
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
- 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
- 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
-
await .fetch_stream_schedule(...) -> list[T]
async for item in .fetch_stream_schedule(...):
async fetch_stream_schedule(*, ids: list[str] | None = None, token_for: str | PartialUser | None = None, start_time: datetime.datetime | None = None, first: int = 20, max_results: int | None = None) HTTPAsyncIterator[Schedule] ¶ 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 token to use instead of the default app 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 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
- 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.
- async update_schedule_segment(*, id: str, 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.
- 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
- 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 token to use instead of the default app token.
- Returns
List of ChannelTeam objects.
- Return type
- 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.- Parameters
*messages (
twitchio.AutomodCheckMessage
) – An argument list of AutomodCheckMessage objects.- Returns
List of AutoModStatus objects.
- Return type
- 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
- 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 theAutomodSettings
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
-
await .fetch_banned_user(...) -> list[T]
async for item in .fetch_banned_user(...):
async 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
ormoderator: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
- 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 themoderator: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
- async timeout_user(*, moderator: str | int | PartialUser | None, user: str | PartialUser | None, duration: int, reason: str | None = None) Timeout ¶
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 themoderator: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 is1_209_600
seconds (2 weeks).To end the chatters timeout early, set this field to
1
, or use theunban_user()
endpoint.The default is
600
which is ten minutes.
- Returns
The
Timeout
object.- Return type
- 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.
-
await .fetch_unban_requests(...) -> list[T]
async for item in .fetch_unban_requests(...):
async fetch_unban_requests(*, moderator: str | int | PartialUser, status: Literal['pending', 'approved', 'denied', 'acknowledged', 'canceled'], user: str | int | PartialUser | None = None, first: int = 20, max_results: int | None = None) HTTPAsyncIterator[UnbanRequest] ¶ 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
ormoderator: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
- 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
ordenied
.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
- Raises
ValueError – Resolution text must be less than 500 characters.
-
await .fetch_blocked_terms(...) -> list[T]
async for item in .fetch_blocked_terms(...):
async 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
- 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
orfoo*
.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
orfoo*
.If the blocked term already exists, the response contains the existing blocked term.
- Returns
BlockedTerm object.
- Return type
- 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.
token_for (str | PartialUser) – User access token that includes the
moderator:manage:chat_messages
scope.message_id (str) – The ID of the message to remove.
-
await .fetch_moderated_channels(...) -> list[T]
async for item in .fetch_moderated_channels(...):
async 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
-
await .fetch_moderators(...) -> list[T]
async for item in .fetch_moderators(...):
async 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 thechannel: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.
token_for (str | PartialUser) – User access token that includes the
moderation:read
scope. If your app also adds and removes moderators, you can use thechannel:manage:moderators
scope instead. The user ID in the access token must match the broadcaster’s ID.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
- 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.
-
await .fetch_vips(...) -> list[T]
async for item in .fetch_vips(...):
async 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 thechannel: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
- 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.
- 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.
- 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
ormoderator: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.
-
await .fetch_polls(...) -> list[T]
async for item in .fetch_polls(...):
async 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
orchannel: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
- 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 Falsechannel_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
- 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]
-
await .fetch_predictions(...) -> list[T]
async for item in .fetch_predictions(...):
async 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
orchannel: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
- 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
- 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
andLOCKED
."CANCELED" – The status to set the prediction to. Possible case-sensitive values are:
RESOLVED
,CANCELED
andLOCKED
."LOCKED"] – The status to set the prediction to. Possible case-sensitive values are:
RESOLVED
,CANCELED
andLOCKED
.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
- 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
-
await .fetch_followed_streams(...) -> list[T]
async for item in .fetch_followed_streams(...):
async 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
- 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
- Raises
ValueError – The maximum length of the description is 140 characters.
-
await .fetch_stream_markers(...) -> list[T]
async for item in .fetch_stream_markers(...):
async 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
orchannel: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
- 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
- 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
- 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
- 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
- Raises
ValueError – The description must be a maximum of 300 characters.
-
await .fetch_block_list(...) -> list[T]
async for item in .fetch_block_list(...):
async 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
- Returns
HTTPAsyncIterator of PartialUser objects.
- Return type
- 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
oruser:edit:broadcast
scope.- Parameters
token_for (str | PartialUser | None) – Optional user access token. To include extensions that you have under development, you must specify a user access token that includes the
user:read:broadcast
oruser: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
- async update_custom_reward(id: str, *, title: str | None = None, cost: int | None = None, prompt: str | None = None, enabled: bool | None = None, colour: str | 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 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 toTrue
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
- 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
- class twitchio.User(data: UsersResponseData, *, http: HTTPClient)¶
Represents a User.
This class inherits from PartialUser and contains additional information about the user.
- name¶
The user’s name. In most cases, this is provided. There are however, rare cases where it is not.
- Type
str | None
- type¶
The type of the user. Possible values are:
admin - Twitch administrator
global_mod
staff - Twitch staff
empty string - Normal user
- Type
Literal[“admin”, “global_mod”, “staff”, “”]
- broadcaster_type¶
The broadcaster type of the user. Possible values are:
affiliate
partner
empty string - Normal user
- Type
Literal[“affiliate”, “partner”, “”]
- offline_image¶
Offline image as an asset, otherwise None if broadcaster as not set one.
- Type
Asset | None
- email¶
The user’s verified email address. The object includes this field only if the user access token includes the
user:read:email
scope.- Type
str | None
- created_at¶
When the user was created.
- Type
- asyncadd_blocked_term
- asyncadd_moderator
- asyncadd_vip
- asyncapprove_automod_messages
- asyncban
- asyncban_user
- asyncblock
- 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_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
- async forfetch_moderated_channels
- async forfetch_moderators
- async forfetch_polls
- async forfetch_predictions
- asyncfetch_shared_chat_session
- asyncfetch_shield_mode_status
- asyncfetch_stream_key
- async forfetch_stream_markers
- async forfetch_stream_schedule
- asyncfetch_subscription
- async forfetch_unban_requests
- async forfetch_user_emotes
- async forfetch_vips
- asyncfollow_info
- asyncmodify_channel
- asyncremove_blocked_term
- asyncremove_moderator
- asyncremove_vip
- asyncresolve_unban_request
- asyncsend_announcement
- asyncsend_message
- asyncsend_shoutout
- asyncsend_whisper
- asyncsnooze_next_ad
- asyncstart_commercial
- asyncstart_raid
- asynctimeout
- 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
- asyncwarn_user
- class twitchio.Chatter¶
Class which represents a User in a chat room and has sent a message.
This class inherits from
PartialUser
and contains additional information about the chatting user. Most of the additional information is received in the form of the badges sent by Twitch.Note
You usually wouldn’t construct this class yourself. You will receive it in
Command
callbacks, viaContext
and in theevent_message
event.- property channel: PartialUser¶
Property returning the channel in the form of a
PartialUser
this chatter belongs to.
- property staff: bool¶
A property returning a bool indicating whether the chatter is Twitch Staff.
This bool should always be
True
when the chatter is a Twitch Staff.
- property admin: bool¶
A property returning a bool indicating whether the chatter is Twitch Admin.
This bool should always be
True
when the chatter is a Twitch Admin.
- property broadcaster: bool¶
A property returning a bool indicating whether the chatter is the broadcaster.
This bool should always be
True
when the chatter is the broadcaster.
- property moderator: bool¶
A property returning a bool indicating whether the chatter is a moderator.
This bool should always be
True
when the chatter is a moderator.
- property artist: bool¶
A property returning a bool indicating whether the chatter is an artist for the channel.
- property founder: bool¶
A property returning a bool indicating whether the chatter is a founder of the channel.
- property subscriber: bool¶
A property returning a bool indicating whether the chatter is a subscriber of the channel.
- property no_audio: bool¶
A property returning a bool indicating whether the chatter is watching without audio.
- property no_video: bool¶
A property returning a bool indicating whether the chatter is watching without video.
- property partner: bool¶
A property returning a bool indicating whether the chatter is a Twitch partner.
- property colour: twitchio.utils.Colour | None¶
Property returning the colour of the chatter as a
Colour
.There is an alias for this property named
color
.Could be None if the chatter has not set a colour.
- property color: twitchio.utils.Colour | None¶
Property returning the color of the chatter as a
Colour
.There is an alias for this property named
colour
.Could be None if the chatter has not set a color.
- property badges: list[ChatMessageBadge]¶
Property returning a list of
ChatMessageBadge
associated with the chatter in this channel.
- async ban(moderator: str | PartialUser, reason: str | None = None) Ban ¶
This function is a coroutine.
Ban the chatter from the associated channel/broadcaster.
Important
This is different to the
ban_user()
as it will ban this chatter directly in the associated channel in the object.Note
You must have a user access token that includes the
moderator:manage:banned_users
scope to do this.- Parameters
moderator (str | PartialUser) – The ID of or the
PartialUser
object of the moderator issuing this action. You must have a token stored with themoderator:manage:banned_users
scope for this moderator.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.
TypeError – You can not ban the broadcaster.
HTTPException – The request to ban the chatter failed.
- Returns
The
Ban
object for this ban.- Return type
- async timeout(moderator: str | PartialUser | None = None, duration: int = 600, reason: str | None = None) Timeout ¶
This function is a coroutine.
Timeout the chatter from the associated channel/broadcaster.
Important
This is different to the
timeout_user()
as it will timeout this chatter directly in the associated channel in the object.Note
You must have a user access token that includes the
moderator:manage:banned_users
scope to do this.- Parameters
moderator (str | PartialUser | None) – The ID of or the
PartialUser
object of the moderator issuing this action. You must have a token stored with themoderator:manage:banned_users
scope for this moderator.duration (int) –
The duration of the timeout in seconds. The minimum duration is
1
second and the maximum is1_209_600
seconds (2 weeks).To end the chatters timeout early, set this field to
1
, or use theunban_user()
endpoint.The default is
600
which is ten minutes.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.
- async warn(moderator: str | twitchio.user.PartialUser, reason: str) Warning ¶
This function is a coroutine.
Send this chatter a warning, preventing them from chat interaction until the warning is acknowledged. New warnings can be issued to a chatter / user when they already have a warning in the channel (new warning will replace old warning).
Important
This is different to the
warn_user()
as it will warn this chatter directly for the associated channel in the object.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.
reason (str) – The reason provided for warning.
- Returns
Warning object.
- Return type
- async block(source: Optional[Literal['chat', 'whisper']] = None, reason: Optional[Literal['harassment', 'spam', 'other']] = None) None ¶
This function is a coroutine.
Blocks this chatter from interacting with or having contact with the broadcaster.
The user ID in the OAuth token identifies the broadcaster who is blocking the user.
Important
This is different to the
block_user()
as it will block this chatter directly from the associated channel in the object.Note
Requires a user access token that includes the
user:manage:blocked_users
scope.- Parameters
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 follow_info() ChannelFollowerEvent | None ¶
This function is a coroutine.
Check whether this Chatter is following the broadcaster. If the user is not following then this will return None.
Important
You must have a user token for the broadcaster / channel that this chatter is being checked in.
Note
Requires user access token that includes the
moderator:read:followers
scope.- Return type
ChannelFollowerEvent | None
- 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
orfoo*
.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
orfoo*
.If the blocked term already exists, the response contains the existing blocked term.
- Returns
BlockedTerm object.
- Return type
- Raises
ValueError – Text must be more than 2 characters but less than 500 characters.
- 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 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.
- 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 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 themoderator: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
- 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 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
- 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.- Parameters
*messages (
twitchio.AutomodCheckMessage
) – An argument list of AutomodCheckMessage objects.- Returns
List of AutoModStatus objects.
- Return type
- async create_clip(*, token_for: str | PartialUser, has_delay: bool = False) 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. To specify the title and the portion of the 90 seconds window that’s used for the clip, use 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.- Parameters
has_delay (bool) – A Boolean value that determines whether the API captures the clip at the moment the viewer requests it or after a delay. If False (default), Twitch captures the clip at the moment the viewer requests it (this is the same clip experience as the Twitch UX). If True, Twitch adds a delay before capturing the clip (this basically shifts the capture window to the right slightly).
token_for (str | PartialUser) – User access token that includes the
clips:edit
scope.
- Returns
The CreatedClip object.
- Return type
CreatedClip
- 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.
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
- 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 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 Falsechannel_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
- 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 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
- 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 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.
- 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
- Raises
ValueError – The maximum length of the description is 140 characters.
- 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.
token_for (str | PartialUser) – User access token that includes the
moderator:manage:chat_messages
scope.message_id (str) – The ID of the message to remove.
- 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 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 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 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]
- 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
andLOCKED
."CANCELED" – The status to set the prediction to. Possible case-sensitive values are:
RESOLVED
,CANCELED
andLOCKED
."LOCKED"] – The status to set the prediction to. Possible case-sensitive values are:
RESOLVED
,CANCELED
andLOCKED
.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
- 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
oruser:edit:broadcast
scope.- Parameters
token_for (str | PartialUser | None) – Optional user access token. To include extensions that you have under development, you must specify a user access token that includes the
user:read:broadcast
oruser:edit:broadcast
scope.- Returns
ActiveExtensions object.
- Return type
ActiveExtensions
- 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
- 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
- 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 token to use instead of the default app token.
- Returns
A list of ChatBadge objects belonging to the user.
- Return type
-
await .fetch_banned_user(...) -> list[T]
async for item in .fetch_banned_user(...):
async 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
ormoderator: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
- Raises
ValueError – You may only specify a maximum of 100 users.
- async fetch_bits_leaderboard(token_for: str | PartialUser, 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 theperiod
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.
token_for (str | PartialUser) – User token to use that includes the
bits:read
scope.
- Returns
BitsLeaderboard object for a user’s channel.
- Return type
- 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.
-
await .fetch_block_list(...) -> list[T]
async for item in .fetch_block_list(...):
async 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
- Returns
HTTPAsyncIterator of PartialUser objects.
- Return type
-
await .fetch_blocked_terms(...) -> list[T]
async for item in .fetch_blocked_terms(...):
async 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
- 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
- Raises
ValueError – You may only provide a maximum of 100 user IDs.
- 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 token to use instead of the default app token.
- Returns
A list of ChannelEmote objects
- Return type
- 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 token to use instead of the default app token.
- Returns
ChannelInfo object representing the channel information.
- Return type
- 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 token to use instead of the default app token.
- Returns
List of ChannelTeam objects.
- Return type
- 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
-
await .fetch_charity_donations(...) -> list[T]
async for item in .fetch_charity_donations(...):
async 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
- Return type
- async fetch_chat_settings(*, moderator: str | int | PartialUser | None = None, token_for: str | PartialUser | None = None) ChatSettings ¶
This function is a coroutine.
Fetches the broadcaster’s chat settings.
Note
If you wish to view
non_moderator_chat_delay
andnon_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 themoderator:read:chat_settings
scope. the toke- 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
andnon_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
andnon_moderator_chat_delay_duration
then you will provide a token for the user inmoderator
. The required scope ismoderator:read:chat_settings
. Otherwise it is an optional user token to use instead of the default app token.
- Returns
ChatSettings object of the broadcaster’s chat settings.
- Return type
- 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
-
await .fetch_clips(...) -> list[T]
async for item in .fetch_clips(...):
async fetch_clips(*, started_at: datetime.datetime | None = None, ended_at: datetime.datetime | None = None, featured: bool | None = None, token_for: str | PartialUser | None = None, first: int = 20, max_results: int | None = None) HTTPAsyncIterator[Clip] ¶ 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 token to use instead of the default app token.
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
- 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
orchannel:manage:redemptions
scope.- Parameters
- Returns
_description_
- Return type
- 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
-
await .fetch_extension_analytics(...) -> list[T]
async for item in .fetch_extension_analytics(...):
async 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
andended_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) – A user access token that includes 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
- Raises
ValueError – Both started_at and ended_at must be provided together.
- 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
-
await .fetch_followed_streams(...) -> list[T]
async for item in .fetch_followed_streams(...):
async 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
- async fetch_followers(user: str | int | PartialUser | None = None, first: int = 20, max_results: int | None = None) ChannelFollowers ¶
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.
- Returns
A ChannelFollowers object.
- Return type
-
await .fetch_game_analytics(...) -> list[T]
async for item in .fetch_game_analytics(...):
async 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
andended_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.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) – A user access token that includes the
analytics:read:extensions
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
- Raises
ValueError – Both started_at and ended_at must be provided together.
- 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.
-
await .fetch_hype_train_events(...) -> list[T]
async for item in .fetch_hype_train_events(...):
async fetch_hype_train_events(*, first: int = 1, max_results: int | None = None) HTTPAsyncIterator[HypeTrainEvent] ¶ This function returns a
HTTPAsyncIterator
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
-
await .fetch_moderated_channels(...) -> list[T]
async for item in .fetch_moderated_channels(...):
async 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
-
await .fetch_moderators(...) -> list[T]
async for item in .fetch_moderators(...):
async 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 thechannel: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.
token_for (str | PartialUser) – User access token that includes the
moderation:read
scope. If your app also adds and removes moderators, you can use thechannel:manage:moderators
scope instead. The user ID in the access token must match the broadcaster’s ID.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
- Raises
ValueError – You may only specify a maximum of 100 user IDs.
-
await .fetch_polls(...) -> list[T]
async for item in .fetch_polls(...):
async 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
orchannel: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
- Raises
ValueError – You may only specify a maximum of 20 IDs.
-
await .fetch_predictions(...) -> list[T]
async for item in .fetch_predictions(...):
async 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
orchannel: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
- Raises
ValueError – You may only specify a maximum of 25 IDs.
This function is a coroutine.
Fetches the active shared chat session for a channel.
- Parameters
token_for (str | PartialUser | None) – An optional user token to use instead of the default app token.
- Returns
Object representing the user’s shared chat session.
- Return type
- 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
ormoderator: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.
- 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
-
await .fetch_stream_markers(...) -> list[T]
async for item in .fetch_stream_markers(...):
async 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
orchannel: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
-
await .fetch_stream_schedule(...) -> list[T]
async for item in .fetch_stream_schedule(...):
async fetch_stream_schedule(*, ids: list[str] | None = None, token_for: str | PartialUser | None = None, start_time: datetime.datetime | None = None, first: int = 20, max_results: int | None = None) HTTPAsyncIterator[Schedule] ¶ 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 token to use instead of the default app 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 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
- Raises
ValueError – You may specify a maximum of 100 ids.
- 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
-
await .fetch_unban_requests(...) -> list[T]
async for item in .fetch_unban_requests(...):
async fetch_unban_requests(*, moderator: str | int | PartialUser, status: Literal['pending', 'approved', 'denied', 'acknowledged', 'canceled'], user: str | int | PartialUser | None = None, first: int = 20, max_results: int | None = None) HTTPAsyncIterator[UnbanRequest] ¶ 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
ormoderator: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
-
await .fetch_user_emotes(...) -> list[T]
async for item in .fetch_user_emotes(...):
async 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
-
await .fetch_vips(...) -> list[T]
async for item in .fetch_vips(...):
async 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 thechannel: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
- Raises
ValueError – You may only specify a maximum of 100 user IDs.
- property mention: str¶
Property returning the users display_name formatted to mention them in chat.
E.g. “@kappa”
- 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.Examples
import twitchio users: list[ChannelInfo] = await client.fetch_channels([21734222]) msg_checks: list[AutomodCheckMessage] = [AutomodCheckMessage(id="1234", text="Some Text"), AutomodCheckMessage(id="12345", text="Some More Text")] checks: list[AutoModStatus] = await users[0].check_automod_status(messages=msg_checks, token_for="21734222")
- 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).
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.
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 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 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.
- 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 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
ordenied
.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
- Raises
ValueError – Resolution text must be less than 500 characters.
- 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_message(*, sender: str | int | PartialUser, message: str, token_for: str | PartialUser | None = None, reply_to_message_id: str | None = None) SentMessage ¶
This function is a coroutine.
Send a message to the broadcaster’s chat room.
Important
Requires an app access token or user access token that includes the
user:write:chat
scope. User access token is generally recommended.If app access token used, then additionally requires
user:bot scope
from chatting user, and eitherchannel: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
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.
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
token_for (str | PartialUser | None) – User access token that includes the
user:write:chat
scope. You can use an app access token which additionally requiresuser:bot scope
from chatting user, and eitherchannel:bot scope
from broadcaster or moderator status.reply_to_message_id (str | None) – The ID of the chat message being replied to.
- Returns
An object containing the response from Twitch regarding the sent message.
- Return type
- Raises
ValueError – The message is limited to a maximum of 500 characters.
- 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.
- 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 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
- 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
- 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
- async timeout_user(*, moderator: str | int | PartialUser | None, user: str | PartialUser | None, duration: int, reason: str | None = None) Timeout ¶
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 themoderator: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 is1_209_600
seconds (2 weeks).To end the chatters timeout early, set this field to
1
, or use theunban_user()
endpoint.The default is
600
which is ten minutes.
- Returns
The
Timeout
object.- Return type
- 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.
- 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 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
- Raises
ValueError – The description must be a maximum of 300 characters.
- 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 theAutomodSettings
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
- async update_chat_settings(moderator: str | int | PartialUser, emote_mode: bool | None = None, follower_mode: bool | None = None, follower_mode_duration: int | None = None, slow_mode: bool | None = None, slow_mode_wait_time: int | None = None, subscriber_mode: bool | None = None, unique_chat_mode: bool | None = None, non_moderator_chat_delay: bool | None = None, non_moderator_chat_delay_duration: Literal[2, 4, 6] | None = None) ChatSettings ¶
This function is a coroutine.
Update the user’s chat settings.
Note
To set the
slow_mode_wait_time
orfollower_mode_duration
field to its default value, set the correspondingslow_mode
orfollower_mode
field to True (and don’t include theslow_mode_wait_time
orfollower_mode_duration
field).To set the
slow_mode_wait_time
,follower_mode_duration
, ornon_moderator_chat_delay_duration
field’s value, you must set the correspondingslow_mode
,follower_mode
, ornon_moderator_chat_delay
field to True.To remove the
slow_mode_wait_time
,follower_mode_duration
, ornon_moderator_chat_delay_duration
field’s value, set the correspondingslow_mode
,follower_mode
, ornon_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
- Raises
ValueError – follower_mode_duration must be below 129600
ValueError – slow_mode_wait_time must be between 3 and 120
- 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 update_custom_reward(id: str, *, title: str | None = None, cost: int | None = None, prompt: str | None = None, enabled: bool | None = None, colour: str | 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 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 toTrue
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
- 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 update_schedule_segment(*, id: str, 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.
- 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
- Raises
ValueError – Duration must be between 30 and 1380.
ValueError – Title must not be greater than 140 characters.
- 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.
- 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 user() User ¶
This function is a coroutine.
Fetch the full User information for the PartialUser.
- Returns
User object.
- Return type
- 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