Changelog - Version 5.8 (2026-10-13)

Version Information

• Updated version from 5.7.29 to 5.8
• Major architecture improvements and custom bot support

Improvements

• !permitsong
  • Mods and the broadcaster can run !permitsong @username to give that viewer one request past the same-song gap.
  • The permit is kept until their next request that would have been refused as played too soon. A normal request does not use it up. A bot restart clears unused permits.
• Same song request gap
  • The same song cannot be requested again until 720 minutes have passed. The requester is told “This song has been played too soon.”
  • 0 turns the check off. A shorter gap tells the requester the song was requested less than that many minutes ago.
• Bot creator welcome
  • The first time the bot creator chats in a channel while the stream is online, and they are not already in that channel’s seen_users table, the bot posts a one-time hello that names them as its creator.
  • That hello still goes out when the channel has welcome messages turned off. Later visits use the channel’s normal welcome. Chatting while the stream is offline does not use up the hello.
• Rerun notice in chat
  • While a scheduled VOD rerun is playing on the channel, the bot @ mentions each chatter once to let them know it is a rerun of a past stream and the streamer may be away from keyboard.
  • Each viewer is told only once per rerun; the streamer’s own messages never trigger it, and nothing is sent outside a rerun.
  • Who has been told is saved in the new per-user rerun_notices table, so a bot restart mid-rerun does not repeat the notice.
• Viewer birthdays
  • Mods and the broadcaster save a viewer’s birthday with !addbirthday @user DD/MM. Viewers use !mybirthday (shows their saved date, or saves one if none is set) and !updatebirthday DD/MM.
  • On a viewer’s birthday (checked in the channel’s timezone), their first chat of the stream gets a Happy Birthday, @user! 🎂 message from the bot. 29 February birthdays are celebrated on 28 February in non-leap years.
  • The wish is its own chat message, sent after the welcome message. A long welcome can never push it past the 500-character limit, and it is still sent when welcome messages are turned off.
  • !addbirthday uses a per-user cooldown so one mod adding birthdays does not lock the other mods out.
  • Birthdays are stored in the per-user birthdays table (keyed by Twitch user ID) and listed on the new Birthdays dashboard page (Community menu).
• Per-artist song request cap
  • The media player global artist limit still applies to everyone (or to the include/exclude list).
  • Each artist on the list can now store their own number. Blank keeps the global cap. A number replaces it for that artist, including 0 for no cap on them.
  • Spotify and YouTube still share one counter. Chat enforcement starts after the bot is restarted.
• Ad-end chat notice survives a bot reboot
  • When a mid-roll starts, the bot now writes started_at, duration_seconds, and eta_end to the per-user ad_break_state table.
  • After a restart while live, it reads that row: if eta_end is still ahead, the welcome-back line is scheduled for that time; if it already passed, the line is sent immediately. The row is marked end_notice_sent so a second restart cannot double-post.
  • Stream-offline and leftover rows from a previous stream are marked sent without chatting.
• Editable success chat for flavour builtins
  • Builtin Commands edit modal now shows chat templates for success lines that are the streamer’s voice: deaths, lurk/unlurk/lurking, hug/kiss/highfive, game, uptime, followage, watchtime, points, mybits, subscription, ping, bot, roadmap, cheerleader, and pet feed/play/sad/sleep.
  • Seeded with the current default using (var) tokens. Lists, error trees, and system/ops commands stay hardcoded.
  • Per-user command_options rows are seeded from dashboard/includes/usr_database.php (same pattern as twitch_chat_alerts). Dashboard field labels/vars come from api/builtin_commands.json. The bot fills (var) tokens from those rows.
• Custom !deathadd / !deathremove chat messages
  • Builtin Commands edit modal can now change the chat line those commands send.
  • The field is seeded with the current default text using custom-command variables: (game), (deaths), (deaths.total), (deaths.stream), (arg), (user).
  • Stored in per-user command_options JSON (message). Empty or missing falls back to the built-in default.
• Express TTS
  • TTS Settings now has a Normal / Expressive style. Normal keeps the existing voice and language. Expressive shows a separate voice list and follows the viewer’s language automatically.
  • Expressive reads ALL CAPS as shouting and lol / haha as laughter. If expressive generation fails, that line falls back to the saved Normal voice.
  • Per-user tts_settings gains style and expressive_voice via usr_database.php.
• !lurking not-lurking message
  • When a viewer checks !lurking but is not in lurk mode, the reply now tells them how to start: you’re not currently lurking. To lurk, use the !lurk command.

Bug Fixes

• API key kept out of overlay notice web addresses
  • The bot sends the channel’s API key to the websocket server in the X-API-KEY header instead of the /notify web address, so it no longer lands in server access logs.
• Song requester survives a bot restart
  • The Spotify track ID and an in-queue flag are now stored on song_request_analytics, so !skip still knows who requested the current song after the bot restarts.
• !schedule no longer treats a same-day replacement as a cancellation
  • Cancelling one occurrence of a recurring Twitch schedule slot and adding a one-off later the same day produced two chat lines: the cancelled occurrence, then the real next stream.
  • The command now skips cancelled segments when picking the next stream, and only announces a cancellation when that occurrence is not replaced by another stream on the same local calendar day.
  • Chat spelling is cancelled. Helix fetch raised from 3 to 25 segments so cancelled slots cannot hide the real next stream.
• !so no longer double-queues a user who is already waiting
  • The shoutout queue did not track who was already waiting, so !so on a user already queued (for example after a welcome (shoutout)) added a second entry. When that user reached the front, chat posted the same shoutout twice.
  • Outgoing shoutouts now record the target user ID while they are queued or in-flight. A second !so is rejected and the mod is told @mod, @user is already in the shoutout queue. Auto sources (raid, welcome, variables) also skip instead of stacking.
  • Incoming “they shouted us out” notices are not treated as the same queue slot, so they still post.
• Stream Bounty bits now fan out as TWITCH_CHEER
  • Extra cards and extra votes paid with bits already posted chat and wrote stream_credits / bits_data, but they never emitted the bits websocket event.
  • Twitch channel.bits.use does not include extension transactions, so Discord logs, Specter Alerts, and the dashboard ticker never saw those spends.
  • Both EXTRA_CARD_WITH_BITS and EXTRA_VOTE_WITH_BITS now also send TWITCH_CHEER with the same payload as a normal cheer. Credits and chat are unchanged (not re-run through process_cheer_event).
• Custom command cooldown bucket
  • Custom Commands page only exposed cooldown seconds; streamers could not choose global vs per-user vs mod buckets (builtin commands already could).
  • Added cooldown_bucket on custom_commands (auto-migrated via usr_database.php), add/edit UI + table column on dashboard/custom_commands.php, and the bot now honors default / user / mod via resolve_cooldown_bucket_key.

New Features & Major Changes

• Working & Study Task List
  • Viewers manage their own tasks on the Working & Study overlay from chat. !task <title> sets the task you are working on now, and any task you already had moves to the front of your backlog.
  • Backlog commands: !later queues at the end, !soon queues at the front, !now <title|n|skip> switches the active task, !backlog lists the queue, and !mytasks shows the active task plus as many backlog titles as fit in one message. Use ; to add several tasks at once.
  • !done finishes the active task, !done <n> finishes backlog item #n, !done 2; 4; 5 finishes several, and !done next finishes the active task and promotes backlog #1. !rename, !remove, and !taskclear (clears the done list) round out the set. !taskhelp posts a quick guide.
  • Per-viewer projects: !project <name> switches project (created on first use), !project move, !project rename, !project delete, and !project clear. !projects lists projects with their open task counts.
  • Overlay badges use each viewer’s backlog position, not the global task ID. Task commands always have no cooldown.
• Personal Timers
  • !timer <minutes> <title> is a general countdown that pings you in chat. !timer <minutes> "title" focus runs a focus block and adds it to the task list. !timer <work>/<break>/<cycles> [label] runs a multi-cycle focus/break session.
  • !checktimer shows the time left, !timer stop cancels, and !timerhelp explains every mode. Aliases: !personaltimer, !ptimer, !mytimer, !focus.
  • The bot stores each timer’s phase end time in the per-user user_pomos table, so timers resume (and catch up on missed phases) after a bot restart. The websocket server only relays overlay updates.
  • !tasktimer (mods and the broadcaster, aliases !ttimer / !stimer) controls the streamer’s own overlay timer: start, stop, pause, resume, auto-pilot, and focus/break/cycle lengths.
• Point Store
  • Viewers spend bot points (not Twitch channel points) on items the streamer sets up: sound alerts, video alerts, TTS, or chat messages.
  • !store lists items and !store <name|id> buys one. Viewers can also shop at members.botofthespecter.com/{channel}/store. Items and store settings (enabled, paused, live-only, cooldowns) are managed on the new Point Store dashboard page.
  • Points are debited in one atomic update before anything is played, and checkouts are handled one at a time per viewer so two quick purchases cannot both slip past a limit.
  • Purchases emit a new STORE websocket event alongside the matching sound, video, or TTS event, so existing overlays play the item straight away.
• Interactive Channel Pet
  • A corner companion overlay with happiness, hunger, energy, levels, and XP. Streamers upload sprite sheets or GIFs, or pick one of the free starter packs (Specter, Specter Bot, cat, dog, and more).
  • Chat keywords, commands, Twitch events, gift subs, and channel-point rewards can trigger reactions. Viewers use !pet (status), !feed, !play, !sad, and !sleep (restores energy).
  • The bot announces XP gains, can post scheduled pet sayings, and sends low-stat chat alerts when energy, hunger, or happiness drops to a set threshold.
  • The pet logic lives in a shared bot/modules/pet.py. Configured from the new Pet dashboard page.
• Game Tracker
  • On the new Tracked Games dashboard page, streamers keep a per-channel list of games marked playing, on hold, finished, dropped, or 100%. The bot auto-adds the live Twitch category (minus an editable denylist) and counts session time.
  • !game now shows play time and status for tracked games. Mods can use !game done, !game hold, !game drop, !game 100, and !game time 12h30m, and !game list lists the tracked games.
• Channel Warnings
  • Mods and the broadcaster can issue !warn @user <reason> (alias !warning). Warnings are stored in the per-user warnings table and reviewed or cleared on the new Channel Moderation dashboard page (Analytics).
• Makers & Crafting
  • New Makers & Crafting overlay and dashboard page. !craft manages it from chat: set the current project, add notes, links and images, mark projects finished, queue upcoming ideas, and switch the display mode. The overlay updates live.
• Custom Command Aliases
  • Custom commands can have comma-separated aliases, set on the Custom Commands add/edit form. An alias runs the main command and shares its cooldown.
• Builtin Command Cooldowns
  • Every builtin command reads its rate, time, and bucket from builtin_commands, so the dashboard settings always apply. Remaining wait time is always shown as at least 1 second.
  • Social and self-targeted commands (hug, kiss, highfive, lurk, points, games, raffle entry, pet, birthdays, and similar) use a per-user cooldown so one viewer cannot lock a command for everyone. !clip, !joke, and !ping stay on the shared cooldown. Existing channels are moved over when the bot starts.
• Media Player Song Requests (YouTube fallback)
  • When Spotify is not linked, !songrequest resolves YouTube links or searches and adds them to the dashboard Media Player queue, with the same guardrails as Spotify requests. Mods can remove queued songs with !removesong <position>.
  • Each artist on the artist list can have their own request cap, and streamers choose whether the cap applies to everyone or only to listed artists.
• Known Bots Registry
  • The bot loads an admin-managed list of known bots from website.known_bots (with a built-in fallback list). Known bots are counted but never welcomed or auto-shouted-out.
