Client Reference#

Event, Client and Exceptions API reference.

Note

For the command extension see: Commands Ext

Client#

Attributes
Methods
class twitchio.Client(token: str, *, client_secret: Optional[str] = None, initial_channels: Optional[Union[list, tuple, Callable]] = None, loop: Optional[AbstractEventLoop] = None, heartbeat: Optional[float] = 30.0, retain_cache: Optional[bool] = True)#

TwitchIO Client object that is used to interact with the Twitch API and connect to Twitch IRC over websocket.

Parameters

  • token (str) – An OAuth Access Token to login with on IRC and interact with the API.

  • client_secret (Optional[str]) – An optional application Client Secret used to generate Access Tokens automatically.

  • initial_channels (Optional[Union[list, tuple, Callable]]) – An optional list, tuple or callable which contains channel names to connect to on startup. If this is a callable, it must return a list or tuple.

  • loop (Optional[asyncio.AbstractEventLoop]) – The event loop the client will use to run.

  • heartbeat (Optional[float]) – An optional float in seconds to send a PING message to the server. Defaults to 30.0.

  • retain_cache (Optional[bool]) – An optional bool that will retain the cache if PART is received from websocket when True. It will still remove from cache if part_channels is manually called. Defaults to True.

loop#

The event loop the Client uses.

Type

asyncio.AbstractEventLoop

coroutine close()#

This function is a coroutine.

Cleanly disconnects from the twitch IRC server

coroutine connect()#

This function is a coroutine.

Connects to the twitch IRC server

create_user(user_id: int, user_name: str) → PartialUser#

A helper method to create a twitchio.PartialUser from a user id and user name.

Parameters

  • user_id (int) – The id of the user

  • user_name (str) – The name of the user

Returns

twitchio.PartialUser

coroutine delete_videos(token: str, ids: List[int]) → List[int]#

This function is a coroutine.

Delete videos from the api. Returns the video ids that were successfully deleted.

Parameters

  • token (str) – An oauth token with the channel:manage:videos scope

  • ids (List[int]) – A list of video ids from the channel of the oauth token to delete

Returns

List[int]

coroutine event_channel_joined(channel: Channel)#

This function is a coroutine.

Event called when the bot joins a channel.

Parameters

channel (Channel) – The channel that was joined.

coroutine event_notice(message: str, msg_id: Optional[str], channel: Optional[Channel])#

This function is a coroutine.

Event called with the NOTICE data received by Twitch.

Tip

For more information on NOTICE msg_ids visit: https://dev.twitch.tv/docs/irc/msg-id/

Parameters

  • message (str) – The message of the NOTICE.

  • msg_id (Optional[str]) – The msg_id that indicates what the NOTICE type.

  • channel (Optional[Channel]) – The channel the NOTICE message originated from.

Example

@bot.event()
async def event_notice(message, msg_id, channel):
    print(message)
coroutine event_raw_notice(data: str)#

This function is a coroutine.

Event called with the raw NOTICE data received by Twitch.

Parameters

data (str) – The raw NOTICE data received from Twitch.

Example

@bot.event()
async def event_raw_notice(data):
    print(data)
coroutine event_token_expired()#

This function is a coroutine.

A special event called when the oauth token expires. This is a hook into the http system, it will call this when a call to the api fails due to a token expiry. This function should return either a new token, or None. Returning None will cause the client to attempt an automatic token generation.

Note

This event is a callback hook. It is not a dispatched event. Any errors raised will be passed to the event_error() event.

coroutine fetch_channel(broadcaster: str, token: Optional[str] = None)#

This function is a coroutine.

Retrieve channel information from the API.

Note

This will be deprecated in 3.0. It’s recommended to use fetch_channels() instead.

Parameters

  • broadcaster (str) – The channel name or ID to request from API. Returns empty dict if no channel was found.

  • token (Optional[str]) – An optional OAuth token to use instead of the bot OAuth token.

Returns

twitchio.ChannelInfo

coroutine fetch_channels(broadcaster_ids: List[int], token: Optional[str] = None)#

This function is a coroutine.

Retrieve information for up to 100 channels from the API.

