What is BotOfTheSpecter?

BotOfTheSpecter is a cloud-based Twitch chat bot that runs entirely on our servers. You don't need to install any software, run servers, or manage technical infrastructure. Just connect your Twitch account and start using the bot immediately!

Troubleshooting

Setup Complete!

Premium Features

Some advanced features require a premium subscription:

• AI Chat: Have conversations with an AI in your chat
• Advanced Music: Use !song without connecting Spotify
• Shared Bot Name (BotOfTheSpecter): The default shared bot username used across the platform
• Custom Bot Name (Experimental/Coming Soon): Use your own bot username instead of BotOfTheSpecter

Support the developer on Twitch to unlock these features!

Support on Twitch

Need Help?

If you encounter issues during setup, don't hesitate to reach out:

Chat Protection & Custom Commands

Link Protection

URL blocking is disabled by default. You must enable it before the bot will remove links posted by non-moderators. Moderators & Broadcasters are always exempt.

• When enabled, any viewer who posts a link will have their message deleted.
• Use !permit @username to give a viewer a 30-second window to post one link.
• Toggle URL blocking from Integrations → Specter Modules → Chat Protection in the dashboard.
• Add trusted domains to the Link Whitelist so they always bypass URL blocking, without needing a permit.

Blocked Terms Beta

Separately from link blocking, you can keep a list of forbidden words. Any message containing a blocked term is deleted automatically. Configure it under Integrations → Specter Modules → Chat Protection in the dashboard.

Custom Commands

Create unlimited custom commands from the dashboard or directly in chat.

• !addcommand !name response — creates a new command.
• !editcommand !name new response — updates an existing command.
• !removecommand !name — deletes a command.
• Give a command a permission level by quoting the response: !addcommand !name "response text" mod (levels: everyone, mod, vip, subscribers, broadcaster). Beta

Responses support the full variables system — including (user), (count), (customapi.URL), math expressions, and more.

Commands can also have aliases — extra trigger words that redirect to the same command and share its cooldown. Beta

Timed Messages

Schedule messages to post automatically at a set interval. Manage them under Commands → Timed Messages.

• Set the interval in minutes and a minimum chat-line threshold so messages only fire when chat is active.
• Multiple timed messages can run simultaneously.
• Supports the same dynamic variables as custom commands.

Bot Modes

Games & Fun

Points-Based Games

These games consume or award bot points. The points system must be enabled in Settings → Bot Points.

Social & Party Commands

Raffle System Beta

Lotto System

A Channel Points-based lotto system where viewers redeem Channel Point rewards to get their lotto numbers. Winning numbers are automatically generated when the stream goes live, and moderators draw prizes across multiple divisions, awarding Bot Points to the winners.

Setup

1. Create a Channel Point reward on Twitch for lotto entry.
2. In the Specter dashboard, sync your Channel Point rewards.
3. Edit the lotto reward and add (lotto) to the custom message — this generates the viewer's lotto numbers.
4. Viewers redeem the reward to receive their numbers and enter the draw.

Commands

• !startlotto (Moderator) — manually generates the winning numbers (they are also generated automatically when the stream goes live).
• !drawlotto (Moderator) — compares entries to winning numbers and awards Bot Points by division: Division 1 (100,000), Division 2 (50,000), Division 3 (10,000), Division 4 (5,000), Division 5 (1,000), Division 6 (500).

Events & Alerts

BotOfTheSpecter reacts to Twitch events automatically. All response messages are customisable from Settings → Alerts in the dashboard and support the variables system.

Overlay Alerts

Events are forwarded to the WebSocket server and displayed through OBS browser source overlays at:
https://overlay.botofthespecter.com/alert.php?code=YOUR_API_KEY

Tracking & Stats

Bot Points

A built-in loyalty point system earned by chatting and participating in the stream, with bonus points for new follows, subscriptions, cheers, and raids. Configure the name, earn rate, and icon under Settings → Bot Points.

• !points — check your balance.
• !addpoints / !removepoints — moderator manual adjustment.
• Spent playing !gamble, !slots, and !roulette.
• !store / !store <item> — browse or redeem rewards from the point store. Beta

Watch Time

Tracks total viewing time per viewer across all streams. Viewers check their own with !watchtime.

Lurk Tracking

