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 directly iterate over in your API usage but that also contain other useful 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 useful data outside of the list the pagination iterates 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 iterate over all possible results 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/', auth_base_url='https://id.twitch.tv/oauth2/', session_timeout=_SENTINEL.sentinel)#
- Parameters:
app_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
auth_base_url¶ (
str
) – The URL to the Twitch API auth serverDefault:TWITCH_AUTH_BASE_URL
session_timeout¶ (
Union
[object
,ClientTimeout
]) – Override the time in seconds before any request times out. Defaults to aiohttp default (300 seconds)-
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
-
session_timeout:
Union
[object
,ClientTimeout
]# Override the time in seconds before any request times out. Defaults to aiohttp default (300 seconds)
-
auto_refresh_auth:
bool
# If set to true, auto refresh the auth token once it expires.
Default:True
- async static 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:
scope¶ (
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
- async get_refreshed_user_auth_token()#
Validates the current set user auth token and returns it
Will reauth if token is invalid
- 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:
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
extension_id¶ (
Optional
[str
]) – If this is specified, the returned URL points to an analytics report for just the specified extension.Default:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, Maximum 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
TwitchResourceNotFound – if the extension specified in extension_id was not found
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:
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, Maximum 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
TwitchResourceNotFound – if the game specified in game_id was not found
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
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, Maximum 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
TwitchResourceNotFound – if one or more transaction IDs specified in transaction_id where not found
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
TwitchResourceNotFound – if the broadcaster is not live
- Return type:
- async get_clips(broadcaster_id=None, game_id=None, clip_id=None, is_featured=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
is_featured¶ (
Optional
[bool
]) – A Boolean value that determines whether the response includes featured clips.
IfTrue
, returns only clips that are featured.
IfFalse
, returns only clips that aren’t featured.
IfNone
, all clips are returned.Default:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, Maximum 100
Default:20
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default: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
TwitchResourceNotFound – if the game specified in game_id was not found
- 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:
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
before¶ (
Optional
[str
]) – Cursor for backward paginationDefault:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, 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_automod_settings(broadcaster_id, moderator_id)#
Gets the broadcaster’s AutoMod settings.
Requires User Authentication with
MODERATOR_READ_AUTOMOD_SETTINGS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-automod-settings
- Parameters:
- 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
TwitchAPIException – if a Query Parameter is missing or invalid
- Return type:
- async update_automod_settings(broadcaster_id, moderator_id, settings=None, overall_level=None)#
Updates the broadcaster’s AutoMod settings.
You can either set the individual level or the overall level, but not both at the same time. Setting the overall_level parameter in settings will be ignored.
Requires User Authentication with
MODERATOR_MANAGE_AUTOMOD_SETTINGS
For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-automod-settings
- Parameters:
broadcaster_id¶ (
str
) – The ID of the broadcaster whose AutoMod settings you want to update.moderator_id¶ (
str
) – The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room.settings¶ (
Optional
[AutoModSettings
]) – If you want to change individual settings, set this.Default:None
overall_level¶ (
Optional
[int
]) – If you want to change the overall level, set this.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
TwitchAPIException – if a Query Parameter is missing or invalid
ValueError – if both settings and overall_level are given or none of them are given
- 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
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
before¶ (
Optional
[str
]) – Cursor for backward paginationDefault:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, 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.Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, Maximum 100
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 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
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, 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
TwitchResourceNotFound – if the user in user_id is not live, the ID is not valid or has not enabled VODs
- Return type:
- async get_streams(after=None, before=None, first=20, game_id=None, language=None, user_id=None, user_login=None, stream_type=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:
Cursor for forward pagination.
Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.
Default:None
before¶ (
Optional
[str
]) – Cursor for backward paginationDefault:None
The maximum number of items to return per API call. You can use this in combination with
limit()
to optimize the bandwidth and number of API calls used to fetch the amount of results you desire.Minimum 1, Maximum 100
-
session_timeout:
-
app_auth_refresh_callback: