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/', auth_base_url='https://id.twitch.tv/oauth2/', session_timeout=_SENTINEL.sentinel)#
Parameters:
  • app_id (str) – Your app id

  • app_secret (Optional[str]) – Your app secret, leave as None if you only want to use User Authentication

    Default: None

  • authenticate_app (bool) – If true, auto generate a app token on startup

    Default: True

  • target_app_auth_scope (Optional[List[AuthScope]]) – AuthScope to use if authenticate_app is True

    Default: None

  • base_url (str) – The URL to the Twitch API

  • auth_base_url (str) – The URL to the Twitch API auth server

  • session_timeout (Union[object, ClientTimeout]) – Override the time in seconds before any request times out. Defaults to aiohttp default (300 seconds)

logger: Logger#

The logger used for Twitch API call related log messages

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

base_url: str#

The URL to the Twitch API used

async static close()#

Gracefully close the connection to the Twitch API

get_user_auth_scope()#
Return type:

List[AuthScope]

Returns the set User auth Scope

has_required_auth(required_type, required_scope)#
Return type:

bool

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:

None

Returns:

None

async set_app_authentication(token, scope)#

Set a app token, most likely only used for testing purposes

Parameters:
  • token (str) – the app token

  • scope (List[AuthScope]) – List of Authorization scopes that the given app token has

async set_user_authentication(token, scope, refresh_token=None, validate=True)#

Set a user token to be used.

Parameters:
  • token (str) – the generated user token

  • scope (List[AuthScope]) – List of Authorization Scopes that the given user token has

  • refresh_token (Optional[str]) – The generated refresh token, has to be provided if auto_refresh_auth is True

    Default: None

  • validate (bool) – if true, validate the set token for being a user auth token and having the required scope

    Default: True

Raises:
get_app_token()#

Returns the app token that the api uses or None when not authenticated.

Return type:

Optional[str]

Returns:

app token

get_user_auth_token()#

Returns the current user auth token, None if no user Authentication is set

Return type:

Optional[str]

Returns:

current user auth token

async get_refreshed_user_auth_token()#
Return type:

Optional[str]

Validates the current set user auth token and returns it

Will reauth if token is invalid

async get_refreshed_app_token()#
Return type:

Optional[str]

get_used_token()#

Returns the currently used token, can be either the app or user auth Token or None if no auth is set

Return type:

Optional[str]

Returns:

the currently used auth token or None if no Authentication 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 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

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith 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 returned

    Default: None

Raises:
Return type:

AsyncGenerator[ExtensionAnalytic, None]

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

    Note: The library handles pagination on its own, only use this parameter if you get a pagination cursor via other means.

    Default: None

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith 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 ID

    Default: 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:
Return type:

AsyncGenerator[GameAnalytics, None]

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:
Return type:

AsyncGenerator[CreatorGoal, None]

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:
Return type:

BitsLeaderboard

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 str

    Default: None

  • after (Optional[str]) –

    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

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

AsyncGenerator[ExtensionTransaction, None]

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 get

  • moderator_id (Optional[str]) – Required only to access the non_moderator_chat_delay or non_moderator_chat_delay_duration settings

    Default: None

Raises:
Return type:

ChatSettings

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 room

    Default: 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 6

    Default: 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 messages

    Default: 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:
Return type:

ChatSettings

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:
Return type:

CreatedClip

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.
    If True, returns only clips that are featured.
    If False, returns only clips that aren’t featured.
    If None, all clips are returned.

    Default: None

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • after (Optional[str]) –

    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 pagination

    Default: None

  • ended_at (Optional[datetime]) – Ending date/time for returned clips

    Default: None

  • started_at (Optional[datetime]) – Starting date/time for returned clips

    Default: None

Raises:
Return type:

AsyncGenerator[Clip, None]

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

    Default: None

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

AsyncGenerator[Game, None]

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:
Raises:
Return type:

AsyncGenerator[Game, None]

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:
Return type:

AsyncGenerator[AutoModStatus, None]

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:
  • broadcaster_id (str) – The ID of the broadcaster whose AutoMod settings you want to get.

  • moderator_id (str) – The ID of the broadcaster or a user that has permission to moderate the broadcaster’s chat room.

Raises:
Return type:

AutoModSettings

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:
Return type:

AutoModSettings

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

    Default: None

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

AsyncGenerator[BannedUser, None]

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:
Return type:

BanUserResponse

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:
Return type:

bool

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]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: None

Raises:
Return type:

AsyncGenerator[BlockedTerm, None]

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:
Return type:

BlockedTerm

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:
Return type:

bool

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 100

    Default: None

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

AsyncGenerator[Moderator, None]

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:
Return type:

CreateStreamMarkerResponse

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:
  • after (Optional[str]) –

    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 pagination

    Default: None

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, 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

  • stream_type (Optional[str]) – The type of stream to filter the list of streams by. Possible values are all and live

    Default: None

Raises:
Return type:

AsyncGenerator[Stream, None]

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.

Parameters:
  • user_id (str) – ID of the broadcaster from whose stream markers are returned.

  • video_id (str) – ID of the VOD/video whose stream markers are returned.

  • after (Optional[str]) –

    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 pagination

    Default: None

  • first (int) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

AsyncGenerator[GetStreamMarkerResponse, None]

async get_broadcaster_subscriptions(broadcaster_id, user_ids=None, after=None, first=20)#

Get all of a broadcaster’s subscriptions.

Requires User authentication with scope CHANNEL_READ_SUBSCRIPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-broadcaster-subscriptions

Parameters:
  • broadcaster_id (str) – User ID of the broadcaster. Must match the User ID in the Bearer token.

  • user_ids (Optional[List[str]]) – Unique identifier of account to get subscription status of. Maximum 100 entries

    Default: None

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

BroadcasterSubscriptions

async check_user_subscription(broadcaster_id, user_id)#

Checks if a specific user (user_id) is subscribed to a specific channel (broadcaster_id).

Requires User or App Authorization with scope USER_READ_SUBSCRIPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#check-user-subscription

Parameters:
  • broadcaster_id (str) – User ID of an Affiliate or Partner broadcaster.

  • user_id (str) – User ID of a Twitch viewer.

Raises:
Return type:

UserSubscription

async get_channel_teams(broadcaster_id)#

Retrieves a list of Twitch Teams of which the specified channel/broadcaster is a member.

Requires User or App authentication.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference/#get-channel-teams

Parameters:

broadcaster_id (str) – User ID for a Twitch user.

Raises:
Return type:

List[ChannelTeam]

async get_teams(team_id=None, name=None)#

Gets information for a specific Twitch Team.

Requires User or App authentication. One of the two optional query parameters must be specified.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference/#get-teams

Parameters:
Raises:
Return type:

ChannelTeam

async get_users(user_ids=None, logins=None)#

Gets information about one or more specified Twitch users. Users are identified by optional user IDs and/or login name. If neither a user ID nor a login name is specified, the user is the one authenticated.

Requires App authentication if either user_ids or logins is provided, otherwise requires a User authentication. If you have user Authentication and want to get your email info, you also need the authentication scope USER_READ_EMAIL

If you provide user_ids and/or logins, the maximum combined entries should not exceed 100.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-users

Parameters:
  • user_ids (Optional[List[str]]) – User ID. Multiple user IDs can be specified. Limit: 100.

    Default: None

  • logins (Optional[List[str]]) – User login name. Multiple login names can be specified. Limit: 100.

    Default: None

Raises:
Return type:

AsyncGenerator[TwitchUser, None]

async get_channel_followers(broadcaster_id, user_id=None, first=None, after=None)#

Gets a list of users that follow the specified broadcaster. You can also use this endpoint to see whether a specific user follows the broadcaster.

Requires User Authentication with MODERATOR_READ_FOLLOWERS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-followers

Note

This can also be used without the required scope or just with App Authentication, but the result will only include the total number of followers in these cases.

Parameters:
  • broadcaster_id (str) – The broadcaster’s ID. Returns the list of users that follow this broadcaster.

  • user_id (Optional[str]) – A user’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this user if they follow the broadcaster. If not specified, the response contains all users that follow the broadcaster.

    Default:None

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • after (Optional[str]) –

    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

Raises:
Return type:

ChannelFollowersResult

async get_followed_channels(user_id, broadcaster_id=None, first=None, after=None)#

Gets a list of broadcasters that the specified user follows. You can also use this endpoint to see whether a user follows a specific broadcaster.

Requires User Authentication with USER_READ_FOLLOWS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-followed-channels

Parameters:
  • user_id (str) – A user’s ID. Returns the list of broadcasters that this user follows. This ID must match the user ID in the user OAuth token.

  • broadcaster_id (Optional[str]) – A broadcaster’s ID. Use this parameter to see whether the user follows this broadcaster. If specified, the response contains this broadcaster if the user follows them. If not specified, the response contains all broadcasters that the user follows.

    Default: None

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • after (Optional[str]) –

    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

Raises:
Return type:

FollowedChannelsResult

async update_user(description)#

Updates the description of the Authenticated user.

Requires User authentication with scope USER_EDIT

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-user

Parameters:

description (str) – User’s account description

Raises:
Return type:

TwitchUser

async get_user_extensions()#
Return type:

List[UserExtension]

Gets a list of all extensions (both active and inactive) for the authenticated user

Requires User authentication with scope USER_READ_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-extensions

Raises:
async get_user_active_extensions(user_id=None)#

Gets information about active extensions installed by a specified user, identified by a user ID or the authenticated user.

Requires User authentication with scope USER_READ_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-active-extensions

Parameters:

user_id (Optional[str]) – ID of the user whose installed extensions will be returned.

Default: None

Raises:
Return type:

UserActiveExtensions

async update_user_extensions(data)#

“Updates the activation state, extension ID, and/or version number of installed extensions for the authenticated user.

Requires User authentication with scope USER_EDIT_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-user-extensions

Parameters:

data (UserActiveExtensions) – The user extension data to be written

Raises:
Return type:

UserActiveExtensions

async get_videos(ids=None, user_id=None, game_id=None, after=None, before=None, first=20, language=None, period=TimePeriod.ALL, sort=SortMethod.TIME, video_type=VideoType.ALL)#

Gets video information by video ID (one or more), user ID (one only), or game ID (one only).

Requires App authentication.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-videos

Parameters:
  • ids (Optional[List[str]]) – ID of the video being queried. Limit: 100.

    Default: None

  • user_id (Optional[str]) – ID of the user who owns the video.

    Default: None

  • game_id (Optional[str]) – ID of the game the video is of.

    Default: None

  • after (Optional[str]) –

    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 pagination

    Default: None

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • language (Optional[str]) – Language of the video being queried.

    Default: None

  • period (TimePeriod) – Period during which the video was created.

    Default: TimePeriod.ALL

  • sort (SortMethod) – Sort order of the videos.

    Default: SortMethod.TIME

  • video_type (VideoType) – Type of video.

    Default: VideoType.ALL

Raises:
Return type:

AsyncGenerator[Video, None]

async get_channel_information(broadcaster_id)#

Gets channel information for users.

Requires App or user authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-information

Parameters:

broadcaster_id (Union[str, List[str]]) – ID of the channel to be returned, can either be a string or a list of strings with up to 100 entries

Raises:
Return type:

List[ChannelInformation]

