🤖 A simple Discord bot that maintains a list of live Twitch streams in a Discord channel.
This readme was originally written for use with the Heroku free tier, however as Heroku has gotten rid of it, it's been repurposed for any generic server (I use Ubuntu).
Many bots simply post to a Discord channel when a streamer has gone live, the post gives you no indication as to whether the streamer is still live or what their status is, leading to the information in the channel becoming stale quickly.
This bot creates a card in the channel which updates throughout the duration of the streamer's stream, with uptime, viewcount, and a screenshot of their stream.
Once the streamer goes offline, the bot deletes the card, ensuring that the posts in your discord channel are all up-to-date and only referring to streamers who are live right now.
Multiple streamers can be added to the watch list, at your (or any server admin's) discretion.
- Maintains a real-time list of live streamers.
- Per-channel configuration: Each streamer can be configured for specific channels.
- Per-role mentions: Each streamer can have specific roles mentioned when they go live.
- Monitors Twitch streamers and posts on discord when they're live.
- Continously updates streamer card in the channel with uptime/game changes + screenshot.
- Deletes streamer card from channel when streamer goes offline.
- Discord slash commands to add/remove/list/reset watched streamers (
/watch,/unwatch,/list,/reset).
This is written for beginners, but it is expected that you at least know how to use basic unix shell commands.
Requirements
A server (this guide uses Ubuntu) where you have sudo.
Instructions
- Install Node
- Here's a decent guide on how to install node. I recommend using NVM (Option 3). This bot was built in node v18 so any LTS in v18 should be fine.
- Install a Node Process Manager
- I use PM2
npm install pm2@latest -g
- I use PM2
- Install PostgreSQL
sudo apt update- Install PostgreSQL
sudo apt install postgresql postgresql-contrib - Run PostgreSQL
sudo systemctl start postgresql.service - Create a user
sudo -u postgres createuser --interactive- Enter a name of your choice (the easiest is to use the same name as your unix username)
- Superuser: Y
- Set a psql password for the user
psql- Enter and remember a password for the user.
\password - Quit psql
\q
- Create a DB
sudo -u postgres createdb twitchmon
- Get the Bot
- Clone the repo into a folder on the server
git clone https://github.com/brofar/TwitchMonitor.git - Rename
.env.sampleto.env. - Set the
DATABASE_URLtopostgres://[username]:[password]@localhost:5432/twitchmon.- Swap
[username]with the psql username you created above. - Swap
[password]with the psql password you set above.
- Swap
- Clone the repo into a folder on the server
- Get a Discord Token
- Generate a Discord bot token by following this guide.
- Copy the token into
DISCORD_BOT_TOKENin your.envfile.
- Copy your Discord application's Client ID to the
DISCORD_CLIENT_IDin your.envfile - Get a Twitch Token
- Create a Twitch app on the Twitch Developer Console (When it asks, set the OAuth Redirect URL to
http://localhost) - Copy the Twitch
Client IDinto theTWITCH_CLIENT_IDin your.envfile. - Copy the Twitch
Client Secretinto theTWITCH_CLIENT_SECRETin your.envfile.
- Create a Twitch app on the Twitch Developer Console (When it asks, set the OAuth Redirect URL to
- Deploy the Slash Commands
cdinto the bot's directorynpm run deploy- Start the Bot
pm2 start app.js --name twitch-monitor
- Invite the Bot to your Discord Server
- Go to
https://discord.com/api/oauth2/authorize?client_id=[BOT_CLIENT_ID]&permissions=8&scope=bot- Swap
[BOT_CLIENT_ID]in the URL above for your Discord app's client id. - If you want to lock down the announcement channel so nobody but the bot can post, ensure that the bot has permissions at minimum to Send Messages, Manage Messages, and Embed Links.
- Swap
- Go to
Adds one or more Twitch streamers to the watch list for a specific channel with optional role mentions.
Parameters:
channel: The Discord channel where live notifications will be posted (required)role: The role to mention when the streamer goes live (optional)streamers: Space-separated list of Twitch usernames to watch (required)
Usage: /watch channel:#streams role:@gamers streamers:shroud ninja lirik
Features:
- Validates that the selected channel is in the same server
- Checks bot permissions for the channel and role
- Provides detailed feedback on added/skipped/duplicate streamers
- Allows the same streamer to be watched in multiple channels with different roles
Removes one or more Twitch streamers from the watch list.
Parameters:
streamers: Space-separated list of Twitch usernames to stop watching (required)
Usage: /unwatch streamers:shroud ninja
Note: This removes the streamer from ALL channels in the current server.
Lists all streamers the bot is currently watching in the server, organized by streamer with their configured channels and roles.
Usage: /list
Output: Shows streamers grouped with their respective channels and role mentions.
Removes ALL streamers and configurations from the current server. This is useful for completely resetting the bot's configuration.
Parameters:
confirm: Must be set toTrueto confirm the action (required)
Usage: /reset confirm:True
- All streamer watches from all channels
- All channel configurations
- All role mention settings
Use this command carefully - it's intended for completely resetting the bot's configuration in your server.
If you're upgrading from an older version of Twitch Monitor that used the old database structure (with a single channel per guild), you'll need to migrate your database to the new structure that supports per-channel and per-role configuration.
The bot will automatically detect if you're using the old database structure and perform the migration when you start it. The migration process:
- Detects the old database structure
- Creates backup tables to preserve your data
- Migrates your existing streamer configurations to use the channel specified in your old config
- Updates the database schema to the new structure
- Cleans up old tables and backups
If you prefer to run the migration manually, you can use the migration script:
npm run migrateOr run it directly:
node migrate-db.js- Streamer configurations: All streamers you were watching will continue to be watched
- Channel assignments: Streamers will be assigned to the channel that was configured in your old setup
- Guild settings: All guild-specific settings are preserved
- Role assignments: Initially set to null (no role mentions), you can configure these using the new
/watchcommand
After migration, you can:
- Use the new
/watchcommand to add streamers to specific channels with optional role mentions - Use
/unwatchto remove streamers - Use
/listto see all configured streamers with their channels and roles
The old commands are no longer supported in the new version.
After setting up the bot, you need to deploy the slash commands to Discord:
npm run deployOr run it directly:
node deploy-commands.jsThis only needs to be done once when you first set up the bot, or when you update command definitions. The bot will automatically load all commands from the commands/ directory.