Parameters

  • broadcaster_ids (List[int]) – The channel ids to request from API.

  • token (Optional[str]) – An optional OAuth token to use instead of the bot OAuth token

Returns

List[twitchio.ChannelInfo]

coroutine fetch_chatters_colors(user_ids: List[int], token: Optional[str] = None)#

This function is a coroutine.

Fetches the color of a chatter.

Parameters

  • user_ids (List[int]) – List of user ids to fetch the colors for

  • token (Optional[str]) – An optional user oauth token

Returns

List[twitchio.ChatterColor]

coroutine fetch_cheermotes(user_id: Optional[int] = None)#

This function is a coroutine.

Fetches cheermotes from the twitch API

Parameters

user_id (Optional[int]) – The channel id to fetch from.

Returns

List[twitchio.CheerEmote]

coroutine fetch_clips(ids: List[str])#

This function is a coroutine.

Fetches clips by clip id. To fetch clips by user id, use twitchio.PartialUser.fetch_clips()

Parameters

ids (List[str]) – A list of clip ids

Returns

List[twitchio.Clip]

coroutine fetch_games(ids: Optional[List[int]] = None, names: Optional[List[str]] = None, igdb_ids: Optional[List[int]] = None) → List[Game]#

This function is a coroutine.

Fetches games by id or name. At least one id or name must be provided

Parameters

  • ids (Optional[List[int]]) – An optional list of game ids

  • names (Optional[List[str]]) – An optional list of game names

  • igdb_ids (Optional[List[int]]) – An optional list of IGDB game ids

Returns

List[twitchio.Game]

coroutine fetch_global_chat_badges()#

This function is a coroutine.

Fetches Twitch’s list of chat badges, which users may use in any channel’s chat room.

Returns: List[twitchio.ChatBadge]

coroutine fetch_global_emotes()#

This function is a coroutine.

Fetches global emotes from the twitch API

Returns

List[twitchio.GlobalEmote]

coroutine fetch_streams(user_ids: Optional[List[int]] = None, game_ids: Optional[List[int]] = None, user_logins: Optional[List[str]] = None, languages: Optional[List[str]] = None, token: Optional[str] = None, type: typing_extensions.Literal[all, live] = 'all')#

This function is a coroutine.

Fetches live streams from the helix API

Parameters

  • user_ids (Optional[List[int]]) – user ids of people whose streams to fetch

  • game_ids (Optional[List[int]]) – game ids of streams to fetch

  • user_logins (Optional[List[str]]) – user login names of people whose streams to fetch

  • languages (Optional[List[str]]) – language for the stream(s). ISO 639-1 or two letter code for supported stream language

  • token (Optional[str]) – An optional OAuth token to use instead of the bot OAuth token

  • type (Literal["all", "live"]) – One of "all" or "live". Defaults to "all". Specifies what type of stream to fetch.

Returns

List[twitchio.Stream]

coroutine fetch_tags(ids: Optional[List[str]] = None)#

This function is a coroutine.

Fetches stream tags.

Parameters

ids (Optional[List[str]]) – The ids of the tags to fetch

Returns

List[twitchio.Tag]

coroutine fetch_teams(team_name: Optional[str] = None, team_id: Optional[str] = None)#

This function is a coroutine.

Fetches information for a specific Twitch Team.

Parameters

  • name (Optional[str]) – Team name to fetch

  • id (Optional[str]) – Team id to fetch

Returns

List[twitchio.Team]

coroutine fetch_top_games() → List[Game]#

This function is a coroutine.

Fetches the top games from the api

Returns

List[twitchio.Game]

coroutine fetch_users(names: Optional[List[str]] = None, ids: Optional[List[int]] = None, token: Optional[str] = None, force=False) → List[User]#

This function is a coroutine.

Fetches users from the helix API

Parameters

  • names (Optional[List[str]]) – usernames of people to fetch

  • ids (Optional[List[str]]) – ids of people to fetch

  • token (Optional[str]) – An optional OAuth token to use instead of the bot OAuth token

  • force (bool) – whether to force a fetch from the api, or check the cache first. Defaults to False

Returns

List[twitchio.User]

