Skip to main content

​
Environment variables

The bot uses environment variables for configuration. All variables should be defined in a .env file in the root directory.

​
Required variables

The bot will not start without these variables. It validates their presence on startup in src/index.ts.

​
DISCORD_TOKEN

Your Discord bot token from the Discord Developer Portal.
.env
DISCORD_TOKEN=your_bot_token_here
Never commit your bot token to version control. Keep .env in your .gitignore file.
The bot validates this token on startup:
src/index.ts
const token = process.env.DISCORD_TOKEN;

if (!token) {
  logger.error("DISCORD_TOKEN is not set in environment variables");
  process.exit(1);
}

​
CLIENT_ID

Your Discord application’s client ID, required for deploying slash commands.
.env
CLIENT_ID=your_client_id_here
To find your client ID:
1

Open Developer Portal

Go to discord.com/developers/applications
2

Select your application

Click on your bot application
3

Copy Application ID

On the “General Information” page, copy the “Application ID”

​
Optional variables

​
GUILD_ID

A Discord server (guild) ID for testing. When set, commands deploy instantly to this guild instead of globally.
.env
GUILD_ID=123456789012345678
Global vs Guild deployment:
  • Guild deployment: Instant, but commands only work in the specified server
  • Global deployment: Takes up to 1 hour to propagate, but works in all servers
Use GUILD_ID during development, then remove it for production.
To find your guild ID:
1

Enable Developer Mode

In Discord, go to User Settings > Advanced > Enable “Developer Mode”
2

Copy Server ID

Right-click your server icon and select “Copy Server ID”

​
LOG_LEVEL

Optional logging level for debugging. When set to debug, the bot will output detailed platform check results and internal operations.
.env
LOG_LEVEL=debug
Available values:
  • debug - Show all logs including platform checks
  • Not set (default) - Show only info, warnings, and errors
From src/utils/logger.ts: 
debug(message: string, ...args: unknown[]): void {
  if (process.env.LOG_LEVEL === "debug") {
    console.log(formatMessage("debug", message, ...args));
  }
}

​
Environment file example

Your complete .env file should look like this:
.env
# Discord Bot Token (required)
DISCORD_TOKEN=your_bot_token_here

# Discord Application ID (required for command deployment)
CLIENT_ID=your_client_id_here

# Optional: Guild ID for testing (deploys commands instantly to this guild)
# Leave empty for global deployment (takes up to 1 hour to propagate)
GUILD_ID=

​
Discord permissions

The bot requires specific permissions to function properly.

​
Gateway Intents

Enable these intents in the Discord Developer Portal under Bot > Privileged Gateway Intents:

Guilds

Required to receive guild events and access server information

Guild Messages

Required to send notifications and interact with channels

​
Bot Permissions

When generating an invite link, ensure these permissions are selected:
PermissionRequiredPurpose
Send MessagesYesSend stream notifications
Embed LinksYesDisplay rich stream embeds
Use External EmojisYesShow platform emojis (🟢 🟣 🔴)
The minimum permission integer is 18432 (Send Messages + Embed Links + Use External Emojis)

​
Command Permissions

Some commands require elevated permissions:
CommandRequired PermissionPurpose
/streamer addManage ChannelsPrevents non-moderators from adding streamers
/streamer removeManage ChannelsPrevents non-moderators from removing streamers
/streamer listNoneAnyone can view tracked streamers
/helpNoneAnyone can access help
/pingNoneAnyone can check bot status
Users with “Manage Channels” permission can add/remove streamers. Configure Discord roles carefully to control who can manage the bot.

​
Bot invite URL

Generate an invite URL with the correct permissions:
1

Open OAuth2 URL Generator

In the Discord Developer Portal, navigate to OAuth2 > URL Generator
2

Select scopes

Check these boxes:
  • bot
  • applications.commands
3

Select permissions

Check these boxes:
  • Send Messages
  • Embed Links
  • Use External Emojis
4

Copy and share URL

Copy the generated URL at the bottom and use it to invite the bot to servers
Your invite URL will look like: 
https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=18432&scope=bot%20applications.commands

​
Data storage

The bot uses Enmap for persistent storage with zero configuration required.
No database setup needed - Enmap automatically creates and manages local database files.

​
Stored data

The bot stores the following data per Discord server:
  • Tracked streamers (username, platform, notification channel)
  • Live status cache (current stream title, viewer count)
  • Last alert timestamp (prevents duplicate notifications)

​
Data location

Enmap creates a data directory in the bot’s root folder with SQLite databases: 
streamer-alerts-bot/
├── data/
│   └── streamers.sqlite
├── src/
├── .env
└── package.json
Back up the data directory regularly to prevent data loss.

​
Advanced configuration

​
Polling interval

The bot checks streamer status every 60 seconds by default. This is hardcoded in the polling loop. To adjust the interval, modify the polling implementation in the codebase: 
// Check every 60 seconds (60000ms)
setInterval(checkStreamers, 60000);
Shorter intervals provide faster alerts but increase API request load. 60 seconds is recommended for reliability.

​
Error handling

The bot includes global error handlers that log errors and prevent crashes:
src/index.ts
process.on("uncaughtException", (error) => {
  logger.error("Uncaught exception:", error);
  process.exit(1);
});

process.on("unhandledRejection", (reason) => {
  logger.error("Unhandled rejection:", reason);
});

​
Production deployment

For production environments:
1

Use a process manager

Run the bot with PM2 or similar to ensure automatic restarts:
npm install -g pm2
pm2 start dist/index.js --name streamer-alerts
pm2 save
pm2 startup
2

Remove GUILD_ID

Set GUILD_ID= to empty in .env for global command deployment
3

Enable logging

Configure log output to a file or logging service for monitoring
4

Secure environment variables

Ensure .env has restricted file permissions:
chmod 600 .env

​
Next steps

Usage guide

Learn how to use bot commands and manage streamer notifications

Build docs developers (and LLMs) love

Get started for freeTalk to us