Installation

Documentation and Support

Usage

Basic API calls

fromtwitchAPI.twitchimportTwitchfromtwitchAPI.helperimportfirstimportasyncioasyncdeftwitch_example():# initialize the twitch instance, this will by default also create a app authentication for youtwitch=awaitTwitch('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=awaitfirst(twitch.get_users(logins='your_twitch_user'))# print the ID of your user or do whatever else you want with itprint(user.id)# run this exampleasyncio.run(twitch_example())

Authentication

App Authentication

fromtwitchAPI.twitchimportTwitchtwitch=awaitTwitch('my_app_id','my_app_secret')

User Authentication

fromtwitchAPI.twitchimportTwitchfromtwitchAPI.oauthimportUserAuthenticatorfromtwitchAPI.typeimportAuthScopetwitch=awaitTwitch('my_app_id','my_app_secret')target_scope= [AuthScope.BITS_READ]auth=UserAuthenticator(twitch,target_scope,force_verify=False)# this will open your default browser and prompt you with the twitch verification websitetoken,refresh_token=awaitauth.authenticate()# add User authenticationawaittwitch.set_user_authentication(token,target_scope,refresh_token)

fromtwitchAPI.oauthimportrefresh_access_tokennew_token,new_refresh_token=awaitrefresh_access_token('refresh_token','client_id','client_secret')

AuthToken refresh callback

fromtwitchAPI.twitchimportTwitchasyncdefuser_refresh(token:str,refresh_token:str):print(f'my new user token is:{token}')asyncdefapp_refresh(token:str):print(f'my new app token is:{token}')twitch=awaitTwitch('my_app_id','my_app_secret')twitch.app_auth_refresh_callback=app_refreshtwitch.user_auth_refresh_callback=user_refresh

EventSub

Chat

Example code for a simple bot

fromtwitchAPI.twitchimportTwitchfromtwitchAPI.oauthimportUserAuthenticatorfromtwitchAPI.typeimportAuthScope,ChatEventfromtwitchAPI.chatimportChat,EventData,ChatMessage,ChatSub,ChatCommandimportasyncioAPP_ID='my_app_id'APP_SECRET='my_app_secret'USER_SCOPE= [AuthScope.CHAT_READ,AuthScope.CHAT_EDIT]TARGET_CHANNEL='teekeks42'# this will be called when the event READY is triggered, which will be on bot startasyncdefon_ready(ready_event:EventData):print('Bot is ready for work, joining channels')# join our target channel, if you want to join multiple, either call join for each individually# or even better pass a list of channels as the argumentawaitready_event.chat.join_room(TARGET_CHANNEL)# you can do other bot initialization things in here# this will be called whenever a message in a channel was send by either the bot OR another userasyncdefon_message(msg:ChatMessage):print(f'in{msg.room.name},{msg.user.name} said:{msg.text}')# this will be called whenever someone subscribes to a channelasyncdefon_sub(sub:ChatSub):print(f'New subscription in{sub.room.name}:\\n'f'  Type:{sub.sub_plan}\\n'f'  Message:{sub.sub_message}')# this will be called whenever the !reply command is issuedasyncdeftest_command(cmd:ChatCommand):iflen(cmd.parameter)==0:awaitcmd.reply('you did not tell me what to reply with')else:awaitcmd.reply(f'{cmd.user.name}:{cmd.parameter}')# this is where we set up the botasyncdefrun():# set up twitch api instance and add user authentication with some scopestwitch=awaitTwitch(APP_ID,APP_SECRET)auth=UserAuthenticator(twitch,USER_SCOPE)token,refresh_token=awaitauth.authenticate()awaittwitch.set_user_authentication(token,USER_SCOPE,refresh_token)# create chat instancechat=awaitChat(twitch)# register the handlers for the events you want# listen to when the bot is done starting up and ready to join channelschat.register_event(ChatEvent.READY,on_ready)# listen to chat messageschat.register_event(ChatEvent.MESSAGE,on_message)# listen to channel subscriptionschat.register_event(ChatEvent.SUB,on_sub)# there are more events, you can view them all in this documentation# you can directly register commands and their handlers, this will register the !reply commandchat.register_command('reply',test_command)# we are done with our setup, lets start this bot up!chat.start()# lets run till we press enter in the consoletry:input('press ENTER to stop\n')finally:# now we can close the chat bot and the twitch api clientchat.stop()awaittwitch.close()# lets run our setupasyncio.run(run())