• Ad Breaks: Raid Auto-Snooze and Specter Alerts Card
  • When a raid arrives, the bot can snooze the next ad automatically (configured in the ad notice settings). The generic “ad snoozed” chat line is skipped for these bot-initiated snoozes.
  • The bot emits TWITCH_AD_BREAK / TWITCH_AD_BREAK_END so Specter Alerts can show an ad-break card with a live countdown. This works whether or not the chat ad notices are turned on.
• Scheduled Timed Messages
  • A new scheduled trigger type posts a timed message at a set time of day in the streamer’s timezone, once per day, only while the stream is live.
• Shoutout History
  • Every shoutout that is sent is recorded in a new shoutout_history table, which the API and dashboard use for shoutout counts.
• Twitch Charity and Gift-Sub Events
  • Charity donations (with correct decimal handling) and gift subs are sent to the websocket as TWITCH_CHARITY and TWITCH_GIFT_SUB, for overlays and Discord.
• More Custom Command Variables
  • (count.<name>) named counters and (clearcount.<name>) to reset one. (count), (count_name), and (usercount) always add exactly 1 per use, so viewers cannot change the increment.
  • (storeredeem) records a channel-point redemption in the new stored_redeems table, readable through GET /channel/twitch/redeems/store.
• !puzzledone
  • Mods can add one to the completed Tanggle puzzle count by hand when the automatic completion notice is missed.
• Custom Bot Mode Support
  • Added support for running the bot with custom bot accounts via database credentials
  • New -botusername command line argument for specifying custom bot username
  • Automatic credential fetching for the custom bot account
  • Comprehensive validation checks before bot initialization
  • Custom bots now show the Chat Bot badge in chat and appear under “Chat Bots” in the viewers list
  • BotOfTheSpecter maintains a separate IRC presence in the channel when running in custom mode, so it always appears in the viewers list alongside the custom bot
  • Chat sending in custom mode uses the shared app access token so the Chat Bot badge stays. The custom bot’s own user token is only used to keep IRC presence (so it appears in the viewers list).
  • Robust IRC presence loop: Rewrote twitch_irc_presence() with proper auth-failure backoff, capability-handshake handling, and notice-id classification - msg_banned / msg_channel_blocked / msg_suspended etc. trigger a 10-minute back-off, account-action notices (msg_requires_verified_phone_number, etc.) fail loudly with a manual-action message, and room-mode notices are silently consumed. Watch-streak IRC NOTICEs are explicitly ignored - the bot uses the channel.chat.notification EventSub event as the source of truth. Self, custom, and default modes each use the matching bot credentials; custom-bot tokens retry on 401. The function now accepts override_nick / override_token so a secondary BotOfTheSpecter presence can run alongside a custom bot from the same loop.
• Per-Viewer Song Request Limits & Pruning
  • Integrated evaluate_guardrails validation from media_helpers.py for Spotify song requests in songrequest_command.
  • Spotify requests now validate against the unified media_request_settings configuration (checking maximum duration, queue length, per-viewer limit, and keyword/track ban lists).
  • Implemented real-time request tracking list pruning in songrequest_command by querying the active Spotify player queue, ensuring that viewer request limits are updated immediately as songs play or get skipped.
  • Fixed a bug where currently playing tracks were prematurely pruned from the song_requests cache (since they exit the future queue array returned by Spotify). Whitelisted the active currently_playing track to ensure that the requester can successfully use the !skip command on their own song.
  • Added case-insensitive username matching (.lower() == .lower()) and safety checks for empty item structures when querying active playback in skipsong_command.
• Per-Channel Module System
  • New custom_channel_modules/ package allows packaging channel-specific behavior (commands, event handlers, websocket interceptors) as Python modules without touching the core bot.
  • On startup, each module’s claims_channel(CHANNEL_NAME) is consulted; modules that claim the active channel are instantiated and have their tables ensured via ensure_tables().
  • Modules expose optional hooks: handle_<event>(...) coroutines (dispatched via dispatch_module_event), is_module_command / handle_module_command, and is_bureau_command / handle_bureau_command (dispatched via dispatch_module_command for every chat line).
  • websocket_notice(..., interceptable=True) lets a module preempt or augment internal websocket emits before they fan out.
  • Currently bundled modules: botofthespecter and gfaundead.
• EventSub WebSocket Robustness Improvements
  • session_reconnect handling: The bot now correctly handles server-initiated reconnects. When Twitch sends a session_reconnect message it includes a new WebSocket URL; the bot connects to that URL immediately (without resubscribing - existing subscriptions transfer automatically) instead of falling back to the hardcoded default URI. A new EventSubReconnect exception propagates the URL from twitch_receive_messages() to twitch_eventsub(), which sets the next connection target and loops without delay.
  • revocation handling: Subscription revocations (e.g. chat_user_banned, user_removed, authorization_revoked) are now detected and logged at ERROR level with the subscription type, status, and ID. When a channel.chat.* subscription is revoked because the bot was banned or removed from chat, an additional error log is emitted so the issue is immediately visible in logs.
  • Session-id persistence: Each new EventSub session id (initial connect or post-reconnect) is upserted into the eventsub_sessions table with session_name = "{SYSTEM} Bot" and last_updated = CURRENT_TIMESTAMP, giving the dashboard a live view of the active EventSub session.
  • Fixed chat EventSub subscriptions failing with HTTP 400: channel.chat.message, channel.chat.notification, and channel.chat.user_message_hold were being subscribed using an App Access Token, which Twitch rejects for WebSocket transport (App tokens are only valid for webhook transport). All EventSub subscriptions now always use the broadcaster’s User Access Token, resolving the “invalid transport and auth combination” error.