async modify_channel_information(broadcaster_id, game_id=None, broadcaster_language=None, title=None, delay=None, tags=None, content_classification_labels=None, is_branded_content=None)#

Modifies channel information for users.

Requires User authentication with scope CHANNEL_MANAGE_BROADCAST

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#modify-channel-information

Parameters:
  • broadcaster_id (str) – ID of the channel to be updated

  • game_id (Optional[str]) – The current game ID being played on the channel

    Default: None

  • broadcaster_language (Optional[str]) – The language of the channel

    Default: None

  • title (Optional[str]) – The title of the stream

    Default: None

  • delay (Optional[int]) – Stream delay in seconds. Trying to set this while not being a Twitch Partner will fail!

    Default: None

  • tags (Optional[List[str]]) – A list of channel-defined tags to apply to the channel. To remove all tags from the channel, set tags to an empty array.

    Default:None

  • content_classification_labels (Optional[List[str]]) – List of labels that should be set as the Channel’s CCLs.

  • is_branded_content (Optional[bool]) – Boolean flag indicating if the channel has branded content.

Raises:
Return type:

bool

async search_channels(query, first=20, after=None, live_only=False)#

Returns a list of channels (users who have streamed within the past 6 months) that match the query via channel name or description either entirely or partially.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#search-channels

Parameters:
  • query (str) – search query

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • after (Optional[str]) –

    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

  • live_only (Optional[bool]) – Filter results for live streams only.

    Default: False

Raises:
Return type:

AsyncGenerator[SearchChannelResult, None]

async search_categories(query, first=20, after=None)#

Returns a list of games or categories that match the query via name either entirely or partially.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#search-categories

Parameters:
  • query (str) – search query

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • after (Optional[str]) –

    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

Raises:
Return type:

AsyncGenerator[SearchCategoryResult, None]

async get_stream_key(broadcaster_id)#

Gets the channel stream key for a user.

Requires User authentication with CHANNEL_READ_STREAM_KEY

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-stream-key

Parameters:

broadcaster_id (str) – User ID of the broadcaster

Raises:
Return type:

str

async start_commercial(broadcaster_id, length)#

Starts a commercial on a specified channel.

Requires User authentication with CHANNEL_EDIT_COMMERCIAL

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#start-commercial

Parameters:
  • broadcaster_id (str) – ID of the channel requesting a commercial

  • length (int) – Desired length of the commercial in seconds. , one of these: [30, 60, 90, 120, 150, 180]

Raises:
Return type:

StartCommercialResult

async get_cheermotes(broadcaster_id)#

Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat.

Requires App authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-cheermotes

Parameters:

broadcaster_id (str) – ID for the broadcaster who might own specialized Cheermotes.

Raises:
Return type:

GetCheermotesResponse

async get_hype_train_events(broadcaster_id, first=1, cursor=None)#

Gets the information of the most recent Hype Train of the given channel ID. When there is currently an active Hype Train, it returns information about that Hype Train. When there is currently no active Hype Train, it returns information about the most recent Hype Train. After 5 days, if no Hype Train has been active, the endpoint will return an empty response.

Requires App or User authentication with CHANNEL_READ_HYPE_TRAIN

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-hype-train-events

Parameters:
  • broadcaster_id (str) – User ID of the broadcaster.

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 1

  • cursor (Optional[str]) – Cursor for forward pagination

    Default: None

Raises:
Return type:

AsyncGenerator[HypeTrainEvent, None]

async get_drops_entitlements(entitlement_id=None, user_id=None, game_id=None, after=None, first=20)#

Gets a list of entitlements for a given organization that have been granted to a game, user, or both.

OAuth Token Client ID must have ownership of Game

Requires App or User authentication

See Twitch documentation for valid parameter combinations!

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-drops-entitlements

Parameters:
  • entitlement_id (Optional[str]) – Unique Identifier of the entitlement

    Default: None

  • user_id (Optional[str]) – A Twitch User ID

    Default: None

  • game_id (Optional[str]) – A Twitch Game ID

    Default: None

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

Raises:
Return type:

AsyncGenerator[DropsEntitlement, None]

async create_custom_reward(broadcaster_id, title, cost, prompt=None, is_enabled=True, background_color=None, is_user_input_required=False, is_max_per_stream_enabled=False, max_per_stream=None, is_max_per_user_per_stream_enabled=False, max_per_user_per_stream=None, is_global_cooldown_enabled=False, global_cooldown_seconds=None, should_redemptions_skip_request_queue=False)#

Creates a Custom Reward on a channel.

Requires User Authentication with CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-custom-rewards

Parameters:
  • broadcaster_id (str) – ID of the broadcaster, must be same as user_id of auth token

  • title (str) – The title of the reward

  • cost (int) – The cost of the reward

  • prompt (Optional[str]) – The prompt for the viewer when they are redeeming the reward

    Default: None

  • is_enabled (Optional[bool]) – Is the reward currently enabled, if false the reward won’t show up to viewers.

    Default: True

  • background_color (Optional[str]) – Custom background color for the reward. Format: Hex with # prefix. Example: #00E5CB.

    Default: None

  • is_user_input_required (Optional[bool]) – Does the user need to enter information when redeeming the reward.

    Default: False

  • is_max_per_stream_enabled (Optional[bool]) – Whether a maximum per stream is enabled.

    Default: False

  • max_per_stream (Optional[int]) – The maximum number per stream if enabled

    Default: None

  • is_max_per_user_per_stream_enabled (Optional[bool]) – Whether a maximum per user per stream is enabled.

    Default: False

  • max_per_user_per_stream (Optional[int]) – The maximum number per user per stream if enabled

    Default: None

  • is_global_cooldown_enabled (Optional[bool]) – Whether a cooldown is enabled.

    Default: False

  • global_cooldown_seconds (Optional[int]) – The cooldown in seconds if enabled

    Default: None

  • should_redemptions_skip_request_queue (Optional[bool]) – Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.

    Default: False