• !lurk — starts tracking and announces the viewer is lurking.
• !unlurk — ends tracking and announces the viewer is back.
• !lurking — shows how long the user has been lurking this session.
• !lurklead — shows who has the most accumulated all-time lurk time.
• !userslurking — shows how many viewers are currently lurking.

Death Counter

Tracks in-game deaths for the current session.

• !deaths — shows the count (anyone).
• !deathadd / !death+ — adds to the counter (moderator).
• !deathremove / !death- — removes from the counter (moderator).

Typo Counter

• !typo @user — records a typo for a user (moderator).
• !typos [@user] — shows the typo count.
• !edittypos @user <n> — sets the count to a specific number (moderator).
• !removetypos @user — decrements or resets (moderator).

Quotes

• !quote [number] — shows a random quote or one by number.
• !quoteadd <text> — saves a new quote (moderator).
• !removequote <number> — deletes a quote (moderator).

Bits Tracking

• !mybits — shows the user's total all-time bits cheered in the channel.
• !cheerleader — shows the all-time top bit cheerer.

Follow Age

!followage [@user] queries the Twitch API to show exactly how long a viewer has been following the channel.

Working & Study

A productivity overlay for co-working streams.

• !task <name> — sets your active task on the overlay.
• !done [n] — finishes your active task (or multiple backlog items like !done 2; 4; 5) and awards points.
• !later <name> / !soon <name> — queues tasks into your backlog.
• !backlog — views your pending tasks.
• !personaltimer <minutes> <label> — starts a personal focus timer (also supports cycles like 50/10/4).
• !project <name> — organises your tasks into specific projects.
• !tasktimer — broadcaster/mod controls for the main overlay timer (e.g. !tasktimer auto on).
• !taskhelp — outputs a summary of these commands in chat.

Subathon Timer

A countdown timer that extends with subs and bits (cheers) to drive engagement during subathon events. Check remaining time with !subathon status. Configure time additions per sub tier from the dashboard.

Integrations

BotOfTheSpecter connects to a wide range of third-party services to enhance your stream. All integrations are configured from Integrations in the dashboard.

Troubleshooting Common Issues

• Redirect URI mismatch: Ensure the Redirect URI in your Spotify app matches exactly:
  https://dashboard.botofthespecter.com/spotifylink.php
• Permissions: The required scopes (user-read-playback-state, user-modify-playback-state, user-read-currently-playing) are automatically requested during authorization.
• Rate limits: Spotify has rate limits — if you exceed them, wait a moment before trying again.
• Authorization fails: Double-check that your Client ID and Client Secret are correct and that the Redirect URI matches exactly.

What is TTS & How to Set It Up

The Text-to-Speech (TTS) module allows BotOfTheSpecter to read messages aloud in your stream. You can customize which voice is used, and the TTS will play through your audio overlay. This is perfect for announcements, alerts, and enhancing viewer engagement.

Setting Up TTS

1. Navigate to the TTS Settings section in the BotOfTheSpecter dashboard.
2. Choose your preferred voice from the available options (see the Available Voices section below).
3. Set up your audio overlay to hear TTS output — see the OBS Audio Monitoring guide.
4. Test your setup with a sample message.

Using TTS with Channel Points

TTS is triggered through Twitch Channel Points redemptions. Viewers can redeem a Channel Point reward to have a message read aloud using the voice you've selected in TTS settings.

Using TTS with the Point Store Beta

On the beta bot, viewers can also trigger TTS by buying a TTS item from your Point Store, spending their bot loyalty points instead of Twitch Channel Points. Their message is read aloud with the same voice configured in your TTS settings.

Available Voices

Click the play button next to each voice to hear a sample:

Troubleshooting TTS

• No audio output: Verify that your audio overlay is correctly configured in OBS and that audio monitoring is enabled. See the OBS Audio Monitoring guide.
• Wrong voice playing: Check that you've saved the correct voice in TTS settings on the dashboard.
• Audio too quiet or too loud: Adjust the volume slider on the audio overlay source in OBS.
• TTS not responding: Ensure the TTS module is enabled on the dashboard and the bot has proper channel permissions.

Why Audio Monitoring?

Audio monitoring lets you hear audio from your overlays — sound alerts, TTS, and walk-ons — directly through OBS, ensuring they play correctly during your stream.

Part 1: Configure OBS Audio Settings

2

Go to Settings

Click the Settings button in the bottom-right corner of the OBS window.

3

Select the Audio Tab