• Fixed Duplicate Gift Sub Chat Messages
  • When a streamer gifted multiple subs to the community, the bot was sending one chat message and stream marker per recipient (e.g. 10 gifted subs → 10 identical messages). This was caused by the sub_gift EventSub notification firing once per recipient in addition to the single community_sub_gift event.
  • Individual sub_gift events that belong to a community gift batch (identified by a community_gift_id in the payload) are now silently skipped. The community_sub_gift event continues to handle the single aggregate “X gifted N subs” message and stream marker as before.
  • Individually targeted gift subs (no community_gift_id) are unaffected and still produce their own alert.
  • The recipient-tracking dict (gift_sub_recipients) used to suppress duplicate sub alerts within the 30-second window is now pruned by a cleanup_gift_sub_tracking() background task that runs every 60 seconds, so the dict can’t grow unbounded during a long stream.
• AI-Powered Ad Break Notifications
  • Uses the bot’s OpenAI chat model (OPENAI_MODEL) to generate contextual ad break messages
  • AI analyzes recent chat history to create personalized ad break announcements
  • analyze_chat_vibe() runs a fast keyword scan over recent chat (coding/game/music/hype topics, exclamation/emoji density, caps usage) to produce a tone label (hype / focused / gamey / neutral) that is appended to the AI prompt - so the AI references topics that actually came up rather than inventing unrelated activities.
  • Tracks ad break count per stream session for smarter messaging
  • Premium tier 2+ feature with automatic fallback to standard messages
  • Resets ad-break chat history on stream-session resets and clears it when the first AI ad-break response is produced, preventing stale context from accumulating across streams
  • Filters out timed messages from AI context while preserving command responses
  • Includes stream title and game context for better awareness
  • Restricted ad schedule checking and notifications to be triggered exclusively through the main handle_upcoming_ads looped task, removing the redundant post-ad background polling tasks to prevent duplicate notification triggers.
  • Corrected looped task lifecycle: the handle_upcoming_ads task is now started immediately when the stream goes online and cancelled/ended immediately when the stream goes offline.
  • Increased ad-check responsiveness by reducing the main loop check interval to 10 seconds, improving reliability of upcoming ad notifications and reducing missed or late alerts.
  • Improved error handling and logging for ad polling: non-200 responses and JSON parse failures are logged and retried; duplicate notifications are now deduplicated by the actual next_ad_at value to prevent repeated warnings for the same scheduled ad (including startup/restart edge cases).
  • Fixed delayed ad-break end notice: The end-of-ad countdown timer is now started immediately when the ad-break event is received (before any AI processing begins). Previously the timer only started after the AI start-message had been generated and sent, causing the “ad has ended” notice to fire several seconds late.
• Enhanced Ad Break Configuration
  • Added individual toggle controls for each ad message type (upcoming, start, end, snoozed)
  • New database fields: enable_upcoming_ad_message, enable_start_ad_message, enable_end_ad_message, enable_snoozed_ad_message, enable_ai_ad_breaks
  • Improved ad break messaging logic with granular control
  • Better logging for ad notification debugging
• Unified Points Management System
  • New manage_user_points() function for centralized point operations
  • Supports get, credit, and debit actions with consistent return structure
  • Automatic user creation in bot_points table if not exists
  • Comprehensive error handling with detailed response objects
• Improved Shoutout System
  • New get_shoutout_message() function with game information integration
  • Different behavior for raid vs command-triggered shoutouts
  • Fetches latest stream game automatically for richer shoutout messages
  • Graceful fallback when game information unavailable
  • (shoutout.<login>) placeholder: Custom commands, channel-point rewards, and timed messages can now silently queue a shoutout for a named user via the dynamic-variable engine. The placeholder is stripped from chat output and the standard automated-shoutout cooldown applies.
  • cleanup_expired_shoutouts() background task runs every 5 minutes, deleting both in-memory and automated_shoutout_tracking rows older than the configured cooldown window, so stale per-user shoutout tracking can’t accumulate across streams.
  • Fixed duplicate automated shoutout chat messages during cooldown windows
    • Automated shoutout queue requests now return whether a shoutout was actually queued.
    • Chat shoutout text is only sent when queueing succeeds, preventing duplicate shoutout lines when users are still on the 60-minute automated/Twitch cooldown (for example: raid auto-shoutout followed by a walk-on (shoutout) trigger).
    • Added explicit log entries when a shoutout message is suppressed due to automated cooldown, including source context (welcome_message, raid, cheer, subscription, subscription_message, follow).
  • Fixed shoutout queue blocking bug: Reordered cooldown checks to prevent queue blocking when users are on per-user cooldown
    • Per-user cooldown (60 min) now checked before global cooldown (2 min) wait
    • Users on cooldown are skipped immediately without blocking other users in queue
    • Allows multiple different users to be shouted out every 2 minutes while respecting per-user limits
  • Fixed channel.shoutout.create EventSub notification handling
    • Fixed bug where shoutout_user.lower() was being called on a dictionary
    • Now properly detects command-triggered vs manual/UI-triggered shoutouts
    • Command-triggered shoutouts skip EventSub message to prevent duplicates
    • Manual/UI-triggered shoutouts now properly send chat messages via EventSub
    • Uses get_shoutout_message() function with “eventsub” action for consistent messaging
    • Fixed typo: “inforamtion” → “information” in error message
• Stream Watch Streak Notifications
  • Added handling for Twitch’s watch_streak notice type in the channel.chat.notification EventSub event, matching the existing display in the YourChat system.
  • When a viewer achieves a watch streak milestone (N consecutive streams watched), the bot now announces it in chat.
  • Message is configurable via the twitch_chat_alerts table using alert_type = 'watch_streak'; supported placeholders: (user), (value) (current consecutive count), and (total) (lifetime total streams watched).
  • Default message: Congrats (user) on watching (value) consecutive streams! (uses the longer form including (total) once the user has prior history).
  • Streak losses are detected: when the new streak count is lower than the stored value the bot sends a sympathetic “We’re sorry you lost your N stream streak…” message (using the previous streak length, current count, and new lifetime total).
  • Database: the analytic_stream_watch_streak table is auto-migrated to add highest_streak and total_streams_watched columns on first run.
  • Events are logged to the event log for auditing.
