Twitch API#
This is the base of this library, it handles authentication renewal, error handling and permission management.
Look at the Twitch API reference for a more detailed documentation on what each endpoint does.
Example Usage#
from twitchAPI.twitch import Twitch
from twitchAPI.helper import first
import asyncio
async def twitch_example():
# initialize the twitch instance, this will by default also create a app authentication for you
twitch = await Twitch('app_id', 'app_secret')
# call the API for the data of your twitch user
# this returns a async generator that can be used to iterate over all results
# but we are just interested in the first result
# using the first helper makes this easy.
user = await first(twitch.get_users(logins='your_twitch_user'))
# print the ID of your user or do whatever else you want with it
print(user.id)
await twitch.close()
# run this example
asyncio.run(twitch_example())
Working with the API results#
The API returns a few different types of results.
TwitchObject#
A lot of API calls return a child of TwitchObject
in some way (either directly or via generator).
You can always use the to_dict()
method to turn that object to a dictionary.
Example:
blocked_term = await twitch.add_blocked_term('broadcaster_id', 'moderator_id', 'bad_word')
print(blocked_term.id)
IterTwitchObject#
Some API calls return a special type of TwitchObject. These usually have some list inside that you may want to dicrectly itterate over in your API usage but that also contain other usefull data outside of that List.
Example:
lb = await twitch.get_bits_leaderboard()
print(lb.total)
for e in lb:
print(f'#{e.rank:02d} - {e.user_name}: {e.score}')
AsyncIterTwitchObject#
A few API calls will have usefull data outside of the list the pagination itterates over. For those cases, this object exist.
Example:
schedule = await twitch.get_channel_stream_schedule('user_id')
print(schedule.broadcaster_name)
async for segment in schedule:
print(segment.title)
AsyncGenerator#
AsyncGenerators are used to automatically itterate over all possible resuts of your API call, this will also automatically handle pagination for you.
In some cases (for example stream schedules with repeating entries), this may result in a endless stream of entries returned so make sure to add your own
exit conditions in such cases.
The generated objects will always be children of TwitchObject
, see the docs of the API call to see the exact object type.
Example:
async for tag in twitch.get_all_stream_tags():
print(tag.tag_id)
Authentication#
The Twitch API knows 2 different authentications. App and User Authentication. Which one you need (or if one at all) depends on what calls you want to use.
Its always good to get at least App authentication even for calls where you don’t need it since the rate limits are way better for authenticated calls.
App Authentication#
By default, The lib will try to attempt to create a App Authentication on Initialization:
from twitchAPI.twitch import Twitch
twitch = await Twitch('my_app_id', 'my_app_secret')
You can set a Auth Scope like this:
from twitchAPI.twitch import Twitch, AuthScope
twitch = await Twitch('my_app_id', 'my_app_secret', target_app_auth_scope=[AuthScope.USER_EDIT])
If you want to change the AuthScope later use this:
await twitch.authenticate_app(my_new_scope)
If you don’t want to use App Authentication, Initialize like this:
from twitchAPI.twitch import Twitch
twitch = await Twitch('my_app_id', authenticate_app=False)
User Authentication#
Only use a user auth token, use this:
from twitchAPI.twitch import Twitch
twitch = await Twitch('my_app_id', authenticate_app=False)
# make sure to set the second parameter as the scope used to generate the token
await twitch.set_user_authentication('token', [], 'refresh_token')
Use both App and user Authentication:
from twitchAPI.twitch import Twitch
twitch = await Twitch('my_app_id', 'my_app_secret')
# make sure to set the second parameter as the scope used to generate the token
await twitch.set_user_authentication('token', [], 'refresh_token')
To get a user auth token, the user has to explicitly click “Authorize” on the twitch website. You can use various online services to generate a token or use my build in authenticator.
See twitchAPI.oauth
for more info on my build in authenticator.
Authentication refresh callback#
Optionally you can set a callback for both user access token refresh and app access token refresh.
from twitchAPI.twitch import Twitch
async def user_refresh(token: str, refresh_token: str):
print(f'my new user token is: {token}')
async def app_refresh(token: str):
print(f'my new app token is: {token}')
twitch = await Twitch('my_app_id', 'my_app_secret')
twitch.app_auth_refresh_callback = app_refresh
twitch.user_auth_refresh_callback = user_refresh
Class Documentation#
- class twitchAPI.twitch.Twitch#
Bases:
object
Twitch API client
- __init__(app_id, app_secret=None, authenticate_app=True, target_app_auth_scope=None, base_url='https://api.twitch.tv/helix/')#
- Parameters:
app_id (
str
) – Your app idapp_secret (
Optional
[str
]) – Your app secret, leave as None if you only want to use User AuthenticationDefault:None
authenticate_app (
bool
) – If true, auto generate a app token on startupDefault:True
target_app_auth_scope (
Optional
[List
[AuthScope
]]) – AuthScope to use ifauthenticate_app
is TrueDefault:None
base_url (
str
) – The URL to the Twitch APIDefault:TWITCH_API_BASE_URL
-
user_auth_refresh_callback:
Optional
[Callable
[[str
,str
],Awaitable
[None
]]]# If set, gets called whenever a user auth token gets refreshed. Parameter: Auth Token, Refresh Token
Default:None
-
app_auth_refresh_callback:
Optional
[Callable
[[str
],Awaitable
[None
]]]# If set, gets called whenever a app auth token gets refreshed. Parameter: Auth Token
Default:None
-
auto_refresh_auth:
bool
# If set to true, auto refresh the auth token once it expires.
Default:True
- async close()#
Gracefully close the connection to the Twitch API
- async refresh_used_token()#
Refreshes the currently used token
- async authenticate_app(scope)#
Authenticate with a fresh generated app token
- Parameters:
scope (
List
[AuthScope
]) – List of Authorization scopes to use- Raises:
TwitchAuthorizationException – if the authentication fails
- Return type:
- Returns:
None
- async set_app_authentication(token, scope)#
Set a app token, most likely only used for testing purposes
- async set_user_authentication(token, scope, refresh_token=None, validate=True)#
Set a user token to be used.
- Parameters:
token (
str
) – the generated user tokenscope (
List
[AuthScope
]) – List of Authorization Scopes that the given user token hasrefresh_token (
Optional
[str
]) – The generated refresh token, has to be provided ifauto_refresh_auth
is TrueDefault:None
validate (
bool
) – if true, validate the set token for being a user auth token and having the required scopeDefault:True
- Raises:
ValueError – if
auto_refresh_auth
is True but refresh_token is not setMissingScopeException – if given token is missing one of the required scopes
InvalidTokenException – if the given token is invalid or for a different client id
- get_app_token()#
Returns the app token that the api uses or None when not authenticated.
- get_user_auth_token()#
Returns the current user auth token, None if no user Authentication is set
- get_used_token()#
Returns the currently used token, can be either the app or user auth Token or None if no auth is set
- async get_extension_analytics(after=None, extension_id=None, first=20, ended_at=None, started_at=None, report_type=None)#
Gets a URL that extension developers can use to download analytics reports (CSV files) for their extensions. The URL is valid for 5 minutes.
Requires User authentication with scope
ANALYTICS_READ_EXTENSION
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-extension-analytics
- Parameters:
after (
Optional
[str
]) – cursor for forward paginationDefault:None
extension_id (
Optional
[str
]) – If this is specified, the returned URL points to an analytics report for just the specified extension.Default:None
first (
int
) – Maximum number of objects returned, range 1 to 100,Default:20
ended_at (
Optional
[datetime
]) – Ending date/time for returned reports, if this is provided, started_at must also be specified.Default:None
started_at (
Optional
[datetime
]) – Starting date/time for returned reports, if this is provided, ended_at must also be specified.Default:None
report_type (
Optional
[AnalyticsReportType
]) – Type of analytics report that is returnedDefault:None
- Raises:
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid
TwitchAPIException – if the request was malformed and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – When you only supply started_at or ended_at without the other or when first is not in range 1 to 100
- Return type:
- async get_game_analytics(after=None, first=20, game_id=None, ended_at=None, started_at=None, report_type=None)#
Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes.
Requires User authentication with scope
ANALYTICS_READ_GAMES
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-game-analytics
- Parameters:
after (
Optional
[str
]) – cursor for forward paginationDefault:None
first (
int
) – Maximum number of objects returned, range 1 to 100,Default:20
game_id (
Optional
[str
]) – Game IDDefault:None
ended_at (
Optional
[datetime
]) – Ending date/time for returned reports, if this is provided, started_at must also be specified.Default:None
started_at (
Optional
[datetime
]) – Starting date/time for returned reports, if this is provided, ended_at must also be specified.Default:None
report_type (
Optional
[AnalyticsReportType
]) – Type of analytics report that is returned.Default:None
- Raises:
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchAPIException – if the request was malformed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – When you only supply started_at or ended_at without the other or when first is not in range 1 to 100
- Return type:
- async get_creator_goals(broadcaster_id)#
Gets Creator Goal Details for the specified channel.
Requires User authentication with scope
CHANNEL_READ_GOALS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-creator-goals
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster that created the goals.- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
TwitchAPIException – if a Query Parameter is missing or invalid
- Return type:
- async get_bits_leaderboard(count=10, period=TimePeriod.ALL, started_at=None, user_id=None)#
Gets a ranked list of Bits leaderboard information for an authorized broadcaster.
Requires User authentication with scope
BITS_READ
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-bits-leaderboard
- Parameters:
count (
Optional
[int
]) – Number of results to be returned. In range 1 to 100,Default:10
period (
Optional
[TimePeriod
]) – Time period over which data is aggregated,Default:twitchAPI.types.TimePeriod.ALL
started_at (
Optional
[datetime
]) – Timestamp for the period over which the returned data is aggregated.Default:None
user_id (
Optional
[str
]) – ID of the user whose results are returned; i.e., the person who paid for the Bits.Default:None
- Raises:
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchAPIException – if the request was malformed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if first is not in range 1 to 100
- Return type:
- async get_extension_transactions(extension_id, transaction_id=None, after=None, first=20)#
Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch. A transaction is a record of a user exchanging Bits for an in-Extension digital good.
Requires App authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-extension-transactions
- Parameters:
extension_id (
str
) – ID of the extension to list transactions for.transaction_id (
Union
[str
,List
[str
],None
]) – Transaction IDs to look up. Can either be a list of str or strDefault:None
after (
Optional
[str
]) – cursor for forward paginationDefault:None
first (
int
) – Maximum number of objects returned, range 1 to 100,Default:20
- Raises:
UnauthorizedException – if app authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchAPIException – if the request was malformed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if first is not in range 1 to 100
ValueError – if transaction_ids is longer than 100 entries
- Return type:
- async get_chat_settings(broadcaster_id, moderator_id=None)#
Gets the broadcaster’s chat settings.
Requires App authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-chat-settings
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster whose chat settings you want to getmoderator_id (
Optional
[str
]) – Required only to access the non_moderator_chat_delay or non_moderator_chat_delay_duration settingsDefault:None
- Raises:
UnauthorizedException – if app authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchAPIException – if the request was malformed
TwitchBackendException – if the Twitch API itself runs into problems
- Return type:
- async update_chat_settings(broadcaster_id, moderator_id, emote_mode=None, follower_mode=None, follower_mode_duration=None, non_moderator_chat_delay=None, non_moderator_chat_delay_duration=None, slow_mode=None, slow_mode_wait_time=None, subscriber_mode=None, unique_chat_mode=None)#
Updates the broadcaster’s chat settings.
Requires User authentication with scope
MODERATOR_MANAGE_CHAT_SETTINGS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-chat-settings
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster whose chat settings you want to update.moderator_id (
str
) – The ID of a user that has permission to moderate the broadcaster’s chat room.emote_mode (
Optional
[bool
]) – A Boolean value that determines whether chat messages must contain only emotes.Default:None
follower_mode (
Optional
[bool
]) – A Boolean value that determines whether the broadcaster restricts the chat room to followers only, based on how long they’ve followed.Default:None
follower_mode_duration (
Optional
[int
]) – The length of time, in minutes, that the followers must have followed the broadcaster to participate in the chat roomDefault:None
non_moderator_chat_delay (
Optional
[bool
]) – A Boolean value that determines whether the broadcaster adds a short delay before chat messages appear in the chat room.Default:None
non_moderator_chat_delay_duration (
Optional
[int
]) – he amount of time, in seconds, that messages are delayed from appearing in chat. Possible Values: 2, 4 and 6Default:None
slow_mode (
Optional
[bool
]) – A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages.Default:None
slow_mode_wait_time (
Optional
[int
]) – The amount of time, in seconds, that users need to wait between sending messagesDefault:None
subscriber_mode (
Optional
[bool
]) – A Boolean value that determines whether only users that subscribe to the broadcaster’s channel can talk in the chat room.Default:None
unique_chat_mode (
Optional
[bool
]) – A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room.Default:None
- Raises:
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchAPIException – if the request was malformed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if non_moderator_chat_delay_duration is not one of 2, 4 or 6
- Return type:
- async create_clip(broadcaster_id, has_delay=False)#
Creates a clip programmatically. This returns both an ID and an edit URL for the new clip.
Requires User authentication with scope
CLIPS_EDIT
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-clip
- Parameters:
broadcaster_id (
str
) – Broadcaster ID of the stream from which the clip will be made.has_delay (
bool
) – If False, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream).Default:False
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
- Return type:
- async get_clips(broadcaster_id=None, game_id=None, clip_id=None, after=None, before=None, ended_at=None, started_at=None, first=20)#
Gets clip information by clip ID (one or more), broadcaster ID (one only), or game ID (one only). Clips are returned sorted by view count, in descending order.
Requires App or User authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-clips
- Parameters:
broadcaster_id (
Optional
[str
]) – ID of the broadcaster for whom clips are returned.Default:None
game_id (
Optional
[str
]) – ID of the game for which clips are returned.Default:None
clip_id (
Optional
[List
[str
]]) – ID of the clip being queried. Limit: 100.Default:None
first (
int
) – Maximum number of objects to return. Maximum: 100.Default:20
after (
Optional
[str
]) – Cursor for forward paginationDefault:None
before (
Optional
[str
]) – Cursor for backward paginationDefault:None
ended_at (
Optional
[datetime
]) – Ending date/time for returned clipsDefault:None
started_at (
Optional
[datetime
]) – Starting date/time for returned clipsDefault:None
- Raises:
UnauthorizedException – if user authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if you try to query more than 100 clips in one call
TwitchAPIException – if the request was malformed
ValueError – if not exactly one of clip_id, broadcaster_id or game_id is given
ValueError – if first is not in range 1 to 100
- Return type:
- async get_code_status(code, user_id)#
Gets the status of one or more provided Bits codes.
Requires App authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-code-status
- Parameters:
- Raises:
UnauthorizedException – if app authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchAPIException – if the request was malformed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if length of code is not in range 1 to 20
- Return type:
- async redeem_code(code, user_id)#
Redeems one or more provided Bits codes to the authenticated Twitch user.
Requires App authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#redeem-code
- Parameters:
- Raises:
UnauthorizedException – if app authentication is not set or invalid
TwitchAPIException – if the request was malformed
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if length of code is not in range 1 to 20
- Return type:
- async get_top_games(after=None, before=None, first=20)#
Gets games sorted by number of current viewers on Twitch, most popular first.
Requires App or User authentication
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-top-games
- Parameters:
after (
Optional
[str
]) – Cursor for forward paginationDefault:None
before (
Optional
[str
]) – Cursor for backward paginationDefault:None
first (
int
) – Maximum number of objects to return. Maximum: 100.Default:20
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if app authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if first is not in range 1 to 100
- Return type:
- async get_games(game_ids=None, names=None, igdb_ids=None)#
Gets game information by game ID or name.
Requires User or App authentication. In total, only 100 game ids and names can be fetched at once.
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-games
- Parameters:
game_ids (
Optional
[List
[str
]]) – Game IDDefault:None
names (
Optional
[List
[str
]]) – Game NameDefault:None
igdb_ids (
Optional
[List
[str
]]) – IGDB IDDefault:None
- Raises:
UnauthorizedException – if app authentication is not set or invalid
TwitchAPIException – if the request was malformed
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if none of game_ids, names or igdb_ids are given or if game_ids, names and igdb_ids are more than 100 entries combined.
- Return type:
- async check_automod_status(broadcaster_id, automod_check_entries)#
Determines whether a string message meets the channel’s AutoMod requirements.
Requires User authentication with scope
MODERATION_READ
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#check-automod-status
- Parameters:
broadcaster_id (
str
) – Provided broadcaster ID must match the user ID in the user auth token.automod_check_entries (
List
[AutoModCheckEntry
]) – The Automod Check Entries
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
- Return type:
- async get_banned_users(broadcaster_id, user_id=None, after=None, first=20, before=None)#
Returns all banned and timed-out users in a channel.
Requires User authentication with scope
MODERATION_READ
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-banned-users
- Parameters:
broadcaster_id (
str
) – Provided broadcaster ID must match the user ID in the user auth token.user_id (
Optional
[str
]) – Filters the results and only returns a status object for users who are banned in this channel and have a matching user_id.Default:None
after (
Optional
[str
]) – Cursor for forward paginationDefault:None
before (
Optional
[str
]) – Cursor for backward paginationDefault:None
first (
Optional
[int
]) – Maximum number of objects to return. Maximum: 100.Default:20
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if first is not in range 1 to 100
- Return type:
- async ban_user(broadcaster_id, moderator_id, user_id, reason, duration=None)#
Bans a user from participating in a broadcaster’s chat room, or puts them in a timeout.
Requires User authentication with scope
MODERATOR_MANAGE_BANNED_USERS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#ban-user
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster whose chat room the user is being banned from.moderator_id (
str
) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.user_id (
str
) – The ID of the user to ban or put in a timeout.reason (
str
) – The reason the user is being banned or put in a timeout. The text is user defined and limited to a maximum of 500 characters.duration (
Optional
[int
]) – To ban a user indefinitely, don’t set this. Put a user in timeout for the number of seconds specified. Maximum 1_209_600 (2 weeks)Default:None
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if duration is set and not between 1 and 1_209_600
ValueError – if reason is not between 1 and 500 characters in length
- Return type:
- async unban_user(broadcaster_id, moderator_id, user_id)#
Removes the ban or timeout that was placed on the specified user
Requires User authentication with scope
MODERATOR_MANAGE_BANNED_USERS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#unban-user
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster whose chat room the user is banned from chatting in.moderator_id (
str
) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.user_id (
str
) – The ID of the user to remove the ban or timeout from.
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
- Return type:
- async get_blocked_terms(broadcaster_id, moderator_id, after=None, first=None)#
Gets 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.
Requires User authentication with scope
MODERATOR_READ_BLOCKED_TERMS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-blocked-terms
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster whose blocked terms you’re getting.moderator_id (
str
) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.after (
Optional
[str
]) – The cursor used to get the next page of results.Default:None
first (
Optional
[int
]) – The maximum number of blocked terms to return per page in the response. Maximum 100Default:None
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if first is set and not between 1 and 100
- Return type:
- async add_blocked_term(broadcaster_id, moderator_id, text)#
Adds a word or phrase to the broadcaster’s list of blocked terms. These are the terms that broadcasters don’t want used in their chat room.
Requires User authentication with scope
MODERATOR_MANAGE_BLOCKED_TERMS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#add-blocked-term
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster that owns the list of blocked terms.moderator_id (
str
) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.text (
str
) – The word or phrase to block from being used in the broadcaster’s chat room. Between 2 and 500 characters long
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if text is not between 2 and 500 characters long
- Return type:
- async remove_blocked_term(broadcaster_id, moderator_id, term_id)#
Removes the word or phrase that the broadcaster is blocking users from using in their chat room.
Requires User authentication with scope
MODERATOR_MANAGE_BLOCKED_TERMS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#remove-blocked-term
- Parameters:
broadcaster_id (
str
) – The ID of the broadcaster that owns the list of blocked terms.moderator_id (
str
) – The ID of a user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID associated with the user OAuth token.term_id (
str
) – The ID of the blocked term you want to delete.
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
- Return type:
- async get_moderators(broadcaster_id, user_ids=None, first=20, after=None)#
Returns all moderators in a channel.
Requires User authentication with scope
MODERATION_READ
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-moderators
- Parameters:
broadcaster_id (
str
) – Provided broadcaster ID must match the user ID in the user auth token.user_ids (
Optional
[List
[str
]]) – Filters the results and only returns a status object for users who are moderator in this channel and have a matching user_id. Maximum 100Default:None
after (
Optional
[str
]) – Cursor for forward paginationDefault:None
first (
Optional
[int
]) – Maximum number of objects to return. Maximum: 100.Default:20
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if user_ids has more than 100 entries
ValueError – if first is not in range 1 to 100
- Return type:
- async create_stream_marker(user_id, description=None)#
Creates a marker in the stream of a user specified by user ID.
Requires User authentication with scope
CHANNEL_MANAGE_BROADCAST
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-stream-marker
- Parameters:
user_id (
str
) – ID of the broadcaster in whose live stream the marker is created.description (
Optional
[str
]) – Description of or comments on the marker. Max length is 140 characters.Default:None
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if user authentication is not set or invalid
MissingScopeException – if the user authentication is missing the required scope
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if description has more than 140 characters
- Return type:
- async get_streams(after=None, before=None, first=20, game_id=None, language=None, user_id=None, user_login=None)#
Gets information about active streams. Streams are returned sorted by number of current viewers, in descending order. Across multiple pages of results, there may be duplicate or missing streams, as viewers join and leave streams.
Requires App or User authentication.
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-streams
- Parameters:
after (
Optional
[str
]) – Cursor for forward paginationDefault:None
before (
Optional
[str
]) – Cursor for backward paginationDefault:None
first (
int
) – Maximum number of objects to return. Maximum: 100.Default:20
game_id (
Optional
[List
[str
]]) – Returns streams broadcasting a specified game ID. You can specify up to 100 IDs.Default:None
language (
Optional
[List
[str
]]) – Stream language. You can specify up to 100 languages.Default:None
user_id (
Optional
[List
[str
]]) – Returns streams broadcast by one or more specified user IDs. You can specify up to 100 IDs.Default:None
user_login (
Optional
[List
[str
]]) – Returns streams broadcast by one or more specified user login names. You can specify up to 100 names.Default:None
- Raises:
TwitchAPIException – if the request was malformed
UnauthorizedException – if app authentication is not set or invalid
TwitchAuthorizationException – if the used authentication token became invalid and a re authentication failed
TwitchBackendException – if the Twitch API itself runs into problems
ValueError – if first is not in range 1 to 100 or one of the following fields have more than 100 entries: user_id, game_id, language, user_login
- Return type:
- async get_stream_markers(user_id, video_id, after=None, before=None, first=20)#
Gets a list of markers for either a specified user’s most recent stream or a specified VOD/video (stream), ordered by recency.
Requires User authentication with scope
USER_READ_BROADCAST
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-stream-markers
Only one of user_id and video_id must be specified.
-
auto_refresh_auth:
-
app_auth_refresh_callback: