Client Reference

Event, Client and Exceptions API reference.

Note

For the command extension see: Commands Ext

Client

class twitchio.Client(token: str, *, client_secret: Optional[str] = None, initial_channels: Optional[Union[list, tuple, Callable]] = None, loop: Optional[asyncio.events.AbstractEventLoop] = None, heartbeat: Optional[float] = 30.0)

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.

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) twitchio.user.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

Return type

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

Return type

List[int]

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)

Retrieve channel information from the API.

Parameters

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

Returns

Return type

twitchio.ChannelInfo

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

Return type

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

Return type

List[twitchio.Clip]

coroutine fetch_games(ids: Optional[List[int]] = None, names: Optional[List[str]] = None) List[twitchio.models.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

Returns

Return type

List[twitchio.Game]

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)

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:class:`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

Returns

Return type

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

Return type

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

Return type

List[twitchio.Team]

coroutine fetch_top_games() List[twitchio.models.Game]

This function is a coroutine.

Fetches the top games from the api

Returns

Return type

List[twitchio.Game]

coroutine fetch_users(names: Optional[List[str]] = None, ids: Optional[List[int]] = None, token: Optional[str] = None, force=False) List[twitchio.user.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

Return type

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

Return type

List[twitchio.Video]

classmethod from_client_credentials(client_id: str, client_secret: str, *, loop: Optional[asyncio.events.AbstractEventLoop] = None, heartbeat: Optional[float] = 30.0) twitchio.client.Client

creates a client application token from your client credentials.

Parameters
  • client_id (:class`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

Return type

A new Client instance

get_channel(name: str) Optional[twitchio.channel.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

Return type

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

Return type

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.

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

Return type

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

Return type

List[twitchio.SearchUser]

coroutine start()

This function is a coroutine.

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

coroutine wait_for(event: str, predicate: 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

Return type

The arguments passed to the event.

property connected_channels: List[twitchio.channel.Channel]

A list of currently connected Channel

property events

A mapping of events name to coroutine.

property nick

The IRC bots nick.

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_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: 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)

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
exception twitchio.Unauthorized