• Pronouns Placeholder Support
  • Added (pronouns), (pronouns.they), and (pronouns.them) placeholders, resolved from the pronouns.alejo.io v1 API.
  • Available in raid alerts, cheer alerts, subscription alerts, gift-sub alerts, and any custom chat alert that runs through the dynamic-variable pipeline.
  • Per-user pronouns are cached for 1 hour (USER_PRONOUNS_CACHE_TTL = 3600); the master pronoun map is cached for 24 hours, keeping API traffic light.
  • Graceful fallback: anonymous gifters and users with no pronouns set resolve to they/them (and split parts to they / them).
• Channel-point VIP grants
  • Added support for channel-point reward placeholders (vip) and (vip.today) in reward custom_message.
    • (vip) - immediately grants the redeemer a Twitch VIP (uses Helix POST /channels/vips).
    • (vip.today) - grants VIP and records the redeemer in a per-user vip_today table; the bot will automatically remove these VIPs when the stream goes offline (Helix DELETE /channels/vips).
  • Note: (vip) and (vip.today) only resolve inside a channel-point reward custom_message (the bot uses the redeemer’s user id from the redemption payload as the VIP target). They are no-ops in other contexts (custom commands, timed messages, alerts).
  • Database: per-channel vip_today table - the bot writes (user_id, username) (the dashboard schema also includes auditing columns like added_at that the bot does not read).
  • Safety: bot logs failures, notifies chat on error, and prunes vip_today after attempting removals to avoid retries.
  • Rate-limits: removals are rate-aware (small delay between deletes) and failures are logged for manual follow-up.
  • Use case: add (vip.today) to a channel-point reward message to grant a time-limited VIP until stream end.
• Channel-point (redeem.*) placeholders
  • New placeholders for channel-point reward custom_message: (redeem.title), (redeem.input), (redeem.cost), (redeem.prompt), (redeem.id), (redeem.status), (redeem.redeemed_at). They expose the full redemption payload (title, the user’s typed input, cost, prompt text, redemption id/status, timestamp) to reward custom messages.
• Raffle System
  • Added a new raffle system enabling streamers to run raffles via both chat and the dashboard.
  • Entry method: free chat command (!joinraffle); raffles may be started with an optional weighted flag so subscribers/VIPs receive improved odds.
  • Commands: !createraffle <name> <prize> <number_of_winners> [weighted] to create a scheduled raffle, !startraffle [raffle_id] to start it, !joinraffle to enter, !leaveraffle to remove your entry, !stopraffle (mod-only) to end a running raffle without drawing, and !drawraffle [raffle_id] for mods to draw winners.
  • Entry-rule schema (stored on the raffle row, configurable via the dashboard):
    • Per-tier weights for weighted raffles - Tier 1 ×2.00, Tier 2 ×3.00, Tier 3 ×4.00, VIP ×1.50 by default (weight_sub_t1 / weight_sub_t2 / weight_sub_t3 / weight_vip).
    • Optional exclude_mods, subscribers_only, followers_only flags enforced at !joinraffle.
    • Optional minimum-follow-duration rule (followers_min_enabled / followers_min_value / followers_min_unit where unit is days / weeks / months / years) - uses the new has_followed_minimum_duration() helper to gate entries.
  • Dashboard: New dashboard/raffles.php page to create, view, and draw raffles from the UI (draw triggers a websocket notify).
  • API/WebSocket: Added /websocket/raffle_winner API endpoint and RAFFLE_WINNER websocket event; drawer updates database, bot announces winner in chat and notifies overlays.
  • Database: Added per-channel tables raffles and raffle_entries to store raffle metadata and entries.
  • Notes/Future: CSV export of entries, scheduled auto-draw and channel-points/bot-points entry costs are planned as optional enhancements.
• Fortune & Lotto Reward Messaging Fixes
  • Fortune reward chat format: Fixed channel-point (fortune) responses so chat output is formatted as username, fortune message, making it clear who the fortune is for.
  • Weighted lotto user tickets: Updated user lotto-number generation to be weighted using the current stream winning numbers from stream_lotto_winning_numbers, guaranteeing at least one points-eligible result per play (minimum Division 6 threshold).
• Raid Analytics & Outgoing Raid Tracking
  • Raid notices used for analytics are sourced from Twitch EventSub channel.raid notifications (both to_broadcaster_user_id for received raids and from_broadcaster_user_id for outgoing raids).
  • Incoming raids are tracked in raid_data and analytic_raids (source: ‘received’): raid counts and viewer totals are aggregated per raider, and stream credits are recorded.
  • Outgoing (sent) raids are detected when the broadcaster initiates a raid; the bot captures the viewer count, holds the raid data until the stream goes offline to ensure accurate viewer persistence, and then inserts a record into analytic_raids with source ‘sent’.
  • Outgoing raids are canceled if an ‘unraid’ is received before persistence; a background task (wait_and_persist_outgoing_raid) waits for stream offline to persist the raid.
  • Points, raid alerts, stream markers, and optional shoutouts continue to be handled for raid events as before.
• Known Users Timestamps
  • Added first_seen and last_seen DATETIME columns to the seen_users table (nullable).
  • Bot behavior: first_seen is set to the current timestamp the first time a user is observed; last_seen is updated on every message.
  • Dashboard: Known Users page now displays First Seen/Last Seen columns and shows “Unknown” when timestamps are missing.
  • Migration: existing last_seen values are used to populate first_seen when appropriate.