Raises:
Return type:

CustomReward

async delete_custom_reward(broadcaster_id, reward_id)#

Deletes a Custom Reward on a channel.

Requires User Authentication with CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-custom-rewards

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token

  • reward_id (str) – ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel.

Raises:
async get_custom_reward(broadcaster_id, reward_id=None, only_manageable_rewards=False)#

Returns a list of Custom Reward objects for the Custom Rewards on a channel. Developers only have access to update and delete rewards that the same/calling client_id created.

Requires User Authentication with CHANNEL_READ_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-custom-reward

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token

  • reward_id (Union[str, List[str], None]) – When used, this parameter filters the results and only returns reward objects for the Custom Rewards with matching ID. Maximum: 50

    Default: None

  • only_manageable_rewards (Optional[bool]) – When set to true, only returns custom rewards that the calling client_id can manage.

    Default: False

Raises:
Return type:

List[CustomReward]

async get_custom_reward_redemption(broadcaster_id, reward_id, redemption_id=None, status=None, sort=SortOrder.OLDEST, after=None, first=20)#

Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same client_id.

Requires User Authentication with CHANNEL_READ_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-custom-reward-redemption

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token

  • reward_id (str) – When ID is not provided, this parameter returns paginated Custom Reward Redemption objects for redemptions of the Custom Reward with ID reward_id

  • redemption_id (Optional[List[str]]) – When used, this param filters the results and only returns Custom Reward Redemption objects for the redemptions with matching ID. Maximum: 50 ids

    Default: None

  • status (Optional[CustomRewardRedemptionStatus]) – When id is not provided, this param is required and filters the paginated Custom Reward Redemption objects for redemptions with the matching status.

    Default: None

  • sort (Optional[SortOrder]) – Sort order of redemptions returned when getting the paginated Custom Reward Redemption objects for a reward.

    Default: SortOrder.OLDEST

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 50

    Default: 20

Raises:
Return type:

AsyncGenerator[CustomRewardRedemption, None]

async update_custom_reward(broadcaster_id, reward_id, title=None, prompt=None, cost=None, is_enabled=True, background_color=None, is_user_input_required=False, is_max_per_stream_enabled=False, max_per_stream=None, is_max_per_user_per_stream_enabled=False, max_per_user_per_stream=None, is_global_cooldown_enabled=False, global_cooldown_seconds=None, should_redemptions_skip_request_queue=False)#

Updates a Custom Reward created on a channel.

Requires User Authentication with CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-custom-reward

Parameters:
  • broadcaster_id (str) – ID of the broadcaster, must be same as user_id of auth token

  • reward_id (str) – ID of the reward that you want to update

  • title (Optional[str]) – The title of the reward

    Default: None

  • prompt (Optional[str]) – The prompt for the viewer when they are redeeming the reward

    Default: None

  • cost (Optional[int]) – The cost of the reward

    Default: None

  • is_enabled (Optional[bool]) – Is the reward currently enabled, if false the reward won’t show up to viewers.

    Default: true

  • background_color (Optional[str]) – Custom background color for the reward.

    Default: None Format: Hex with # prefix. Example: #00E5CB.

  • is_user_input_required (Optional[bool]) – Does the user need to enter information when redeeming the reward.

    Default: false

  • is_max_per_stream_enabled (Optional[bool]) – Whether a maximum per stream is enabled.

    Default: False

  • max_per_stream (Optional[int]) – The maximum number per stream if enabled

    Default: None

  • is_max_per_user_per_stream_enabled (Optional[bool]) – Whether a maximum per user per stream is enabled.

    Default: False

  • max_per_user_per_stream (Optional[int]) – The maximum number per user per stream if enabled

    Default: None

  • is_global_cooldown_enabled (Optional[bool]) – Whether a cooldown is enabled.

    Default: false

  • global_cooldown_seconds (Optional[int]) – The cooldown in seconds if enabled

    Default: None

  • should_redemptions_skip_request_queue (Optional[bool]) – Should redemptions be set to FULFILLED status immediately when redeemed and skip the request queue instead of the normal UNFULFILLED status.

    Default: False

Raises:
  • TwitchAPIException – if the request was malformed

  • ValueError – if is_global_cooldown_enabled is True but global_cooldown_seconds is not specified

  • ValueError – if is_max_per_stream_enabled is True but max_per_stream is not specified

  • ValueError – if is_max_per_user_per_stream_enabled is True but max_per_user_per_stream is not specified

  • 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

  • TwitchAPIException – if Channel Points are not available for the broadcaster or the custom reward belongs to a different broadcaster

  • TwitchResourceNotFound – if the custom reward specified in reward_id was not found

  • ValueError – if the given reward_id does not match a custom reward by the given broadcaster

Return type:

CustomReward

async update_redemption_status(broadcaster_id, reward_id, redemption_ids, status)#

Updates the status of Custom Reward Redemption objects on a channel that are in the UNFULFILLED status.

Requires User Authentication with CHANNEL_MANAGE_REDEMPTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-redemption-status

Parameters:
  • broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token.

  • reward_id (str) – ID of the Custom Reward the redemptions to be updated are for.

  • redemption_ids (Union[List[str], str]) – IDs of the Custom Reward Redemption to update, must match a Custom Reward Redemption on broadcaster_id’s channel Max: 50

  • status (CustomRewardRedemptionStatus) – The new status to set redemptions to.

Raises:
Return type:

CustomRewardRedemption

async get_channel_editors(broadcaster_id)#

Gets a list of users who have editor permissions for a specific channel.

