Client Reference#
Event, Client and Exceptions API reference.
Note
For the command extension see: Commands Ext
Client#
- clsClient.from_client_credentials
- asyncclose
- asyncconnect
- defcreate_user
- asyncdelete_videos
- asyncevent_channel_join_failure
- asyncevent_channel_joined
- asyncevent_error
- asyncevent_join
- asyncevent_message
- asyncevent_mode
- asyncevent_notice
- asyncevent_part
- asyncevent_raw_data
- asyncevent_raw_notice
- asyncevent_raw_usernotice
- asyncevent_ready
- asyncevent_reconnect
- asyncevent_token_expired
- asyncevent_usernotice_subscription
- asyncevent_userstate
- asyncfetch_channel
- asyncfetch_channels
- asyncfetch_chatters_colors
- asyncfetch_cheermotes
- asyncfetch_clips
- asyncfetch_games
- asyncfetch_global_chat_badges
- asyncfetch_global_emotes
- asyncfetch_streams
- asyncfetch_tags
- asyncfetch_teams
- asyncfetch_top_games
- asyncfetch_users
- asyncfetch_videos
- defget_channel
- asyncget_webhook_subscriptions
- asyncjoin_channels
- asyncpart_channels
- defrun
- asyncsearch_categories
- asyncsearch_channels
- asyncstart
- asyncupdate_chatter_color
- asyncwait_for
- asyncwait_for_ready
- 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.
- 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
- Returns
- 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.
- 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
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
- Returns
- 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
- 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
- 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
- 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 fetchgame_ids (Optional[List[
int
]]) – game ids of streams to fetchuser_logins (Optional[List[
str
]]) – user login names of people whose streams to fetchlanguages (Optional[List[
str
]]) – language for the stream(s). ISO 639-1 or two letter code for supported stream languagetoken (Optional[
str
]) – An optional OAuth token to use instead of the bot OAuth tokentype (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
- 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
- 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 idsgame_id (Optional[
int
]) – A game to fetch videos fromuser_id (Optional[
int
]) – A user to fetch videos from. Seetwitchio.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 passedsort (
str
) – Sort orders of the videos. Valid values are time, trending, views, Defaults to time. Cannot be used when video id(s) are passedtype (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 passedlanguage (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
- 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
- coroutine join_channels(channels: Union[List[str], Tuple[str]])#
This function is a coroutine.
Join the specified channels.
- coroutine part_channels(channels: Union[List[str], Tuple[str]])#
This function is a coroutine.
Part the specified channels.
- 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
- 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 theuser: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_ prefixpredicate (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 beTrue
- 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.
- 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.
- 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
- 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.
- 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
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#