• URL Blocking System Overhaul
  • Blacklist Always Active: Blacklisted URLs are now blocked regardless of URL blocking setting
    • Blacklist check happens first before any other URL validation
    • Sends “Code Red” alert to mods when blacklisted URL is detected
    • Ensures harmful/unwanted URLs are always blocked
  • Regex Support for Whitelist: Whitelist now supports full regex pattern matching
    • Allows flexible URL pattern matching (e.g., .*\.example\.com for subdomains)
    • Backwards compatible - can still use simple domain names
    • Invalid regex patterns are logged and skipped gracefully
  • Improved Privilege Handling: Mods and streamers bypass URL blocking when enabled
    • Clearer logging for privileged user URL allowances
    • Permit command functionality preserved
  • Enhanced URL Blocking Logic:
    • Enabled: Removes all links except whitelisted regex patterns and Twitch links
    • Disabled: Allows all URLs except blacklisted ones
    • Twitch.tv and clips.twitch.tv links always allowed when URL blocking enabled
  • Better Logging: More descriptive log messages for URL blocking decisions
    • Logs when blacklisted URLs are detected
    • Logs when URLs are allowed due to whitelist match
    • Logs when URLs are allowed due to mod/streamer privilege
    • Logs when non-whitelisted URLs are blocked
• Text Term Blocking System
  • New Feature: Block specific words from chat
  • Messages containing blocked terms are automatically deleted
  • Case-insensitive matching (e.g., “badword”, “BADWORD”, “BadWord” all match)
  • Independent enable/disable toggle separate from URL blocking
  • Single word per entry validation (no spaces allowed)
  • Database Tables:
    • Added term_blocking column to protection table (VARCHAR(500), default: ‘False’)
    • New blocked_terms table to store blocked terms list
  • Bot Logic:
    • Scans all chat messages for blocked terms when enabled
    • Deletes messages containing blocked terms instantly
    • Sends notification to user explaining removal
    • Independent from URL blocking - can be enabled separately
  • Bug fix: Fixed intermittent “Cursor closed” errors by using a dedicated DB connection+cursor for blocked-terms checks (no longer reuses cursors that may have been released).
• Word Replacer Module
  • New syllable-swap fun module: the bot occasionally re-posts a viewer’s chat line with random syllables swapped for a streamer-chosen word (for example How has your day been? → How has your fun been?). The original message stays in chat; the bot adds a mangled copy underneath. This is an engagement toy, not moderation - it is fully independent from URL/term blocking.
  • Configurable per channel from the dashboard (Modules → Chat Protection → Word Replacer): enable/disable, replacement word (default fun), trigger frequency (1-in-N messages, default 30), per-syllable rate (1-in-N, default 10), and an echo cooldown (default 30 s). Off by default.
  • Default exclusions: the random echo never targets the streamer, the bot’s own messages (timed messages, alerts, command replies), or opted-out viewers.
  • Viewer opt-out: anyone can type !wordreplaceoff to stop their messages being randomly echoed and !wordreplaceon to opt back in. These commands are always available (not gated by the module toggle and not disableable from the Builtin Commands page). Streamers/mods can also manage opted-out users and an ignored-words list from the dashboard.
  • Syllable splitting uses the pyphen hyphenation dictionary with a vowel-cluster fallback for words it doesn’t recognise. ALL-CAPS words echo in ALL-CAPS, mixed-case casing is mirrored, and trailing s/z plurals are preserved.
  • New per-channel tables word_replace_ignored_users and word_replace_ignored_words, plus word_replace_* columns on the protection table (auto-migrated).
• First-Message Command Protection Enhancements
  • Added support for two first-message command blocking modes:
    • All commands: blocks all bot-managed commands until the user has sent a normal chat message.
    • Selected commands only: blocks only commands selected in the dashboard.
  • Selection supports both built-in and custom commands.
  • Unknown/non-bot commands are ignored by this protection and no warning message is sent for them.
  • Database updates in protection table:
    • block_first_message_command_mode
    • block_first_message_selected_commands
• Welcome Message Fix (Custom Mode)
  • Fixed issue where botofthespecter could still receive welcome messages when running with a custom bot account.
  • Welcome flow now ignores both the default bot account and the currently active bot username in custom mode (IGNORED_WELCOME_USERNAMES = {"botofthespecter", BOT_USERNAME.lower()}).
  • Applied to both normal welcome detection and first-command welcome flow.
• Timed Message Trigger Mode Selection
  • Streamers can now choose whether each timed message fires on a fixed timer (every N minutes), after a set number of chat lines, or both simultaneously.

  • A new trigger_type column (timer

    chat_lines

    both) is stored in the timed_messages table; existing rows default to timer via automatic migration. The ENUM is also expanded automatically on existing installs.

  • The bot’s start_timed_message() function activates the interval task and/or the chat-line counter independently based on trigger_type, allowing both to fire in parallel when both is selected.
• Timed Message Variable Expansion & Command Chaining
  • Added support for (command.<name>) inside timed messages and custom commands - inlines another command’s resolved response into the current message.
  • (call.<name>) placeholder (separate from (command.<name>)): defers an actual !command invocation until after the main response is sent. The placeholder is stripped from output and the named built-in/custom command runs as if a moderator had typed it, so it can have its own permission checks and side effects. Optional dot-separated arguments are forwarded to the called command - e.g. (call.todolist.3) runs !todolist 3, and (call.todolist.1,2,3) runs !todolist 1,2,3.
  • Referenced command responses are processed through the same variable engine, so nested placeholders like (game), (count), (random.*), (customapi.*), and (json.*) resolve before sending.
  • Existing timed-message placeholders remain supported, including simple cases like Today we're playing (game).
• (if.<condition>|true_text|false_text) Conditional Placeholder
  • Lets a custom command / timed message branch on resolved values. Supports =, !=, <, >, <=, >=, contains, startswith, endswith (case-insensitive). Example: (if.(json.username) = (user)|You're authorised|You're not authorised).
  • Evaluated last, after all other variables have been substituted, so any other placeholder ((json.*), (user), (count), etc.) can appear inside the condition.
• (todo.add.<category>.[description]) Silent Task Add
  • Custom commands, channel-point reward custom_messages, and timed messages can silently add an item to the to-do list using (todo.add.1.[Buy more snacks]) syntax. Category is parsed as an integer (defaults to id 1), description is the bracketed text. The placeholder is removed from the chat output.