Requires User Authentication with CHANNEL_READ_EDITORS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-editors

Parameters:

broadcaster_id (str) – Broadcaster’s user ID associated with the channel

Raises:
Return type:

List[ChannelEditor]

async delete_videos(video_ids)#

Deletes one or more videos. Videos are past broadcasts, Highlights, or uploads. Returns False if the User was not Authorized to delete at least one of the given videos.

Requires User Authentication with CHANNEL_MANAGE_VIDEOS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-videos

Parameters:

video_ids (List[str]) – ids of the videos, Limit: 5 ids

Raises:
Return type:

List[str]

async get_user_block_list(broadcaster_id, first=20, after=None)#

Gets a specified user’s block list. The list is sorted by when the block occurred in descending order (i.e. most recent block first).

Requires User Authentication with USER_READ_BLOCKED_USERS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-block-list

Parameters:
  • broadcaster_id (str) – User ID for a twitch user

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 20

  • after (Optional[str]) –

    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

Raises:
Return type:

AsyncGenerator[BlockListEntry, None]

async block_user(target_user_id, source_context=None, reason=None)#

Blocks the specified user on behalf of the authenticated user.

Requires User Authentication with USER_MANAGE_BLOCKED_USERS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#block-user

Parameters:
Raises:
Return type:

bool

async unblock_user(target_user_id)#

Unblocks the specified user on behalf of the authenticated user.

Requires User Authentication with USER_MANAGE_BLOCKED_USERS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#unblock-user

Parameters:

target_user_id (str) – User ID of the user to be unblocked.

Raises:
Return type:

bool

async get_followed_streams(user_id, after=None, first=100)#

Gets information about active streams belonging to channels that the authenticated user follows. 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 User Authentication with USER_READ_FOLLOWS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-followed-streams

Parameters:
  • user_id (str) – Results will only include active streams from the channels that this Twitch user follows. user_id must match the User ID in the bearer token.

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default: 100

Raises:
Return type:

AsyncGenerator[Stream, None]

async get_polls(broadcaster_id, poll_id=None, after=None, first=20)#

Get information about all polls or specific polls for a Twitch channel. Poll information is available for 90 days.

Requires User Authentication with CHANNEL_READ_POLLS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-polls

Parameters:
  • broadcaster_id (str) – The broadcaster running polls. Provided broadcaster_id must match the user_id in the user OAuth token.

  • poll_id (Union[str, List[str], None]) – ID(s) of a poll. You can specify up to 20 poll ids

    Default: None

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 20

    Default: 20

Raises:
Return type:

AsyncGenerator[Poll, None]

async create_poll(broadcaster_id, title, choices, duration, channel_points_voting_enabled=False, channel_points_per_vote=None)#

Create a poll for a specific Twitch channel.

Requires User Authentication with CHANNEL_MANAGE_POLLS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-poll

Parameters:
  • broadcaster_id (str) – The broadcaster running the poll

  • title (str) – Question displayed for the poll

  • choices (List[str]) – List of poll choices.

  • duration (int) – Total duration for the poll (in seconds). Minimum 15, Maximum 1800

  • channel_points_voting_enabled (bool) – Indicates if Channel Points can be used for voting.

    Default: False

  • channel_points_per_vote (Optional[int]) – Number of Channel Points required to vote once with Channel Points. Minimum: 0. Maximum: 1000000.

    Default: None

Raises:
Return type:

Poll

async end_poll(broadcaster_id, poll_id, status)#

End a poll that is currently active.

Requires User Authentication with CHANNEL_MANAGE_POLLS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#end-poll

Parameters:
  • broadcaster_id (str) – id of the broadcaster running the poll

  • poll_id (str) – id of the poll

  • status (PollStatus) – The poll status to be set

Raises:
Return type:

Poll

async get_predictions(broadcaster_id, prediction_ids=None, after=None, first=20)#

Get information about all Channel Points Predictions or specific Channel Points Predictions for a Twitch channel. Results are ordered by most recent, so it can be assumed that the currently active or locked Prediction will be the first item.

Requires User Authentication with CHANNEL_READ_PREDICTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-predictions

Parameters:
  • broadcaster_id (str) – The broadcaster running the prediction

  • prediction_ids (Optional[List[str]]) – List of prediction ids.

    Default: None

  • after (Optional[str]) –

    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

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 20

    Default: 20

Raises:
Return type:

AsyncGenerator[Prediction, None]

async create_prediction(broadcaster_id, title, outcomes, prediction_window)#

Create a Channel Points Prediction for a specific Twitch channel.

Requires User Authentication with CHANNEL_MANAGE_PREDICTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-prediction

Parameters:
  • broadcaster_id (str) – The broadcaster running the prediction

  • title (str) – Title of the Prediction

  • outcomes (List[str]) – List of possible Outcomes, must contain between 2 and 10 entries

  • prediction_window (int) – Total duration for the Prediction (in seconds). Minimum 1, Maximum 1800

Raises:
Return type:

Prediction

async end_prediction(broadcaster_id, prediction_id, status, winning_outcome_id=None)#

Lock, resolve, or cancel a Channel Points Prediction.

Requires User Authentication with CHANNEL_MANAGE_PREDICTIONS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#end-prediction

Parameters:
  • broadcaster_id (str) – ID of the broadcaster

  • prediction_id (str) – ID of the Prediction

  • status (PredictionStatus) – The Prediction status to be set.

  • winning_outcome_id (Optional[str]) – ID of the winning outcome for the Prediction.

    Default: None

Raises:
Return type:

Prediction

async start_raid(from_broadcaster_id, to_broadcaster_id)#

Raid another channel by sending the broadcaster’s viewers to the targeted channel.

Requires User Authentication with CHANNEL_MANAGE_RAIDS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#start-a-raid