In the Settings window, click the Audio tab.

4

Configure Monitoring Device

Under Monitoring Device, select your desired audio output (e.g., headphones or speakers). Choose Default or your primary device.

Part 2: Add the Overlay Browser Source

Troubleshooting

Universal Variables

These work in every message type — custom commands, channel point rewards, and event alerts. Timed messages are the exception: on the live bot only (game) is currently replaced in timed messages; full variable support in timed messages is a Beta feature.

Channel Point Reward Variables

Event Alert Variables

Event-specific tokens for welcome messages, ad notices, and Twitch chat alerts (followers, subs, raids, bits, hype trains). Every Universal Variable above also works here — the event-specific tokens below are available in addition to them, because all alert messages run through the same variable-processing engine as custom commands.

General Variables (available across multiple event modules)

Follower Alert

Bits & Cheers

Raid

Hype Train

Standard Subscriptions

Gift Subscriptions

Subscription Upgrade Beta

Watch Streak Beta

What are Twitch Channel Points?

Twitch Channel Points are a loyalty system that allows streamers to reward their viewers for watching, following, subscribing, and participating in the stream. Viewers earn points over time and can redeem them for various rewards that you create.

BotOfTheSpecter integrates seamlessly with Twitch's Channel Points system, allowing you to automate responses and create custom experiences when viewers redeem rewards.

Setting Up & Syncing Rewards

Customizing Reward Responses

Once your rewards are synced, you can customize the bot's response for each redemption. This allows you to create personalized experiences for your viewers.

How to Customize

1. Find the reward in the Channel Rewards table.
2. Click the Edit button next to the reward.
3. Enter your custom message in the text area (up to 255 characters).
4. Click Save to apply the changes.

Message Variables

You can use the following variables in your custom reward messages. For the full shared-variable list, see the Variables guide.

Best Practices

Troubleshooting

API Overview & Authentication

The BotOfTheSpecter API enables programmatic access to various bot features, allowing developers to build custom integrations, extensions, and applications that interact with the bot's functionality.

All authenticated API requests require your unique API key. This key is essential for BotOfTheSpecter integrations, including API access, WebSocket server connections, and third-party platform integrations.

Obtaining Your API Key

1. Log in to the BotOfTheSpecter Dashboard.
2. Navigate to Dashboard → Profile.
3. Locate your API key in the API Access section of the Profile page.

API Key Regeneration

If you believe your API key has been compromised:

1. Go to Dashboard → Profile.
2. Click the regenerate button in the API Key section.
3. Important: Regenerating your key requires a full restart of all BotOfTheSpecter components (Twitch Chat Bot & Overlays). Restart them via the dashboard after regenerating.

Endpoint Quick Reference

BotOfTheSpecter's API provides several endpoint groups. Some are public; others require a user API key or admin key. For /v2/ endpoints, prefer the X-API-KEY header.

Endpoint Reference: Public & Commands

Public (no authentication required)

• GET /freestuff/games — Get recent free games
• GET /freestuff/latest — Get the most recent free game
• GET /versions — Get the current bot versions
• GET /commands/info — Get builtin commands information
• GET /heartbeat/websocket — Get the heartbeat status of the websocket server
• GET /heartbeat/api — Get the heartbeat status of the API server
• GET /heartbeat/database — Get the heartbeat status of the database server
• GET /system/uptime — Get API process uptime
• GET /chat-instructions — Get AI chat instructions
• GET /api/song — Get the remaining song requests
• GET /api/exchangerate — Get the remaining exchangerate requests
• GET /api/weather — Get the remaining weather API requests
• GET /api/steamapplist — Get Steam app list mapping

Webhooks (require API key)

• POST /fourthwall — Receive and process FOURTHWALL Webhook Requests
• POST /kofi — Receive and process KOFI Webhook Requests
• POST /patreon — Receive and process Patreon Webhook Requests

Commands (requires user API key)

Admins can query any user's data with the channel parameter.

• GET /v2/quotes — Get a random quote
• GET /v2/fortune — Get a random fortune
• GET /v2/kill — Retrieve the Kill Command Responses
• GET /v2/joke — Get a random joke
• GET /v2/sound-alerts — Get list of sound alerts for user
• GET /v2/custom-commands — Get list of custom commands for your account
• GET /v2/user-commands/get — Get list of user managed commands
• POST /v2/user-commands/add — Add a user managed command
• POST /v2/user-commands/remove — Remove a user managed command
• GET /v2/weather — Get weather data and trigger WebSocket weather event
• GET /v2/user-points — Get user points
• POST /v2/user-points/credit — Credit points to a user
• POST /v2/user-points/debit — Debit points from a user

