How to capture moderation events in Twitch IRC bot using Python

Other Questions Twitch
1

I’m building a Python IRC bot that monitors multiple Twitch streams simultaneously. The bot successfully captures regular chat messages, but I need help collecting moderation events like bans and timeouts. Here’s my current implementation:

import socket
import time

chat_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
chat_socket.connect((HOST, PORT_NUM))
chat_socket.send(f"PASS {TOKEN}\n".encode('utf-8'))
chat_socket.send(f"NICK {BOT_NAME}\n".encode('utf-8'))
chat_socket.send(f"JOIN {TARGET_CHANNEL}\n".encode('utf-8'))

while True:
    data = chat_socket.recv(1024).decode('utf-8')
    if data == "PING :tmi.twitch.tv\r\n":
        chat_socket.send("PONG :tmi.twitch.tv\r\n".encode('utf-8'))
    
    print(data)
    time.sleep(0.5)

This code works fine for regular messages but doesn’t capture moderation actions. What do I need to modify to receive ban and timeout notifications through the IRC connection?

2

You’re missing the membership capability - that’s key for getting full moderation data. Add CAP REQ :twitch.tv/membership\r\n to your capability requests. You’ll get JOIN/PART events and more detailed user info that helps make sense of the moderation actions. Here’s something I learned the hard way: CLEARCHAT events come in batches when there’s heavy moderation, so your 1024-byte recv buffer won’t cut it. I bumped mine to 4096 after missing events during raids. Also, message deletions come through CLEARMSG commands, not CLEARCHAT. Parse for both if you want complete coverage of mod activities.

3

Socket timeouts will bite you with this approach. I hit disconnections after a few hours because Twitch kills idle connections without warning. Use chat_socket.settimeout(300) and wrap your recv calls in try-except blocks to handle timeouts. When you get capabilities working, watch the message formats - CLEARCHAT for channel-wide clears vs user-specific actions have different structures. I store raw IRC tags in a separate parsing function to debug what’s actually coming through. Some channels disable certain moderation broadcasts, so don’t expect to get everything even with proper capabilities enabled.

4

don’t forget to parse the data properly - i made this same mistake. right now you’re just printing raw data, but moderation events need specific regex patterns. try if 'CLEARCHAT' in data: then grab the username after the colon. also add some error handling cuz twitch irc gets flaky and will crash your bot without try/catch blocks.

5

Others covered the capability requests - those are essential. But here’s something that took me weeks to debug: Twitch’s moderation events include IRC tags with special characters that’ll corrupt if you’re not careful with decoding. I switched to decode('utf-8', errors='ignore') after getting random UnicodeDecodeError crashes during heavy moderation. Also, some mod actions fire multiple CLEARCHAT messages back-to-back, especially when clearing chat history. Your recv loop handles one message at a time, but these events come in faster than that 0.5 second sleep. I split the received data on \r\n and process each line separately - otherwise you’ll miss events that arrive in the same packet.

6

This is a common Twitch IRC issue. Your setup only gets standard PRIVMSG events, but you need extra capabilities for moderation actions. Send these capability requests after authentication but before joining channels. Add these lines right after your NICK command: chat_socket.send(“CAP REQ :twitch.tv/commands\r\n”.encode(‘utf-8’)) chat_socket.send(“CAP REQ :twitch.tv/tags\r\n”.encode(‘utf-8’)). After that, you’ll start getting CLEARCHAT messages for bans and timeouts. Timeouts look like @ban-duration=600 :tmi.twitch.tv CLEARCHAT #channel :username while permanent bans don’t have the duration tag. The tags capability gives you extra metadata that’s helpful for tracking moderation context. I’ve been running this setup across 15 channels and it’s been solid for catching all moderation events.