Parameters:
  • from_broadcaster_id (str) – The ID of the broadcaster that’s sending the raiding party.

  • to_broadcaster_id (str) – The ID of the broadcaster to raid.

Raises:
Return type:

RaidStartResult

async cancel_raid(broadcaster_id)#

Cancel a pending raid.

Requires User Authentication with CHANNEL_MANAGE_RAIDS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#cancel-a-raid

Parameters:

broadcaster_id (str) – The ID of the broadcaster that sent the raiding party.

Raises:
async manage_held_automod_message(user_id, msg_id, action)#

Allow or deny a message that was held for review by AutoMod.

Requires User Authentication with MODERATOR_MANAGE_AUTOMOD

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#manage-held-automod-messages

Parameters:
  • user_id (str) – The moderator who is approving or rejecting the held message.

  • msg_id (str) – ID of the targeted message

  • action (AutoModAction) – The action to take for the message.

Raises:
async get_chat_badges(broadcaster_id)#

Gets a list of custom chat badges that can be used in chat for the specified channel.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-chat-badges

Parameters:

broadcaster_id (str) – The ID of the broadcaster whose chat badges you want to get.

Raises:
Return type:

List[ChatBadge]

async get_global_chat_badges()#
Return type:

List[ChatBadge]

Gets a list of chat badges that can be used in chat for any channel.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-global-chat-badges

Raises:
async get_channel_emotes(broadcaster_id)#

Gets all emotes that the specified Twitch channel created.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-emotes

Parameters:

broadcaster_id (str) – ID of the broadcaster

Raises:
Return type:

GetEmotesResponse

async get_global_emotes()#
Return type:

GetEmotesResponse

Gets all global emotes.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-global-emotes

Raises:
async get_emote_sets(emote_set_id)#

Gets emotes for one or more specified emote sets.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-emote-sets

Parameters:

emote_set_id (List[str]) – A list of IDs that identify the emote sets.

Raises:
Return type:

GetEmotesResponse

async delete_eventsub_subscription(subscription_id)#

Deletes an EventSub subscription.

Requires App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-eventsub-subscription

Parameters:

subscription_id (str) – The ID of the subscription

Raises:
async get_eventsub_subscriptions(status=None, sub_type=None, user_id=None, after=None)#

Gets a list of your EventSub subscriptions. The list is paginated and ordered by the oldest subscription first.

Requires App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-eventsub-subscriptions

Parameters:
  • status (Optional[str]) – Filter subscriptions by its status.

    Default: None

  • sub_type (Optional[str]) – Filter subscriptions by subscription type.

    Default: None

  • user_id (Optional[str]) – Filter subscriptions by user ID.

    Default: None

  • after (Optional[str]) –

    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

Raises:
Return type:

GetEventSubSubscriptionResult

async get_channel_stream_schedule(broadcaster_id, stream_segment_ids=None, start_time=None, utc_offset=None, first=20, after=None)#

Gets all scheduled broadcasts or specific scheduled broadcasts from a channel’s stream schedule.

Requires App or User Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-stream-schedule

Parameters:
  • broadcaster_id (str) – user id of the broadcaster

  • stream_segment_ids (Optional[List[str]]) – optional list of stream segment ids. Maximum 100 entries.

    Default: None

  • start_time (Optional[datetime]) – optional timestamp to start returning stream segments from.

    Default: None

  • utc_offset (Optional[str]) – A timezone offset to be used.

    Default: None

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 25

    Default: 20

  • after (Optional[str]) –

    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

Raises:
Return type:

ChannelStreamSchedule

async get_channel_icalendar(broadcaster_id)#

Gets all scheduled broadcasts from a channel’s stream schedule as an iCalendar.

Does not require Authorization

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-channel-icalendar

Parameters:

broadcaster_id (str) – id of the broadcaster

Raises:
Return type:

str

async update_channel_stream_schedule(broadcaster_id, is_vacation_enabled=None, vacation_start_time=None, vacation_end_time=None, timezone=None)#

Update the settings for a channel’s stream schedule. This can be used for setting vacation details.

Requires User Authentication with CHANNEL_MANAGE_SCHEDULE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-channel-stream-schedule

Parameters:
  • broadcaster_id (str) – id of the broadcaster

  • is_vacation_enabled (Optional[bool]) – indicates if Vacation Mode is enabled.

    Default: None

  • vacation_start_time (Optional[datetime]) – Start time for vacation

    Default: None

  • vacation_end_time (Optional[datetime]) – End time for vacation specified

    Default: None

  • timezone (Optional[str]) – The timezone for when the vacation is being scheduled using the IANA time zone database format.

Raises:
async create_channel_stream_schedule_segment(broadcaster_id, start_time, timezone, is_recurring, duration=None, category_id=None, title=None)#

Create a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.

Requires User Authentication with CHANNEL_MANAGE_SCHEDULE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#create-channel-stream-schedule-segment

Parameters:
  • broadcaster_id (str) – id of the broadcaster

  • start_time (datetime) – Start time for the scheduled broadcast

  • timezone (str) – The timezone of the application creating the scheduled broadcast using the IANA time zone database format.

  • is_recurring (bool) – Indicates if the scheduled broadcast is recurring weekly.

  • duration (Optional[str]) – Duration of the scheduled broadcast in minutes from the start_time.

    Default: 240

  • category_id (Optional[str]) – Game/Category ID for the scheduled broadcast.

    Default: None

  • title (Optional[str]) – Title for the scheduled broadcast.

    Default: None

Raises:
Return type:

ChannelStreamSchedule

async update_channel_stream_schedule_segment(broadcaster_id, stream_segment_id, start_time=None, duration=None, category_id=None, title=None, is_canceled=None, timezone=None)#