User Account (requires user API key)

Admins can query any user's data with the channel parameter.

• GET /v2/account — Get account information
• GET /v2/checkkey — Check if the API key is valid
• GET /v2/streamonline — Check if the stream is online
• POST /v2/discord/twitch-link/confirm — Confirm Discord to Twitch link using one-time token
• GET /v2/bot/status — Get chat bot status

WebSocket Triggers (requires user API key)

Endpoints that trigger real-time events via WebSocket to the bot and overlays.

• GET /v2/websocket/tts — Trigger TTS via API
• GET /v2/websocket/walkon — Trigger Walkon via API
• GET /v2/websocket/deaths — Trigger Deaths via API
• GET /v2/websocket/sound_alert — Trigger Sound Alert via API
• GET /v2/websocket/custom_command — Trigger Custom Command via API
• GET /v2/websocket/stream_online — Trigger Stream Online via API
• GET /v2/websocket/raffle_winner — Trigger Raffle Winner via API
• GET /v2/websocket/stream_offline — Trigger Stream Offline via API
• POST /v2/SEND_OBS_EVENT — Pass OBS events to the websocket server

Admin Only (requires admin API key)

Administrative endpoints that require admin API key. Service-specific admin keys are restricted to their designated service.

• POST /freestuff — Receive and process FreeStuff Webhook Requests
• POST /github — Receive and process GitHub Webhook Requests
• GET /v2/authorizedusers — Get a list of authorized users for full beta access to the entire Specter Ecosystem
• GET /v2/discord/linked — Check if Discord user is linked
• GET /v2/discord/twitch-link — Get Discord to Twitch link
• POST /v2/discord/twitch-link/request — Create one-time Twitch link token for a Discord user
• POST /v2/discord/twitch-link/unlink — Unlink Discord user from Twitch account

Using the API

For /v2/ endpoints, send your API key in the X-API-KEY header. Legacy endpoints can still use a URL query parameter where supported.

Do not expose the key in public client-side code — treat it like a secret and rotate it if you suspect compromise.

curl -H "X-API-KEY: YOUR_API_KEY" "https://api.botofthespecter.com/v2/account"

fetch('https://api.botofthespecter.com/v2/account', {
  headers: {
    'X-API-KEY': 'YOUR_API_KEY'
  }
})
.then(r => r.json())
.then(console.log);

import requests

