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 alpha stage!
Bugs and oddities are to be expected.
Please report all feature requests and bug requests to the github page.
Commands#
Chat commands are specific messages user can send in chat in order to trigger some action of your bot.
Example:
<User123>: !say Hello world
<MyBot>: User123 asked me to say "Hello world"
You can register listeners to chat commands using register_command()
.
The bot prefix can be set by using set_prefix()
, the default is !
Your command listener function needs to be async and take in one parameter of type ChatCommand
.
Example:
async def say_command_handler(cmd: ChatCommand):
await cmd.reply(f'{cmd.user.name} asked me to say "{cmd.parameter}")
chat.register_command('say', say_command_handler)
Events#
You can listen to different events happening in the chat rooms you joined.
Generally you register a event listener using register_event()
.
The first parameter has to be of type ChatEvent
and the second one is your listener function.
Those Listeners always have to be async functions taking in one parameter (the payload). The Payload type is described below.
Example:
async def on_ready(cmd: EventData):
await cmd.chat.join_room('teekeks42')
chat.register_event(ChatEvent.READY, on_ready)
Bot Ready#
This Event is triggered when the bot is started up and ready to join channels.
Message send#
ChatEvent:
MESSAGE
Payload:
ChatMessage
This Event is triggered when someone wrote a message in a channel we joined
Channel Subscription#
This Event is triggered when someone subscribed to a channel we joined.
Raid#
ChatEvent:
RAID
Payload:
dict
Triggered when a channel gets raided
Channel config changed#
ChatEvent:
ROOM_STATE_CHANGE
Payload:
RoomStateChangeEvent
Triggered when a channel is changed (e.g. sub only mode was enabled)
User channel join#
Triggered when someone other than the bot joins a channel.
Note
this will not always trigger, depending on channel size
User channel leave#
Note
this will not always trigger, depending on channel size
Bot channel join#
ChatEvent:
JOINED
Payload:
JoinedEvent
Triggered when the bot joins a channel
Bot channel leave#
Triggered when the bot left a channel
Message delete#
ChatEvent:
MESSAGE_DELETE
Payload:
MessageDeletedEvent
Triggered when a single message in a channel got deleted
User messages cleared#
ChatEvent:
CHAT_CLEARED
Payload:
ClearChatEvent
Triggered when a user was banned, timed out and/or all messaged from a user where deleted
Bot recieves whisper message#
ChatEvent:
WHISPER
Payload:
WhisperEvent
Triggered when someone whispers to your bot.
Note
You need the WHISPERS_READ
Auth Scope to receive this Event.
Server notice#
ChatEvent:
NOTICE
Payload:
NoticeEvent
Triggered when server sends a notice message.
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())
Class Documentation#
- class twitchAPI.chat.Chat#
Bases:
object
The chat bot instance
- __init__(twitch, connection_url=None, is_verified_bot=False, initial_channel=None)#
- Parameters:
twitch (
Twitch
) – A Authenticated twitch instanceconnection_url (
Optional
[str
]) – alternative connection urlDefault:None
is_verified_bot (
bool
) – set to true if your bot is verified by twitchDefault:False
initial_channel (
Optional
[List
[str
]]) – List of channel which should be automatically joined on startupDefault:None
-
log_no_registered_command_handler:
bool
# Controls if instances of commands being issued in chat where no handler exists should be logged.
Default:True
- set_prefix(prefix)#
Sets a command prefix.
The default prefix is !, the prefix can not start with / or .
- Parameters:
prefix (
str
) – the new prefix to use for command parsing- Raises:
ValueError – when the given prefix is None or starts with / or .
- 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
- Parameters:
name (
str
) – the name of the commandhandler (
Callable
[[ChatCommand
],Awaitable
[None
]]) – The event handler
- Raises:
ValueError – if handler is not a coroutine
- Return type:
- unregister_command(name)#
Unregister a already registered command.
- register_event(event, handler)#
Register a event handler
- unregister_event(event, handler)#
Unregister a handler from a event
- is_ready()#
Returns True if the chat bot is ready to join channels and/or receive events
- Return type:
- is_mod(room)#
Check if chat bot is a mod in a channel
- is_subscriber(room)#
Check if chat bot is a subscriber in a channel
- is_in_room(room)#
Check if the bot is currently in the given chat room
- async join_room(chat_rooms)#
join one or more chat rooms
Will only exit once all given chat rooms where successfully joined or
twitchAPI.chat.Chat.join_timeout
run out.
- async send_raw_irc_message(message)#
Send a raw IRC message
- Parameters:
message (
str
) – the message to send- Raises:
ValueError – if bot is not ready
- async send_message(room, text)#
Send a message to the given channel
Please note that you first need to join a channel before you can send a message to it.
- Parameters:
- Raises:
ValueError – if message is empty or room is not given
ValueError – if bot is not ready
- async leave_room(chat_rooms)#
leave one or more chat rooms
Will only exit once all given chat rooms where successfully left
- class twitchAPI.chat.ChatUser#
Bases:
object
Represents a user in a chat channel
- __init__(chat, parsed, name_override=None)#
- 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
- __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 send(message)#
Sends a message to the channel the command was issued in
- Parameters:
message (
str
) – the message you want to send
- 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)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- 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
Represents the possible events to listen for using
register_event()
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'>#
- USER_LEFT = <ChatEvent.USER_LEFT: 'user_left'>#
- MESSAGE_DELETE = <ChatEvent.MESSAGE_DELETE: 'message_delete'>#
- CHAT_CLEARED = <ChatEvent.CHAT_CLEARED: 'chat_cleared'>#
- WHISPER = <ChatEvent.WHISPER: 'whisper'>#
- NOTICE = <ChatEvent.NOTICE: 'notice'>#
- 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
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.JoinEvent#
Bases:
EventData
- __init__(chat, channel_name, user_name)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.JoinedEvent#
Bases:
EventData
- __init__(chat, channel_name, user_name)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.LeftEvent#
Bases:
EventData
When the bot or a user left a room
- __init__(chat, channel_name, room, user)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.ClearChatEvent#
Bases:
EventData
- __init__(chat, parsed)#
-
banned_user_id:
Optional
[str
]# The ID of the user who got banned or timed out. if
duration
is None, the user was banned. Will be None when the user was not banned nor timed out.
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.WhisperEvent#
Bases:
EventData
- __init__(chat, parsed)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.MessageDeletedEvent#
Bases:
EventData
- __init__(chat, parsed)#
- chat: Chat#
The
twitchAPI.chat.Chat
instance
- class twitchAPI.chat.NoticeEvent#
Bases:
EventData
Represents a server notice
- __init__(chat, parsed)#
-
msg_id:
str
# Message ID of the notice, Msg-id reference
- chat: Chat#
The
twitchAPI.chat.Chat
instance