TwitchIO Bot

A modular Twitch bot built with TwitchIO, featuring:

• OAuth-based multi-channel support
• EventSub integration
• Component-based command system
• SQLite-backed token storage
• Modern Python tooling (uv, Ruff, Pylance)

---

🚀 Features

• 🔐 OAuth authentication for bot + broadcaster
• 📡 EventSub subscriptions (chat, stream online, channel points)
• 🧩 Component system for commands/plugins
• 💾 Persistent token storage using SQLite
• 💬 Chat → Discord logging via webhook
• 🎵 Spotify song requests + now playing command
• ⚡ Fast development setup with uv and Ruff

---

📦 Requirements

• Python 3.11+

• A Twitch Developer Application

• Two Twitch accounts:

  • Bot account
  • Main broadcaster account

---

🔧 Create a Twitch Application

Before running the bot, you need to create a Twitch application.

1. Go to the Twitch Developer Console: https://dev.twitch.tv/console

2. Click "Register Your Application"

3. Fill in the form:

   • Name: (e.g. My Twitch Bot)

   • OAuth Redirect URL:

     http://localhost:4343/oauth/callback
     

   • Category: Application Integration

4. Click Create

5. Once created:

   • Copy your Client ID
   • Generate and copy your Client Secret

---

⚠️ Important:

• The redirect URL must match exactly: http://localhost:4343/oauth/callback
• Do not share your Client Secret

---

⚙️ Setup

1. Clone the repository

git clone <your-repo-url>
cd <repo-name>

---

2. Install dependencies

Using uv:

uv sync

---

3. Configure environment variables

Create your env files from the examples:

cp .env.example .env
cp .env.secret.example .env.secret

Fill in:

.env.secret

TWITCH_CLIENT_ID=your_client_id
TWITCH_CLIENT_SECRET=your_client_secret
CHAT_TO_DISCORD_LOGGER_WEBHOOK_URL=your_discord_webhook_url

# Optional: Spotify
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

.env

TWITCH_BOT_ID=your_bot_user_id
TWITCH_OWNER_ID=your_main_account_user_id
DATABASE_NAME=tokens.db

# Optional: Spotify
SPOTIFY_CHANNEL_REWARD_ID=your_channel_point_reward_id
SPOTIFY_TWITCH_REQUEST_PLAYLIST_ID=your_playlist_id

---

4. Get required IDs

You need the numeric Twitch user IDs for both your bot account and your main account.

You can easily convert a username to a user ID using:

👉 https://streamscharts.com/tools/convert-username

1. Enter your Twitch username
2. Copy the returned User ID

---

Example (Username → ID)

If your username is:

my_twitch_name

You will get something like:

123456789

---

Add to .env

TWITCH_BOT_ID=bot_account_user_id
TWITCH_OWNER_ID=your_main_account_user_id

---

🧠 Why this is needed

Twitch APIs (including EventSub) require user IDs, not usernames.

---

▶️ Running the bot

uv run main.py

This will:

• Start the bot
• Launch a local OAuth server at http://localhost:4343

---

🔑 OAuth Setup

You must authorise both accounts.

---

1. Authorise the Bot Account

Open a private/incognito browser.

Log in as the bot account, then visit:

Bot Account OAuth URL:

http://localhost:4343/oauth?scopes=user:read:chat%20user:write:chat%20user:bot%20channel:bot%20channel:read:ads%20channel:read:redemptions%20channel:manage:redemptions%20channel:manage:ads%20channel:manage:moderators%20channel:manage:polls%20channel:manage:predictions%20channel:manage:vips%20channel:edit:commercial%20channel:moderate%20moderator:manage:announcements%20moderator:read:banned_users%20moderator:manage:banned_users%20moderator:read:chat_messages%20moderator:manage:chat_messages&force_verify=true

---

2. Authorise the Broadcaster Account

In your normal browser (logged into your main account), visit:

Broadcaster OAuth URL:

http://localhost:4343/oauth?scopes=channel:bot&force_verify=true

⚠️ Make sure the bot is running before opening the OAuth links, otherwise the authentication will fail.

⚠️ If you see a redirect error, double-check your Twitch application redirect URL matches exactly: http://localhost:4343/oauth/callback

---

🎵 Spotify Setup (Optional)

To enable Spotify song requests:

1. Go to: https://developer.spotify.com/dashboard
2. Create an application
3. Add redirect URI:

http://localhost:8888/callback

4. Copy Client ID + Secret into .env.secret

---

🎯 What it enables

• Users redeem a channel point reward with a Spotify link

• Bot:

  • Adds song to queue
  • Saves to playlist
  • Confirms in chat

Command:

!song

→ Displays currently playing track

---

✅ First Run Checklist

Before using the bot, make sure everything is set up correctly:

• Twitch application created in Developer Console
• Redirect URL set to http://localhost:4343/oauth/callback
• .env and .env.secret created and filled in
• Correct CLIENT_ID and CLIENT_SECRET added
• Discord webhook URL added (CHAT_TO_DISCORD_LOGGER_WEBHOOK_URL)
• (Optional) Spotify credentials configured
• Correct BOT_ID and OWNER_ID added
• Dependencies installed (uv sync)
• Bot is running (uv run main.py)
• OAuth completed for bot account
• OAuth completed for broadcaster account
• Bot account has moderator/VIP permissions in your channel (if required)

---

🎯 Expected Result

If everything is working correctly:

• Bot connects without errors
• OAuth completes successfully
• Bot responds to commands in chat
• Chat messages appear in your Discord webhook
• Spotify requests are added to queue (if enabled)
• Tokens are saved to data/tokens.db

---

💾 Database

• Stored in: data/tokens.db

• Automatically created on startup

• Stores:

  • user_id
  • access token
  • refresh token

---

🧩 Components

Commands are modular and live in:

bot/components/

Each component:

• Is auto-loaded on startup
• Must not start with _
• Uses TwitchIO’s commands.Component

---

🔌 Example Component: Chat → Discord Logger

(unchanged)

---

🎵 Example Component: Spotify Integration

Handles Twitch channel point song requests.

---

✨ What it does

• Accepts Spotify links from channel point rewards
• Adds songs to playback queue
• Saves songs to a playlist
• Provides !song command

---

📁 Location

bot/components/spotify.py

---

⚠️ Notes

• Requires Spotify Premium for queue control
• Requires valid Spotify OAuth setup
• Only accepts Spotify track links

---

🛠 Development

Linting & Formatting

uv run ruff check . --fix
uv run ruff format .

---

Recommended VS Code Extensions

• Python
• Pylance
• Ruff

---

📁 Project Structure

bot/
├── app.py          # Bot implementation
├── config.py       # Environment + paths
├── database.py     # Token persistence
├── components/     # Command modules

main.py             # Entry point
pyproject.toml      # Project config

---

⚠️ Notes

• Do NOT commit .env or .env.secret
• Tokens are stored locally in SQLite
• First run requires OAuth setup
• Bot must remain running during OAuth

---

🙌 Credits

Built with:

• TwitchIO
• Spotipy
• asqlite
• Ruff
• uv