resp = requests.get(
    'https://api.botofthespecter.com/v2/account',
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
print(resp.json())

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.botofthespecter.com/v2/account');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-KEY: YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

// Java 11+ HttpClient
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.botofthespecter.com/v2/account"))
    .header("X-API-KEY", "YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

What is Self-Hosting?

Server Architecture

The minimum setup required to run SpecterSystems consists of 4 servers running on a headless Linux architecture. A 5-server setup is recommended for production deployments.

Common Software Requirements (All Servers)

• OS: Linux (Ubuntu 24.04 LTS or newer)
• Python: 3.8+ (Bot, API, and WebSocket servers)
• PHP: 8.0+ (Web/Dashboard server)
• Caddy (Web/Dashboard server)
• MySQL (Database server)
• Git: For version control

Network & Services

• Twitch API credentials (OAuth tokens)
• Discord bot token (optional)
• Spotify API credentials (optional)
• OpenWeatherMap API key (optional)
• SSL/TLS certificates for secure communication
• Firewall configured for internal communication

Recommended Hosting: Linode

Get $100 in free credit: Use our referral link to receive $100 of Linode credit to use within 60 days once you've entered a valid payment method to your Linode account.

Get $100 Linode Credit

Prerequisites (All Servers)

Before deploying to individual servers, ensure each Linux server has the following installed:

# Update system packages (All Servers)
sudo apt update && sudo apt upgrade -y

# Install common dependencies (All Servers)
sudo apt install -y curl wget git build-essential openssl ssl-cert

# Create botofthespecter user (All Servers)
sudo useradd -m -s /bin/bash botofthespecter
sudo usermod -aG sudo botofthespecter

# For Servers 1, 2, 3, 5 - Install Python and pip
sudo apt install -y python3 python3-pip python3-venv

# For Server 1 Only - Install PHP and Caddy
sudo apt install -y php php-cli php-fpm php-curl php-json php-mysql php-ssh2 caddy

# For Server 4 Only - Install MySQL
sudo apt install -y mysql-server

Step 1: Clone the Repository (Servers 1, 2, 3, 5)

Clone the BotOfTheSpecter repository to a temporary directory on each server (except Server 4 — Database):

cd /tmp
git clone https://github.com/YourStreamingTools/BotOfTheSpecter.git botofthespecter-temp
cd botofthespecter-temp

Then move the appropriate files to their destinations based on your server type:

For Server 1 (Web/Dashboard):

sudo rm -rf /var/www/html
sudo cp -r /tmp/botofthespecter-temp/dashboard /var/www/
sudo cp -r /tmp/botofthespecter-temp/home /var/www/
sudo cp -r /tmp/botofthespecter-temp/html /var/www/
sudo cp -r /tmp/botofthespecter-temp/overlay /var/www/
sudo cp -r /tmp/botofthespecter-temp/roadmap /var/www/
sudo cp -r /tmp/botofthespecter-temp/tts /var/www/
sudo cp -r /tmp/botofthespecter-temp/walkons /var/www/
sudo cp -r /tmp/botofthespecter-temp/videoalerts /var/www/
sudo cp -r /tmp/botofthespecter-temp/soundalerts /var/www/
sudo cp -r /tmp/botofthespecter-temp/config /var/www/
sudo cp -r /tmp/botofthespecter-temp/cdn /var/www/
sudo chown -R www-data:www-data /var/www

For Server 2 (API):

sudo cp -r /tmp/botofthespecter-temp/api /home/botofthespecter/
sudo chown -R botofthespecter:botofthespecter /home/botofthespecter

For Server 3 (WebSocket):

sudo cp -r /tmp/botofthespecter-temp/websocket /home/botofthespecter/
sudo chown -R botofthespecter:botofthespecter /home/botofthespecter

For Server 5 (Bot):

sudo cp -r /tmp/botofthespecter-temp/bot /home/botofthespecter/
sudo chown -R botofthespecter:botofthespecter /home/botofthespecter

Clean up temporary directory (All Servers):

rm -rf /tmp/botofthespecter-temp

Step 2: Configure Database Server (Server 4 Only)

Server 4 does not require application files from the repository — it only needs MySQL installed and configured. Specter uses two database scopes:

1. Central / system databases — you create these once by hand (website, spam_pattern, optional roadmap / specterdiscordbot).
2. Per-user databases — one MySQL database per Twitch username (DB name = username). These are never created by hand; the dashboard creates them on first login.

Central databases (create manually)

• spam_pattern — global spam phrases for auto-ban (table: spam_patterns)
• website — accounts, OAuth tokens, API keys, admin keys, system tables
• specterdiscordbot — Discord bot state (optional)
• roadmap — roadmap site (optional)

Minimal bootstrap SQL for the core DBs (expand as needed; full website tables also grow via migrations/website/):

sudo mysql -u root -p

-- spam_pattern (DB name) + spam_patterns (table)
CREATE DATABASE IF NOT EXISTS spam_pattern;
USE spam_pattern;
CREATE TABLE IF NOT EXISTS spam_patterns (
    id INT NOT NULL AUTO_INCREMENT,
    spam_pattern TEXT NOT NULL,
    PRIMARY KEY (id)
);

-- roadmap (optional)
CREATE DATABASE IF NOT EXISTS roadmap;
USE roadmap;
CREATE TABLE IF NOT EXISTS roadmap_items (
    id INT NOT NULL AUTO_INCREMENT,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    category ENUM('REQUESTS','IN PROGRESS','BETA TESTING','COMPLETED','REJECTED') NOT NULL DEFAULT 'REQUESTS',
    subcategory ENUM('TWITCH BOT','DISCORD BOT','WEBSOCKET SERVER','API SERVER','WEBSITE','OTHER') NOT NULL,
    priority ENUM('LOW','MEDIUM','HIGH','CRITICAL') NOT NULL DEFAULT 'MEDIUM',
    website_type ENUM('DASHBOARD','OVERLAYS') DEFAULT NULL,
    completed_date DATE DEFAULT NULL,
    created_by VARCHAR(255) DEFAULT NULL,
    created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id)
);
CREATE TABLE IF NOT EXISTS roadmap_comments (
    id INT NOT NULL AUTO_INCREMENT,
    item_id INT NOT NULL,
    username VARCHAR(255) NOT NULL,
    comment TEXT NOT NULL,
    created_at TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    CONSTRAINT roadmap_comments_ibfk_1 FOREIGN KEY (item_id) REFERENCES roadmap_items (id) ON DELETE CASCADE
);

-- specterdiscordbot (optional — full schema in repo)
CREATE DATABASE IF NOT EXISTS specterdiscordbot;

-- website (accounts + system tables; users row is the minimum for login)
CREATE DATABASE IF NOT EXISTS website;
USE website;
CREATE TABLE IF NOT EXISTS users (
    id INT NOT NULL AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL,
    twitch_display_name VARCHAR(50) DEFAULT NULL,
    twitch_user_id VARCHAR(255) NOT NULL,
    access_token VARCHAR(255) DEFAULT NULL,
    refresh_token VARCHAR(255) DEFAULT NULL,
    api_key VARCHAR(32) NOT NULL,
    is_admin TINYINT(1) NOT NULL DEFAULT 0,
    beta_access TINYINT(1) NOT NULL DEFAULT 0,
    is_technical TINYINT(1) NOT NULL DEFAULT 0,
    signup_date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    last_login TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    profile_image VARCHAR(255) NOT NULL DEFAULT 'https://cdn.botofthespecter.com/noimage.png',
    email VARCHAR(255) DEFAULT NULL,
    app_password VARCHAR(50) DEFAULT NULL,
    language VARCHAR(5) NOT NULL DEFAULT 'EN',
    PRIMARY KEY (id),
    UNIQUE KEY username (username),
    UNIQUE KEY api_key (api_key),
    KEY idx_twitch_user_id (twitch_user_id)
);

Then create your MySQL application user (must be able to create databases — per-user DBs need CREATE):

CREATE USER 'your_username'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON *.* TO 'your_username'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Per-user databases (auto-created)

Source of truth: dashboard/includes/usr_database.php.

• Database name = Twitch login / session username (letters, numbers, underscore only; max 64 chars).
• When — first successful dashboard session for that user (and again on later loads to create any missing tables / columns).
• What runs — CREATE DATABASE if the schema does not exist, then CREATE TABLE IF NOT EXISTS for every table below, then column checks, then default seed rows.

Tables created in each user database

Grouped for readability (names match the code):

Default seed data (first creation)

usr_database.php also inserts defaults when tables are empty, including:

• groups — Moderators, VIPs, Subscribers, Bots
• categories — Default
• bot_settings — point name Points, chat/follow/sub/cheer/raid amounts, 2× sub multiplier, excluded users include botofthespecter and the channel username
• point_store_settings, subathon_settings, protection, joke_settings, watch_time_excluded_users, stream_status
• ad_notice_settings — default ad start/end/upcoming messages with variables like (duration) / (minutes)
• streamer_preferences — welcome message defaults, music source
• twitch_chat_alerts — gift/prime upgrade, pay-it-forward, watch streak templates
• task_settings, credits_overlay_settings, closed_captions_settings, avatar_settings, working_study_overlay_settings, automated_shoutout_settings, tanggle_puzzle_stats, showobs

Finally, configure MySQL to accept connections from other servers by editing /etc/mysql/mysql.conf.d/mysqld.cnf:

bind-address = 0.0.0.0

Step 3: Set Up Python Environment (Servers 2, 3 & 5)

All application servers share the same repository path: /home/botofthespecter. Create the virtual environment in that directory and use the venv's pip/python directly so commands are deterministic and work the same on every server.

Recommended venv location: /home/botofthespecter/botofthespecter

# create the venv (run as the botofthespecter user)
python3 -m venv botofthespecter
# install all required packages
/home/botofthespecter/botofthespecter/bin/pip install -r /home/botofthespecter/requirements.txt

Step 4: Configure Environment Variables (All Servers)

Create a .env file in /home/botofthespecter with your configuration. Replace the placeholders with your actual values:

# SQL Data
SQL_HOST=
SQL_USER=
SQL_PASSWORD=
SQL_PORT=
# API STUFF
SHAZAM_API=
WEATHER_API=
STEAM_API=
OPENAI_KEY=
OPENAI_VECTOR_ID=
STREAMELEMENTS_CLIENT_ID=
STREAMELEMENTS_SECRET_KEY=
HYPERATE_API_KEY=
# Twitch Bot
OAUTH_TOKEN=oauth:
TWITCH_OAUTH_API_TOKEN=
TWITCH_OAUTH_API_CLIENT_ID=
CLIENT_ID=
CLIENT_SECRET=
TWITCH_GQL=
TIMEZONE_API=
EXCHANGE_RATE_API=
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=
BOT_ID=
# Discord Bot
DISCORD_TOKEN=
DISCORD_PUBLIC_KEY=
API_KEY=
DISCORD_CLIENT_ID=
DISCORD_CLIENT_SECRET=
# Guided Bot
GUIDED_BOT_USER_ID=
GUIDED_BOT_TOKEN=
# ADMINS
ADMIN_KEY=
# BACKUP SYSTEM
USE_BACKUP_SYSTEM=False
BACKUP_CLIENT_ID=
BACKUP_SECRET_KEY=
# SSH Settings
SSH_USERNAME=
SSH_PASSWORD=
API-HOST=
WEBSOCKET-HOST=
BOT-SRV-HOST=
SQL-HOST=
WEB-HOST=
BILLING-HOST=
STREAM-AU-EAST-1-HOST=
STREAM-US-EAST-1-HOST=
STREAM-US-WEST-1-HOST=
# SMTP Email Settings
SMTP_HOST=
SMTP_PORT=465
SMTP_FROM_NAME=
SMTP_USERNAME=
SMTP_PASSWORD=
# S3 Bucket Settings for Exports Only
S3_ENDPOINT_HOSTNAME=
S3_CUSTOM_DOMAIN=
S3_BUCKET_NAME=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_ALWAYS_UPLOAD=True

Required Variables

• SQL_* — Database connection details (must match Server 4 config)
• CLIENT_ID & CLIENT_SECRET — Your Twitch application credentials
• OAUTH_TOKEN — Bot account OAuth token
• API_KEY — Generate a secure random key for internal service authentication

Optional Variables

• WEATHER_API — For weather commands (OpenWeatherMap)
• SPOTIFY_* — For Spotify integration
• DISCORD_* — For Discord bot functionality
• OPENAI_KEY — For AI features
• S3_* — For user data exports to object storage
• SMTP_* — For email notifications

Server Host Variables

• API-HOST, WEBSOCKET-HOST, etc. — Set these to the IP addresses or hostnames of your respective servers for inter-server communication

Step 5: Verify WebSocket Dependencies (Server 3)

Install Python dependencies for the WebSocket server:

cd /home/botofthespecter
source /home/botofthespecter/botofthespecter/bin/activate
/home/botofthespecter/botofthespecter/bin/pip install -r /home/botofthespecter/requirements.txt

Step 6: Set Up Web Server (Server 1)

Configure Caddy to serve the PHP dashboard and static assets. Caddy auto-issues and auto-renews Let's Encrypt certificates, so you do not need a separate ACME client:

sudo apt install -y caddy
# Install the Caddyfile from the repo (the repo ships a ready-made one under web/Caddyfile)
sudo cp /home/botofthespecter/web/Caddyfile /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile

The shipped web/Caddyfile expects each surface on its own docroot under /var/www/ and talks to PHP over the FPM socket. Update the hostnames in /etc/caddy/Caddyfile to your own domain, then add a Cloudflare DNS API token to /etc/caddy/caddy.env if you need wildcard certificates:

# /etc/caddy/caddy.env  (systemd drop-in; Caddy reads it via {env.X})
CF_API_TOKEN=your_cloudflare_dns_api_token
STORAGE_HOST=your-object-storage-host
STORAGE_PREFIX=your-bucket-prefix

You must serve the dashboard and related assets under your domain. Recommended subdomains to configure:

example.com
dashboard.example.com
overlay.example.com
videoalert.example.com
soundalert.example.com
tts.example.com

Running the Services

Server 1: Start the Web/Dashboard Server

sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy
# After editing /etc/caddy/caddy.env you must restart (env is read once at process start);
# a plain reload will not pick up the new CF_API_TOKEN.
sudo systemctl restart caddy

Server 2: Start the API Server

cd /home/botofthespecter
source /home/botofthespecter/botofthespecter/bin/activate
# Run with TLS (replace cert paths with your domain)
python -m uvicorn api.api:app --host 0.0.0.0 --port 443 \
  --ssl-keyfile=/etc/letsencrypt/live/api.example.com/privkey.pem \
  --ssl-certfile=/etc/letsencrypt/live/api.example.com/fullchain.pem

Server 3: Start the WebSocket Server

cd /home/botofthespecter
source /home/botofthespecter/botofthespecter/bin/activate
python /home/botofthespecter/server.py

Server 4: Start the Database

sudo systemctl enable mysql
sudo systemctl start mysql
sudo systemctl status mysql

Server 5: Bot Service

The bot is controlled and started from the dashboard (Server 1). No manual startup is required on Server 5 — it is ready once the Python environment and .env configuration are complete.

Inter-Server Networking

• Internal Network: Use private IP addresses for inter-server communication
• DNS/Hostnames: Set up DNS or /etc/hosts entries for server-to-server connections
• Firewall Rules: Only allow necessary ports between servers
• SSL/TLS: Encrypt communication between services

Firewall Configuration Example

# Server 1 (Web) - Allow HTTP/HTTPS and communication with other services
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow from 10.10.10.2:443   # API Server
sudo ufw allow from 10.10.10.3:443   # WebSocket Server
sudo ufw allow from 10.10.10.4:3306  # Database Server

# Server 2 (API) - Allow inbound from Web and Bot servers
sudo ufw allow from 10.10.10.1:any   # Web Server
sudo ufw allow from 10.10.10.5:any   # Bot Server

# Server 3 (WebSocket) - Allow inbound from Web and Bot servers
sudo ufw allow from 10.10.10.1:any   # Web Server
sudo ufw allow from 10.10.10.5:any   # Bot Server

# Server 4 (Database) - Allow inbound from all services
sudo ufw allow from 10.10.10.1:any   # Web Server
sudo ufw allow from 10.10.10.2:any   # API Server
sudo ufw allow from 10.10.10.5:any   # Bot Server

# Server 5 (Bot) - Allow outbound to API, WebSocket, and Database
sudo ufw allow to 10.10.10.2:443     # API Server
sudo ufw allow to 10.10.10.3:443     # WebSocket Server
sudo ufw allow to 10.10.10.4:3306    # Database Server

Security Considerations

• HTTPS/SSL: Always use SSL certificates for all services — Let's Encrypt is free
• Firewall: Restrict database access to only the servers that need it
• Environment Variables: Never commit .env files to version control
• Database Backups: Set up automated daily backups
• Updates: Keep dependencies updated to patch security vulnerabilities
• Monitoring: Monitor system resources and bot logs for issues

Troubleshooting

Maintenance

Regular Tasks

• Daily: Check logs for errors and unusual activity
• Weekly: Verify all services are running and responsive
• Monthly: Update dependencies and apply security patches
• Quarterly: Review and optimize database performance

Updating BotOfTheSpecter

git pull origin main
pip install -r bot/requirements.txt --upgrade
pip install -r api/requirements.txt --upgrade

Need Help?

If you encounter issues while self-hosting BotOfTheSpecter:

Bot Not Connecting

If your bot isn't connecting to Twitch:

• Try stopping and starting the bot from the dashboard under Bot Control.

Commands Not Working

If commands aren't responding:

• Check that the command is enabled in the dashboard, or use !enablecommand commandname in chat.
• Commands always use the ! prefix — verify the bot has Moderator permissions in your channel.
• Double-check the spelling of the command name both in chat and in the dashboard.

Sound Alerts / TTS / Walk-ons — Audio Issues

All Specter audio goes through the audio overlays. Make sure you're running the correct overlay, or use the All Audio overlay:

https://overlay.botofthespecter.com/alert.php?code=YOUR_API_KEY

• Check audio device settings in OBS.
• Ensure the OBS Browser Source volume is audible and audio monitoring is configured correctly.
• If you hear an echo, set Audio Monitoring to Monitor Only (mute output) and test again — everyone's audio setup differs.
• Confirm you've entered the correct API key, found on your Specter Profile page in the dashboard.

Still Stuck?

If none of the above resolves your issue, submit a support ticket and include:

• A description of what you expected to happen vs. what actually happened.
• Any error messages you see (screenshots are helpful).
• Your Twitch username and approximate time the issue occurred.