Twitch Chat Bot#
A simple twitch chat bot.
Chat bots can join channels, listen to chat and reply to messages, commands, subscriptions and many more.
Warning
Please note that the Chat Bot is currently in a early alpha stage!
Bugs and oddities are to be expected.
Please report all feature requests and bug requests to the github page.
Code example#
from twitchAPI import Twitch
from twitchAPI.oauth import UserAuthenticator
from twitchAPI.types 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'
# this will be called when the event READY is triggered, which will be on bot start
async def on_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 argument
await ready_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 user
async def on_message(msg: ChatMessage):
print(f'in {msg.room.name}, {msg.user.name} said: {msg.text}')
# this will be called whenever someone subscribes to a channel
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}')
# this will be called whenever the !reply command is issued
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}')
# this is where we set up the bot
async def run():
# set up twitch api instance and add user authentication with some scopes
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)
# create chat instance
chat = await Chat(twitch)
# register the handlers for the events you want
# listen to when the bot is done starting up and ready to join channels
chat.register_event(ChatEvent.READY, on_ready)
# listen to chat messages
chat.register_event(ChatEvent.MESSAGE, on_message)
# listen to channel subscriptions
chat.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 command
chat.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 console
try:
input('press ENTER to stop\n')
finally:
# now we can close the chat bot and the twitch api client
chat.stop()
await twitch.close()
# lets run our setup
asyncio.run(run())
Available Events#
READY
: Triggered when the bot is stared up and ready to join channelsMESSAGE
: Triggered when someone wrote a message in a channel we joinedSUB
: Triggered when someone subscribed to a channel we joinedRAID
: Triggered when a channel gets raidedROOM_STATE_CHANGE
: Triggered when a channel is changed (e.g. sub only mode was enabled)JOIN
: Triggered when someone other than the bot joins a channel. Note: this will not always trigger, depending on channel sizeJOINED
: Triggered when the bot joins a channelLEFT
: triggered when the bot left a channel
Class Documentation#
- class twitchAPI.chat.ChatUser#
Bases:
object
Represents a user in a chat channel
- __init__(chat, parsed)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- badge_info#
All infos related to the badges of the user
- badges#
The badges of the user
- class twitchAPI.chat.EventData#
Bases:
object
Represents a basic chat event
- Parameters:
chat (Chat) – represents the Chat Instance
- __init__(chat)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.ChatMessage#
Bases:
EventData
Represents a chat message
- __init__(chat, parsed)#
- reply_parent_msg_id: Optional[str]#
An ID that uniquely identifies the parent message that this message is replying to.
- emotes#
The emotes used in the message
- async reply(text)#
Reply to this message
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.ChatCommand#
Bases:
ChatMessage
Represents a command
- __init__(chat, parsed)#
- async reply(text)#
Reply to this message
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- reply_parent_msg_id: Optional[str]#
An ID that uniquely identifies the parent message that this message is replying to.
- emotes#
The emotes used in the message
- class twitchAPI.chat.ChatSub#
Bases:
object
Represents a sub to a channel
- __init__(chat, parsed)#
- property room#
The room this sub was issued in
- class twitchAPI.chat.Chat#
Bases:
object
The chat bot instance
- __init__(twitch, connection_url=None)#
- start()#
Start the Chat Client
- Raises:
RuntimeError – if already started
- Return type:
- stop()#
Stop the Chat Client
- Raises:
RuntimeError – if the client is not running
- Return type:
- register_command(name, handler)#
Register a command
- register_event(event, handler)#
Register a event handler
- async join_room(chat_rooms)#
join one or more chat rooms
Will only exit once all given chat rooms where successfully joined
- async send_message(room, text)#
- class twitchAPI.chat.ChatRoom#
Bases:
object
ChatRoom(name: str, is_emote_only: bool, is_subs_only: bool, is_followers_only: bool, is_unique_only: bool, follower_only_delay: int, room_id: str, slow: int)
- __init__(name, is_emote_only, is_subs_only, is_followers_only, is_unique_only, follower_only_delay, room_id, slow)#
- enum twitchAPI.chat.ChatEvent(value)#
Bases:
Enum
An enumeration.
Valid values are as follows:
- READY = <ChatEvent.READY: 'ready'>#
- MESSAGE = <ChatEvent.MESSAGE: 'message'>#
- SUB = <ChatEvent.SUB: 'sub'>#
- RAID = <ChatEvent.RAID: 'raid'>#
- ROOM_STATE_CHANGE = <ChatEvent.ROOM_STATE_CHANGE: 'room_state_change'>#
- JOIN = <ChatEvent.JOIN: 'join'>#
- JOINED = <ChatEvent.JOINED: 'joined'>#
- LEFT = <ChatEvent.LEFT: 'left'>#
- class twitchAPI.chat.RoomStateChangeEvent#
Bases:
EventData
Triggered when a room state changed
- __init__(chat, prev, new)#
- old: Optional[ChatRoom]#
The State of the room from before the change, might be Null if not in cache
- property room#
Returns the Room from cache
- chat: Chat#
The
twitchAPI.chat.Chat
instance