coroutine fetch_videos(ids: Optional[List[int]] = None, game_id: Optional[int] = None, user_id: Optional[int] = None, period=None, sort=None, type=None, language=None)#

This function is a coroutine.

Fetches videos by id, game id, or user id

Parameters

  • ids (Optional[List[int]]) – A list of video ids

  • game_id (Optional[int]) – A game to fetch videos from

  • user_id (Optional[int]) – A user to fetch videos from. See twitchio.PartialUser.fetch_videos()

  • period (Optional[str]) – The period for which to fetch videos. Valid values are all, day, week, month. Defaults to all. Cannot be used when video id(s) are passed

  • sort (str) – Sort orders of the videos. Valid values are time, trending, views, Defaults to time. Cannot be used when video id(s) are passed

  • type (Optional[str]) – Type of the videos to fetch. Valid values are upload, archive, highlight. Defaults to all. Cannot be used when video id(s) are passed

  • language (Optional[str]) – Language of the videos to fetch. Must be an ISO-639-1 two letter code. Cannot be used when video id(s) are passed

Returns

List[twitchio.Video]

classmethod from_client_credentials(client_id: str, client_secret: str, *, loop: Optional[AbstractEventLoop] = None, heartbeat: Optional[float] = 30.0) → Client#

creates a client application token from your client credentials.

Parameters

  • client_id (str) –

  • client_secret (str) – An application Client Secret used to generate Access Tokens automatically.

  • loop (Optional[asyncio.AbstractEventLoop]) – The event loop the client will use to run.

Returns

A new Client instance

get_channel(name: str) → Optional[Channel]#

Retrieve a channel from the cache.

Parameters

name (str) – The channel name to retrieve from cache. Returns None if no channel was found.

Returns

Channel

coroutine get_webhook_subscriptions()#

This function is a coroutine.

Fetches your current webhook subscriptions. Requires your bot to be logged in with an app access token.

Returns

List[twitchio.WebhookSubscription]

coroutine join_channels(channels: Union[List[str], Tuple[str]])#

This function is a coroutine.

Join the specified channels.

Parameters

channels (Union[List[str], Tuple[str]]) – The channels in either a list or tuple form to join.

coroutine part_channels(channels: Union[List[str], Tuple[str]])#

This function is a coroutine.

Part the specified channels.

Parameters

channels (Union[List[str], Tuple[str]]) – The channels in either a list or tuple form to part.

run()#

A blocking function that starts the asyncio event loop, connects to the twitch IRC server, and cleans up when done.

coroutine search_categories(query: str)#

This function is a coroutine.

Searches twitches categories

Parameters

query (str) – The query to search for

Returns

List[twitchio.Game]

coroutine search_channels(query: str, *, live_only=False)#

This function is a coroutine.

Searches channels for the given query

Parameters

  • query (str) – The query to search for

  • live_only (bool) – Only search live channels. Defaults to False

Returns

List[twitchio.SearchUser]

coroutine start()#

This function is a coroutine.

Connects to the twitch IRC server, and cleanly disconnects when done.

coroutine update_chatter_color(token: str, user_id: int, color: str)#

This function is a coroutine.

Updates the color of the specified user in the specified channel/broadcaster’s chat.

Parameters

  • token (str) – An oauth token with the user:manage:chat_color scope.

  • user_id (int) – The ID of the user whose color is being updated, this must match the user ID in the token.

  • color (str) – Turbo and Prime users may specify a named color or a Hex color code like #9146FF. Please see the Twitch documentation for more information.

Returns

None

coroutine wait_for(event: str, predicate: ~typing.Callable[[], bool] = <function Client.<lambda>>, *, timeout=60.0) → Tuple[Any]#

This function is a coroutine.

Waits for an event to be dispatched, then returns the events data

Parameters

  • event (str) – The event to wait for. Do not include the event_ prefix

  • predicate (Callable[[...], bool]) – A check that is fired when the desired event is dispatched. if the check returns false, the waiting will continue until the timeout.

  • timeout (int) – How long to wait before timing out and raising an error.

Returns

The arguments passed to the event.

wait_for_ready() → Coroutine[Any, Any, bool]#

This function is a coroutine.

Waits for the underlying connection to finish startup