Update a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.

Requires User Authentication with CHANNEL_MANAGE_SCHEDULE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-channel-stream-schedule-segment

Parameters:
  • broadcaster_id (str) – id of the broadcaster

  • stream_segment_id (str) – The ID of the streaming segment to update.

  • start_time (Optional[datetime]) – Start time for the scheduled broadcast

    Default: None

  • duration (Optional[str]) – Duration of the scheduled broadcast in minutes from the start_time.

    Default: 240

  • category_id (Optional[str]) – Game/Category ID for the scheduled broadcast.

    Default: None

  • title (Optional[str]) – Title for the scheduled broadcast.

    Default: None

  • is_canceled (Optional[bool]) – Indicated if the scheduled broadcast is canceled.

    Default: None

  • timezone (Optional[str]) – The timezone of the application creating the scheduled broadcast using the IANA time zone database format.

    Default: None

Raises:
Return type:

ChannelStreamSchedule

async delete_channel_stream_schedule_segment(broadcaster_id, stream_segment_id)#

Delete a single scheduled broadcast or a recurring scheduled broadcast for a channel’s stream schedule.

Requires User Authentication with CHANNEL_MANAGE_SCHEDULE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-channel-stream-schedule-segment

Parameters:
  • broadcaster_id (str) – id of the broadcaster

  • stream_segment_id (str) – The ID of the streaming segment to delete.

Raises:
async update_drops_entitlements(entitlement_ids, fulfillment_status)#

Updates the fulfillment status on a set of Drops entitlements, specified by their entitlement IDs.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-drops-entitlements

Parameters:
Raises:
Return type:

List[DropsEntitlement]

async send_whisper(from_user_id, to_user_id, message)#

Sends a whisper message to the specified user.

Requires User Authentication with USER_MANAGE_WHISPERS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#send-whisper

Parameters:
  • from_user_id (str) – The ID of the user sending the whisper.

  • to_user_id (str) – The ID of the user to receive the whisper.

  • message (str) – The whisper message to send.

Raises:
async remove_channel_vip(broadcaster_id, user_id)#

Removes a VIP from the broadcaster’s chat room.

Requires User Authentication with CHANNEL_MANAGE_VIPS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#remove-channel-vip

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that’s removing VIP status from the user.

  • user_id (str) – The ID of the user to remove as a VIP from the broadcaster’s chat room.

Raises:
Return type:

bool

Returns:

True if channel vip was removed, False if user was not a channel vip

async add_channel_vip(broadcaster_id, user_id)#

Adds a VIP to the broadcaster’s chat room.

Requires User Authentication with CHANNEL_MANAGE_VIPS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#add-channel-vip

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that’s granting VIP status to the user.

  • user_id (str) – The ID of the user to add as a VIP in the broadcaster’s chat room.

Raises:
Return type:

bool

Returns:

True if user was added as vip, False when user was already vip or is moderator

async get_vips(broadcaster_id, user_ids=None, first=None, after=None)#

Gets a list of the channel’s VIPs.

Requires User Authentication with CHANNEL_READ_VIPS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-vips

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster whose list of VIPs you want to get.

  • user_ids (Union[str, List[str], None]) – Filters the list for specific VIPs. Maximum 100

    Default:None

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default:None

  • after (Optional[str]) –

    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

Raises:
Return type:

AsyncGenerator[ChannelVIP, None]

async add_channel_moderator(broadcaster_id, user_id)#

Adds a moderator to the broadcaster’s chat room.

Requires User Authentication with CHANNEL_MANAGE_MODERATORS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#add-channel-moderator

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that owns the chat room.

  • user_id (str) – The ID of the user to add as a moderator in the broadcaster’s chat room.

Raises:
async remove_channel_moderator(broadcaster_id, user_id)#

Removes a moderator from the broadcaster’s chat room.

Requires User Authentication with CHANNEL_MANAGE_MODERATORS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#remove-channel-moderator

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that owns the chat room.

  • user_id (str) – The ID of the user to remove as a moderator from the broadcaster’s chat room.

Raises:
async get_user_chat_color(user_ids)#

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

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-chat-color

Parameters:

user_ids (Union[str, List[str]]) – The ID of the user whose color you want to get.

Raises:
Return type:

List[UserChatColor]

Returns:

A list of user chat Colors

async update_user_chat_color(user_id, color)#

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

Requires User Authentication with USER_MANAGE_CHAT_COLOR

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-user-chat-color

Parameters:
  • user_id (str) – The ID of the user whose chat color you want to update.

  • color (str) – The color to use for the user’s name in chat. See twitch Docs for valid values.

Raises:
async delete_chat_message(broadcaster_id, moderator_id, message_id=None)#

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

Requires User Authentication with MODERATOR_MANAGE_CHAT_MESSAGES

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#delete-chat-messages

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that owns the chat room to remove messages from.

  • moderator_id (str) – The ID of a user that has permission to moderate the broadcaster’s chat room.

  • message_id (Optional[str]) – The ID of the message to remove. If None, removes all messages from the broadcasters chat.

    Default:None

Raises:
async send_chat_announcement(broadcaster_id, moderator_id, message, color=None)#

Sends an announcement to the broadcaster’s chat room.

Requires User Authentication with MODERATOR_MANAGE_ANNOUNCEMENTS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#send-chat-announcement

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that owns the chat room to send the announcement to.

  • moderator_id (str) – The ID of a user who has permission to moderate the broadcaster’s chat room.

  • message (str) – The announcement to make in the broadcaster’s chat room.

  • color (Optional[str]) – The color used to highlight the announcement. See twitch Docs for valid values.

    Default:None

Raises:
async send_a_shoutout(from_broadcaster_id, to_broadcaster_id, moderator_id)#

