Python Twitch API
This is a full implementation of the Twitch Helix API, PubSub, EventSub and Chat in python 3.7+.
Installation
Install using pip:
pip install twitchAPI
Documentation and Support
A full API documentation can be found on readthedocs.org.
For support please join the Twitch API discord server
Usage
Basic API calls
Setting up an Instance of the Twitch API and get your User ID:
from twitchAPI.twitch import Twitch
from twitchAPI.helper import first
import asyncio
async def twitch_example():
twitch = await Twitch('app_id', 'app_secret')
user = await first(twitch.get_users(logins='your_twitch_user'))
print(user.id)
asyncio.run(twitch_example())
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.
It's 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.
Please read the docs for more details and examples on how to set and use Authentication!
App Authentication
App authentication is super simple, just do the following:
from twitchAPI.twitch import Twitch
twitch = await Twitch('my_app_id', 'my_app_secret')
User Authentication
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.
For my Authenticator you have to add the following URL as a "OAuth Redirect URL": http://localhost:17563
You can set that here in your twitch dev dashboard.
from twitchAPI.twitch import Twitch
from twitchAPI.oauth import UserAuthenticator
from twitchAPI.type import AuthScope
twitch = await Twitch('my_app_id', 'my_app_secret')
target_scope = [AuthScope.BITS_READ]
auth = UserAuthenticator(twitch, target_scope, force_verify=False)
token, refresh_token = await auth.authenticate()
await twitch.set_user_authentication(token, target_scope, refresh_token)
You can reuse this token and use the refresh_token to renew it:
from twitchAPI.oauth import refresh_access_token
new_token, new_refresh_token = await refresh_access_token('refresh_token', 'client_id', 'client_secret')
AuthToken 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
EventSub
EventSub lets you listen for events that happen on Twitch.
The EventSub client runs in its own thread, calling the given callback function whenever an event happens.
There are multiple EventSub transports available, used for different use cases.
See here for more info about EventSub in general and the different Transports, including code examples: on readthedocs
PubSub
PubSub enables you to subscribe to a topic, for updates (e.g., when a user cheers in a channel).
A more detailed documentation can be found here on readthedocs
from twitchAPI.pubsub import PubSub
from twitchAPI.twitch import Twitch
from twitchAPI.helper import first
from twitchAPI.type import AuthScope
from twitchAPI.oauth import UserAuthenticator
import asyncio
from pprint import pprint
from uuid import UUID
APP_ID = 'my_app_id'
APP_SECRET = 'my_app_secret'
USER_SCOPE = [AuthScope.WHISPERS_READ]
TARGET_CHANNEL = 'teekeks42'
async def callback_whisper(uuid: UUID, data: dict) -> None:
print('got callback for UUID ' + str(uuid))
pprint(data)
async def run_example():
twitch = await Twitch(APP_ID, APP_SECRET)
auth = UserAuthenticator(twitch, [AuthScope.WHISPERS_READ], force_verify=False)
token, refresh_token = await auth.authenticate()
await twitch.set_user_authentication(token, [AuthScope.WHISPERS_READ], refresh_token)
user = await first(twitch.get_users(logins=[TARGET_CHANNEL]))
pubsub = PubSub(twitch)
pubsub.start()
uuid = await pubsub.listen_whispers(user.id, callback_whisper)
input('press ENTER to close...')
await pubsub.unlisten(uuid)
pubsub.stop()
await twitch.close()
asyncio.run(run_example())
Chat
A simple twitch chat bot.
Chat bots can join channels, listen to chat and reply to messages, commands, subscriptions and many more.
A more detailed documentation can be found here on readthedocs
Example code for a simple bot
from twitchAPI.twitch import Twitch
from twitchAPI.oauth import UserAuthenticator
from twitchAPI.type import AuthScope, ChatEvent
from twitchAPI.chat import Chat, EventData, ChatMessage, ChatSub, ChatCommand
import asyncio
APP_ID = 'my_app_id'
APP_SECRET = 'my_app_secret'
USER_SCOPE = [AuthScope.CHAT_READ, AuthScope.CHAT_EDIT]
TARGET_CHANNEL = 'teekeks42'
async def on_ready(ready_event: EventData):
print('Bot is ready for work, joining channels')
await ready_event.chat.join_room(TARGET_CHANNEL)
async def on_message(msg: ChatMessage):
print(f'in {msg.room.name}, {msg.user.name} said: {msg.text}')
async def on_sub(sub: ChatSub):
print(f'New subscription in {sub.room.name}:\\n'
f' Type: {sub.sub_plan}\\n'
f' Message: {sub.sub_message}')
async def test_command(cmd: ChatCommand):
if len(cmd.parameter) == 0:
await cmd.reply('you did not tell me what to reply with')
else:
await cmd.reply(f'{cmd.user.name}: {cmd.parameter}')
async def run():
twitch = await Twitch(APP_ID, APP_SECRET)
auth = UserAuthenticator(twitch, USER_SCOPE)
token, refresh_token = await auth.authenticate()
await twitch.set_user_authentication(token, USER_SCOPE, refresh_token)
chat = await Chat(twitch)
chat.register_event(ChatEvent.READY, on_ready)
chat.register_event(ChatEvent.MESSAGE, on_message)
chat.register_event(ChatEvent.SUB, on_sub)
chat.register_command('reply', test_command)
chat.start()
try:
input('press ENTER to stop\n')
finally:
chat.stop()
await twitch.close()
asyncio.run(run())