Returns

bool The state of the underlying flag. This will always be True

property connected_channels: List[Channel]#

A list of currently connected Channel

property events#

A mapping of events name to coroutine.

property nick#

The IRC bots nick.

property user_id#

The IRC bot user id.

Event Reference#

async Client.event_ready()#

This function is a coroutine.

Event called when the Bot has logged in and is ready.

Example

@bot.event()
async def event_ready():
    print(f'Logged into Twitch | {bot.nick}')
async Client.event_reconnect()#

This function is a coroutine.

Event called when twitch sends a RECONNECT notice. The library will automatically handle reconnecting when such an event is received

async Client.event_raw_data(data: str)#

This function is a coroutine.

Event called with the raw data received by Twitch.

Parameters

data (str) – The raw data received from Twitch.

Example

@bot.event()
async def event_raw_data(data):
    print(data)
async Client.event_message(message: Message)#

This function is a coroutine.

Event called when a PRIVMSG is received from Twitch.

Parameters

message (Message) – Message object containing relevant information.

async Client.event_join(channel: Channel, user: User)#

This function is a coroutine.

Event called when a JOIN is received from Twitch.

Parameters

  • channel (Channel) – The channel associated with the JOIN.

  • user (User) – User object containing relevant information to the JOIN.

async Client.event_part(user: User)#

This function is a coroutine.

Event called when a PART is received from Twitch.

Parameters

user (User) – User object containing relevant information to the PART.

async Client.event_mode(channel: Channel, user: User, status: str)#

This function is a coroutine.

Event called when a MODE is received from Twitch.

Parameters

  • channel (Channel) – Channel object relevant to the MODE event.

  • user (User) – User object containing relevant information to the MODE.

  • status (str) – The JTV status received by Twitch. Could be either o+ or o-. Indicates a moderation promotion/demotion to the User

async Client.event_userstate(user: User)#

This function is a coroutine.

Event called when a USERSTATE is received from Twitch.

Parameters

user (User) – User object containing relevant information to the USERSTATE.

async Client.event_raw_usernotice(channel: Channel, tags: dict)#

This function is a coroutine.

Event called when a USERNOTICE is received from Twitch. Since USERNOTICE’s can be fairly complex and vary, the following sub-events are available:

event_usernotice_subscription() : Called when a USERNOTICE Subscription or Re-subscription event is received.

Tip

For more information on how to handle USERNOTICE’s visit: https://dev.twitch.tv/docs/irc/tags/#usernotice-twitch-tags

Parameters

  • channel (Channel) – Channel object relevant to the USERNOTICE event.

  • tags (dict) – A dictionary with the relevant information associated with the USERNOTICE. This could vary depending on the event.

async Client.event_usernotice_subscription(metadata)#

This function is a coroutine.

Event called when a USERNOTICE subscription or re-subscription event is received from Twitch.

Parameters

metadata (NoticeSubscription) – The object containing various metadata about the subscription event. For ease of use, this contains a User and Channel.

async Client.event_error(error: Exception, data: Optional[str] = None)#

This function is a coroutine.

Event called when an error occurs while processing data.

Parameters

  • error (Exception) – The exception raised.

  • data (str) – The raw data received from Twitch. Depending on how this is called, this could be None.

Example

@bot.event()
async def event_error(error, data):
    traceback.print_exception(type(error), error, error.__traceback__, file=sys.stderr)
async Client.event_channel_join_failure(channel: str)#

This function is a coroutine.

Event called when the bot fails to join a channel.

Parameters

channel (str) – The channel name that was attempted to be joined.

Exceptions#

exception twitchio.TwitchIOException#
exception twitchio.AuthenticationError#
exception twitchio.InvalidContent#
exception twitchio.IRCCooldownError#
exception twitchio.EchoMessageWarning#
exception twitchio.NoClientID#
exception twitchio.NoToken#
exception twitchio.HTTPException(message: str, *, reason: Optional[str] = None, status: Optional[int] = None, extra: Optional[Any] = None)#
exception twitchio.Unauthorized(message: str, *, reason: Optional[str] = None, status: Optional[int] = None, extra: Optional[Any] = None)#