Code Improvements

• IRC and EventSub Chat Deduplication
  • When EventSub and IRC both report the same chat message, the bot now processes it only once. Seen message IDs are tracked for a short time, and EventSub messages are converted into the same message objects as IRC so both go through one handler.
• OpenAI Responses API
  • AI chat replies now use the OpenAI Responses API instead of Chat Completions. Forbidden-phrase rules moved into the AI instructions.
• API V2 Calls
  • Weather, kill, and fortune lookups use the /v2/* API endpoints with the X-API-KEY header instead of ?api_key= query parameters, ready for the V1 API shutdown.
• Opt-in Custom Channel Modules
  • A channel module in custom_channel_modules/ is only loaded when the module file exists, users.use_custom_module is enabled for that user, and the bot is started with -load-custom-module (set through the bots API and dashboard).
• Smaller Fixes
  • First-chat welcome messages still send if the pet trigger fails.
  • Automated chat shoutouts (raid, welcome, and so on) still post when the per-user shoutout cooldown is active. Only the Twitch shoutout API call is skipped.
• Timer Command Refactored to Use TwitchIO Routine
  • !timer no longer holds a database connection open for the entire timer duration via await sleep().
  • The end-of-timer notification is now scheduled using @routines.routine(seconds=..., iterations=1, wait_first=True), the same pattern used for ad-break end notices and poll half-time messages.
  • After inserting the timer record, the DB connection is released immediately; the routine fires after the requested duration, opens a fresh connection, confirms the timer is still active (guards against a concurrent !stoptimer), sends the end message, and cleans up.
  • !stoptimer now cancels the running routine (via active_timer_routines dict) so the end message is never sent after a manual stop.
• Direct Per-Call Database Connections
  • Replaced the previous shared/pooled MySQL handler with DirectConnection: each mysql_connection() call opens a fresh aiomysql connection and closes it on release (via async context manager), eliminating stale-connection issues across long-lived tasks.
  • _MySQLCompat shim preserves the old mysql_handler.get_connection(db_name) interface so module code keeps working unchanged.
  • Added a cleanup_idle_db_pools() background task placeholder that runs on a 30-minute loop (no-op; reserved for future pool reintroduction).
  • Multi-database support retained: callers pass db_name (user DB, website, spam_pattern).
• Chat Message Enhancements
  • Increased maximum message length from 255 to 500 characters
  • Updated send_chat_message() to support three bot modes:
    • Self Mode (-self): Uses broadcaster’s own account as the bot
    • Custom Mode (-custom): Uses custom bot account credentials (with App Access Token for chat sending - see Custom Bot Mode Support)
    • Standard Mode: Uses main “botofthespecter” bot account
  • Dynamic sender_id and access_token selection based on active mode
  • Automatic BOT_USERNAME assignment (channel name for self mode, custom name for custom mode)
  • Improved error logging for failed message delivery
  • Reliability fixes:
    • send_chat_message() now uses a shared aiohttp ClientSession (lazy-created) to reduce transient connection churn and is closed on shutdown
    • Added retries and small backoff for transient network/server errors (502, 503, 504) and for transient aiohttp connection errors
    • Parses response body inside the request context (avoids accessing closed response objects) and uses parsed JSON/text in logs for better diagnostics
  • send_long_chat_message(): New helper splits any response longer than 500 characters into multiple chat sends, breaking on the last whitespace before the limit (or hard-cutting at the limit if no space exists) with a 0.5-second gap between chunks. The dynamic-variable engine uses this for command output, so long commands no longer truncate at 500 characters.
• New Internal WebSocket Event Handlers
  • CUSTOM_COMMAND - accepts {command, response} from the website/API and posts the response to chat, running it through the dynamic-variable engine first so placeholders like (game), (count), (json.*) resolve. Lets the dashboard/API fire any custom command remotely.
  • TASK_REWARD_TRIGGER - when a website “task” reward fires, the bot credits the configured points via manage_user_points, looks up the channel’s point_name, announces the reward in chat, and emits a TASK_REWARD_CONFIRM ack with the new total.
• TwitchIO IRC Auto-Recovery
  • Added an irc_health_check() background task that polls BOTS_TWITCH_BOT.connected_channels every 60 seconds. If the TwitchIO IRC connection has silently dropped (no joined channels), the task logs a warning and calls bot.connect() to re-establish IRC so chat commands continue to work without a manual restart.
• safe_create_task() for Fire-and-Forget Background Work
  • Added a safe_create_task(coro) helper that wraps asyncio.create_task() and stores the resulting task in a module-level _background_tasks set with add_done_callback cleanup. This prevents the asyncio garbage collector from collecting in-flight tasks (which previously surfaced as “Task was destroyed but it is pending!” warnings during shutdown and under load). Most fire-and-forget call sites - websocket notices, alert sends, shoutout removals - now use it instead of bare create_task.
• Event Processing
  • New process_chat_message_event() helper function for consistent event handling
  • Orchestrates message counting and welcome messages; point awarding is deferred to the inner message_counting_and_welcome_messages finally block to avoid double-credit.
  • Simplified event processing from EventSub notifications
  • Provides centralized logging for all chat message events
• Command Management Reliability
  • Fixed !enablecommand and !disablecommand failures caused by an uninitialized cooldown_bucket when command configuration rows were missing.
  • Added safe cooldown defaults and kept DB lookups/updates inside an active cursor scope to prevent runtime command execution errors.
  • Improved target command parsing for these commands by normalizing input (trim, remove leading !, lowercase).
  • Enhanced (customapi.*) variable handling so placeholders inside custom API URLs (for example (user)) are resolved before the API request is made.
  • Improved custom API placeholder parsing to correctly handle nested parentheses in URLs, preventing truncated requests.
  • Added JSON context decoding flow for custom API placeholders:
    • (customapi.json.<url>) now performs a silent fetch only (never posts raw JSON or fetch errors to chat).
    • The fetched JSON is stored in temporary in-message context and the (customapi.json.<url>) placeholder is removed from output.
    • (json.<path>) placeholders resolve values from that stored JSON context, including nested paths (for example (json.last_sign_in.today)).
    • If JSON fetch fails or a path is missing, placeholders resolve to empty output instead of leaking payload/error text to chat.
• Ping Command Internet Test Update
  • Updated !ping to run speedtest --json --secure on the bot server via async subprocess.
  • !ping now reports Speedtest latency (ping) plus transfer totals from bytes_sent and bytes_received.
  • Byte counters are converted to human-readable units before being posted to chat.
  • Added timeout and JSON/error handling for failed or invalid Speedtest responses.
• Dynamic Variable Processor Consolidation
  • Renamed process_custom_command_variables() to process_dynamic_variables() to reflect use beyond chat custom commands.
  • Centralized placeholder switch detection into a shared tuple (DYNAMIC_VARIABLE_SWITCHES) with a has_dynamic_variables() helper, removing duplicate timed-message vs command switch lists.
  • Timed messages and custom-command execution now use the same detection/processing path for consistent behavior across systems.
• Logging Improvements
  • Changed multiple warning level logs to error for better issue visibility
  • Enhanced startup logging with detailed bot configuration information
  • Added comprehensive initialization logs showing channel, username, system, and version
  • Better error context in ad break notification failures
  • New system and integrations log streams: Added two dedicated logger categories — system (startup, shutdown, credential refresh) and integrations (Tanggle, Stream Bingo, StreamElements, StreamLabs, Fourthwall, Ko-fi, Patreon). Keeps bot.log and event_log.log smaller and more focused.
  • Sequential integration startup: connect_to_integrations() now starts Stream Bingo, Tanggle, and tipping services with 2-second gaps between each, so the startup log shows each integration’s “connected” or “no credentials” line in a clean order instead of interleaved.
  • Stream Bingo & Tanggle: deduplicated “no credentials” log spam: When no Stream Bingo API key or Tanggle credentials are configured, the bot previously logged a “skipping connection” message on every 5-minute retry loop. Both integrations now log the missing-credentials message only once per absence. The flag resets as soon as valid credentials are found and a connection is established, so if credentials are later removed the message will appear once again.
• MySQL Query Updates
  • Updated INSERT ... ON DUPLICATE KEY UPDATE syntax to MySQL 8.0+ compatible format for the watch_time query (AS new_watch_time row alias) and the everyone greeting query (AS new row alias).
  • Improved watch_time tracking query for better compatibility.
  • Note: tanggle_puzzle_stats and vip_today ON DUPLICATE KEY UPDATE clauses still use the deprecated VALUES(col) form and remain a follow-up cleanup target for full MySQL 8.0.20+ compatibility.
  • Fixed Data truncated for column 'winner_timer_seconds' warning: winner.get('timer') is now explicitly cast to int before the Tanggle room-completion insert, handling float values returned by the API.
  • Fixed Task was destroyed but it is pending! warnings at shutdown: The finally block in message_counting_and_welcome_messages now catches CancelledError and re-raises it instead of attempting async DB work while the task is being cancelled, preventing dangling pending tasks during bot shutdown.
• Stream Metadata Accuracy Improvements
  • Improved stream-online announcement reliability when category data is temporarily missing from Twitch helix/streams.
  • If stream data confirms the channel is live but game_name is missing/unknown, the bot now performs a fallback metadata lookup to Twitch helix/channels and updates global current_game / stream_title before posting the online message.
  • Fixed fallback metadata lookup not executing: The initial streams call and the fallback channels call are now performed inside a single shared aiohttp session. Previously the session was closed after the first call, causing the fallback request to silently fail and the online message to always read “Streaming Unknown”.
  • If Twitch indicates the stream is offline, the bot intentionally keeps the category as Unknown (no fallback overwrite) to avoid stale game data.
  • Added a live metadata verification loop (periodic_stream_metadata_refresh) that refreshes current_game and stream_title every 60 seconds while stream_online is true.
  • Metadata refresh calls are skipped while offline to reduce unnecessary API traffic and prevent incorrect global updates.
  • stream_session_started_at is now sourced from the real Twitch started_at timestamp returned by helix/streams (fall back to the bot’s local “now” only if the API field is missing). Uptime, duration milestones, and ad-break-chat session windowing all use this anchor.
• SSH Manager Initialization
  • Changed SSH manager logger from bot_logger to system_logger for better categorization
• AI Conversation History
  • Bot replies sent in response to a user !command or @mention are now appended to a short per-viewer AI history (capped at 200 messages). Future AI mentions from the same user can reference prior bot turns for more coherent multi-turn conversations.
• Private Todo Tasks
  • The !todo add action now accepts an optional private keyword - e.g. !todo add "My task" private or !todo add "My task" 2 private. The bot stores the task as private and confirms with a [Private] note in chat.
  • Public/private separation is enforced by !todolist, which only returns tasks where private = 0.
• New !todolist Command
  • Added a new !todolist command that displays the top 5 public (non-private) pending tasks from the to-do list directly in chat. The SQL filters out completed tasks (completed != 'Yes'), so only the pending bullet (○) is shown in practice.
  • Each task shows its completion status marker, ID, and objective.
  • Optional category filtering: !todolist 3 shows only category ID 3, and !todolist 1,2,3 shows tasks from multiple categories. The chat output is prefixed with the matching category name(s), e.g. To-Do List (Work): .... Unknown category IDs return a clear error instead of falling back to all tasks.
  • The same category syntax works via (call.todolist.<id>) / (call.todolist.<id>,<id>) in custom commands, timed messages, and channel-point reward messages.

Thank you for your feedback and support!

As always, your feedback is appreciated. Please report any issues, bugs, or suggestions in the #ticket-info channel on our Discord server. You can also submit feedback and bug reports directly on our website: https://botofthespecter.com/feedback.php