Sends a Shoutout to the specified broadcaster.

Typically, you send Shoutouts when you or one of your moderators notice another broadcaster in your chat, the other broadcaster is coming up in conversation, or after they raid your broadcast.

Requires User Authentication with MODERATOR_MANAGE_SHOUTOUTS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#send-a-shoutout

Parameters:
  • from_broadcaster_id (str) – The ID of the broadcaster that’s sending the Shoutout.

  • to_broadcaster_id (str) – The ID of the broadcaster that’s receiving the Shoutout.

  • moderator_id (str) – The ID 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.

Raises:
Return type:

None

async get_chatters(broadcaster_id, moderator_id, first=None, after=None)#

Gets the list of users that are connected to the broadcaster’s chat session.

Requires User Authentication with MODERATOR_READ_CHATTERS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-chatters

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster whose list of chatters you want to get.

  • moderator_id (str) – The ID of the broadcaster or one of the broadcaster’s moderators. This ID must match the user ID in the user access token.

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 1000

    Default: 100

  • after (Optional[str]) –

    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

Raises:
Return type:

GetChattersResponse

async get_shield_mode_status(broadcaster_id, moderator_id)#

Gets the broadcaster’s Shield Mode activation status.

Requires User Authentication with either MODERATOR_READ_SHIELD_MODE or MODERATOR_MANAGE_SHIELD_MODE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-shield-mode-status

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster whose Shield Mode activation status you want to get.

  • moderator_id (str) – The ID of the broadcaster or a user that is one of the broadcaster’s moderators.

Raises:
Return type:

ShieldModeStatus

async update_shield_mode_status(broadcaster_id, moderator_id, is_active)#

Activates or deactivates the broadcaster’s Shield Mode.

Requires User Authentication with MODERATOR_MANAGE_SHIELD_MODE

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#update-shield-mode-status

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster whose Shield Mode you want to activate or deactivate.

  • moderator_id (str) – The ID of the broadcaster or a user that is one of the broadcaster’s moderators.

  • is_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.

Raises:
Return type:

ShieldModeStatus

async get_charity_campaign(broadcaster_id)#

Gets information about the charity campaign that a broadcaster is running.

Requires User Authentication with CHANNEL_READ_CHARITY

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-charity-campaign

Parameters:

broadcaster_id (str) – The ID of the broadcaster that’s currently running a charity campaign.

Raises:
Return type:

Optional[CharityCampaign]

async get_charity_donations(broadcaster_id, first=None, after=None)#

Gets the list of donations that users have made to the broadcaster’s active charity campaign.

Requires User Authentication with CHANNEL_READ_CHARITY

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-charity-campaign-donations

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster that’s currently running a charity campaign.

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default:20

  • after (Optional[str]) –

    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

Raises:
Return type:

AsyncGenerator[CharityCampaignDonation, None]

async get_content_classification_labels(locale=None)#

Gets information about Twitch content classification labels.

Requires User or App Authentication

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-content-classification-labels

Parameters:

locale (Optional[str]) – Locale for the Content Classification Labels.

Default:en-US

Raises:
Return type:

List[ContentClassificationLabel]

async get_ad_schedule(broadcaster_id)#

This endpoint returns 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. Note that a new ad cannot be run until 8 minutes after running a previous ad.

Requires User Authentication with CHANNEL_READ_ADS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-ad-schedule

Parameters:

broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token.

Raises:
Return type:

AdSchedule

async snooze_next_ad(broadcaster_id)#

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.

Requires User Authentication with CHANNEL_MANAGE_ADS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#snooze-next-ad

Parameters:

broadcaster_id (str) – Provided broadcaster_id must match the user_id in the auth token.

Raises:
Return type:

AdSnoozeResponse

async send_chat_message(broadcaster_id, sender_id, message, reply_parent_message_id=None)#

Sends a message to the broadcaster’s chat room.

Requires User or App Authentication with USER_WRITE_CHAT

If App Authorization is used, then additionally requires USER_BOT scope from the chatting user and either CHANNEL_BOT from the broadcaster or moderator status.

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#send-chat-message

Parameters:
  • broadcaster_id (str) – The ID of the broadcaster whose chat room the message will be sent to.

  • sender_id (str) – The ID 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

  • reply_parent_message_id (Optional[str]) – The ID of the chat message being replied to.

Raises:
Return type:

SendMessageResponse

async get_moderated_channels(user_id, after=None, first=None)#

Gets a list of channels that the specified user has moderator privileges in.

Requires User Authentication with USER_READ_MODERATED_CHANNELS

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-moderated-channels

Parameters:
  • user_id (str) – A user’s ID. Returns the list of channels that this user has moderator privileges in. This ID must match the user ID in the user OAuth token

  • first (Optional[int]) –

    The maximum number of items to return per API call. You can use this in combination with limit() to optimize the bandwith and number of API calls used to fetch the amount of results you desire.

    Minimum 1, Maximum 100

    Default:20

  • after (Optional[str]) –

    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

Raises:
Return type:

AsyncGenerator[ChannelModerator, None]

async get_user_emotes(user_id, broadcaster_id, after=None)#

Retrieves emotes available to the user across all channels.

Requires User Authentication with USER_READ_EMOTES

For detailed documentation, see here: https://dev.twitch.tv/docs/api/reference#get-user-emotes

Parameters:
  • user_id (str) – The ID of the user. This ID must match the user ID in the user access token.

  • broadcaster_id (str) – Returns all emotes available to the user within the chat owned by the specified broadcaster. This includes the Global and Subscriber Emotes the user has access to, as well as channel-only specific emotes such as Follower Emotes.

  • after (Optional[str]) –

    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

Raises:
Return type:

UserEmotesResponse