📢 PhantomBot v3.5.0 is now available as a stable build

⚠️ Warning: This version drops support for updating from any PhantomBot version before v3.3.0

If you are running a PhantomBot version lower than v3.3.0, you should first update to v3.3.0 or later and then run the bot once for 5 minutes before installing this update

Alternatively, if data loss isn't an issue, the existing database can be deleted and the update can be started with a brand new database

Database or configuration errors may occur if this step is skipped when coming from an unsupported version

Rollbar Exception Reporting

ℹ️ Notice: As of Phantombot v3.5.0, we now use Rollbar to automatically report exceptions to the dev team.

OAuth tokens, Client IDs, and API Secrets are NOT sent. All information is kept private.

Data is only sent when an exception occurs. Some very common, safe to ignore, exceptions are not sent, such as the ones that occur when shutting down the bot while an active panel connection exists.

Exceptions are sent through a server owned by @gmt2001 for additional filtering before continuing on to Rollbar. No data is saved on this server beyond normal logs used for DDOS mitigation. These logs may include IP addresses and are deleted after 5 weeks. IP addresses are NOT sent on to Rollbar.

The following values are sent from botlogin.txt:

• allownonascii - Indicates if other config values in botlogin.txt are allowed to use non-US-ASCII characters
• baseport - Indicates the port that the built-in webserver listens on
• channel - Indicates the Broadcaster's channel, where the bot interacts with Twitch viewers
• datastore - Indicates which database backend is used
• debugon - Indicates whether debug messages are printed to the console and logged
• debuglog - Overrides the above to only log, but not print to console
• helixdebug - Enables additional debug logging of Twitch Helix API requests and responses (Not including OAuth tokens)
• ircdebug - Enables additional debug logging of incoming messages from Twitch Message Interface (TMI/IRC)
• logtimezone - Indicates the timezone used by the bot
• msglimit30 - Indicates the self-imposed rate-limit on outgoing messages to TMI
• musicenable - Indicates whether the YouTube player has been enabled at the botlogin.txt level
• owner - Indicates the bot owner (used for giving a non-broadcaster bot owner admin privileges)
• proxybypasshttps - Overrides the SSL checks in the bot to pretend SSL is enabled, for use with a reverse proxy
• reactordebug - Enables very verbose debug output to console from the Netty backend (Helix and Discord API)
• reloadscripts - Indicates whether the bot is allowed to reload most JavaScript files when they are changed without a restart
• rhinodebugger - Enables verbose debug output when JavaScript exceptions occur
• rollbarid - A GUIDv4 which uniquely identifies the current PhantomBot installation, used for identifying when multiple exceptions are coming from the same bot
• twitch_tcp_nodelay - The TCP_NODELAY flag for TMI. Makes TMI less bandwidth efficient but possibly a little faster on outbound messages
• usehttps - Indicates whether SSL is enabled on the bots built-in webserver
• user - The bots Twitch username
• useeventsub - Indicates if EventSub is enabled
• userollbar - Indicates if Rollbar exception reporting is enabled
• webenable - Indicates if the bots built-in webserver is enabled
• whisperlimit60 - Indicates the self-imposed rate-limit on outgoing whispers to TMI
• wsdebug - Enables debug output of WebSocket messages from the panel

For all other values in botlogin.txt, only an indicator of whether the value exists will be sent, but not the actual value itself.

The other data sent includes:

• java.home - Indicates where Java is installed
• java.specification.name - Indicates the specification of the Java Runtime Environment the Java installation adheres to
• java.specification.vendor - Indicates the vendor of the above specification
• java.specification.version - Indicates the version of the above specification
• java.vendor - Indicates the vendor of the actual Java installation
• java.version - Indicates the actual version of the Java installation
• os.arch - Indicates 32-bit or 64-bit operating system
• os.name - Indicates the name of the operating system
• os.version - Indicates the version of the operating system
• The current state of debugon, even if set from the console
• The current state of debuglog, even if set from the console
• A boolean indicator of whether the OAuth is logged in as the Bot (but not the actual OAuth token)
• A boolean indicator of whether the API OAuth is logged in as the Broadcaster (but not the actual OAuth token)
• The full stack trace of the exception

To opt out of Rollbar exception reporting, add the following line to the botlogin.txt:

userollbar=false

Docker users can opt out using the above method, or by adding the following environment variable to the container:

PHANTOMBOT_USEROLLBAR=false

for docker-compose.yml

PHANTOMBOT_USEROLLBAR: "false"

You must restart the bot after putting the opt-out for the change to take effect. Editing a Docker container or docker-compose may require more steps to apply the changes, consult your manual.

If you believe your data has already been sent and want to issue a GDPR delete request, please opt out as above and then send your bot name, broadcaster name, and the rollbarid from botlogin.txt to: gdpr /A\T/ phantombot // hopto \ org

We also accept requests for copies of your data. GDPR requests are accepted from all users, even those who do not live in a locale that has such laws.

Please note that the IP addresses in the DDOS logs can not be retrieved or deleted manually, but will be automatically deleted after 5 weeks by log rotation.

⭐ Major Changes

➡️ Added Rollbar exception tracking, please see above
➡️ Added ability for the poll overlay as well as all of the bets, poll, raffle, etc to be saved across restarts and refreshes as long as they are still open
➡️ Docker no longer runs as root (May cause issues if you bind it to a specific folder on your drive instead of using Docker volumes)
➡️ Added the ability to exempt VIPs from chatMod
➡️ Added the ability to set independent cooldowns for subcommands !coolcom "adventure top5" 10 global (Note the double quotes are required)
➡️ Added all the new sub-gift types, bits, and the supported donation services to the panel feed, with the messages included
➡️ Added the config value proxybypasshttps=true for botlogin.txt to fix using reverse-proxies with usehttps=false
➡️ Added PubSub detection of follows and stream up/down, which should improve reliability and timing
➡️ Added the ability to have multiple sets of notice timers, and enable/disable individual entries in the notice timers
➡️ Cooldowns no longer trigger if the user did not have enough points to use the command
➡️ Fixed the panel login page not redirecting back to the page that triggered it (oauth, etc)
➡️ The panel now has proper drop-downs for selecting Discord channels on the appropriate modules

Full Changelog

✅ Added:
➡️ Added follow history to the panel, along with a button to replay the alert (tsaquet #2429)
➡️ Added a task to the updater script that will delete any org.mozilla.javascript entries from the time leaderboard on the first run after installing this update (gmt2001, reported by mkleemann #2467)
➡️ Added reminder every 5 minutes, but only when attempting to send a message, for non-mod/switched oauth (gmt2001 gmt2001#144)
➡️ Added bool TwitchValidate.hasOAuthInconsistencies(String botName) (gmt2001)
➡️ Added additional binding of port 80 on the built-in webserver when baseport is 443 (gmt2001 gmt2001#147)
➡️ Added a sub-object to the response of the version query from /ws/panel containing broken-down version information (gmt2001)
➡️ Added support for nightly builds to the update notifications (gmt2001 gmt2001#54)
➡️ Added the ability for the polls OBS/XSplit overlay to ping the script to return a start_poll packet after authenticating, thus restoring the overlay after a refresh (gmt2001)
➡️ Added helper functions Optional<Snowflake> DiscordUtil.channelId(Channel), String DiscordUtil.channelIdAsString(Channel), and String DiscordUtil.channelName(Channel) (gmt2001)
➡️ Added ability to exempt VIPs from chat moderator checks (gmt2001 gmt2001#29)
➡️ Added the ability for core scripts to auto-load from the recursive script loader, if not explicitly loaded beforehand (gmt2001)
➡️ Added the Shutdown event, which fires synchronously if a proper shutdown (exit console command, CTRL+C, or SIGTERM) of the bot is caught and handled (gmt2001)
➡️ Added !notice toggleid (notice id) which toggles an individual notice on/off (gmt2001 gmt2001#82)
➡️ Added automatic refresh to the quotes panel page (gmt2001 gmt2001#122)
➡️ Added String[][] $.inidb.executeSql(String sql, String[] replacements) for custom scripting, which uses replacements as the values to escape and replace into the query via a java.sql.PreparedStatement. Return value is a 2D array of results, if any, with the outer array being rows and inner array being columns (gmt2001)
➡️ Added the ability to perform a random draw from queueSystem with !queue random [number to draw] (gmt2001, requested by Casper-O #2438)
➡️ Added the ability to set independent cooldowns for subcommands 2 levels deep via!coolcom, example !coolcom "adventure top5" 10 global. Note that the double quotes are required for this (gmt2001, requested by Sartharon #2459)
➡️ Added anonymous gift subs, mass gift subs, and anonymous mass gift subs to the panel dashboard event feed (gmt2001)
➡️ Added the sub tier and message, if any, to subscription events in the panel dashboard event feed (gmt2001)
➡️ Added the message, if any, to bits events in the panel dashboard event feed (gmt2001)
➡️ Added donations from all three supported services to the panel dashboard event feed (gmt2001, requested by robsdedude #2461)
➡️ Added cache-control headers to the panel to prevent browser caching (gmt2001 gmt2001#152)
➡️ Added the ability to save/change a time variable, using !settimevar, and then retrieve it, using (gettimevar name:str) for use in (countdown) and (countup) independently of the custom command where it is used (gmt2001, requested by nixmomo #2477)
➡️ Added methods to CaselessProperties to support uniform retrieval of properties as an Int, Double, or Boolean, as well as allowing a lambda or method to be provided for returning a default value (gmt2001)
➡️ Added Rollbar exception reporting (gmt2001)
➡️ Added help links to the panels help page (gmt2001, requested by argash #2531)
➡️ Added the config value proxybypasshttps=true for botlogin.txt which makes /sslcheck and others return true, for use with a reverse proxy. This should be used with usehttps=false (gmt2001, requested by alimuratgymn #2536)
➡️ Added the ability for the webserver, and thus the automatically refreshing OAuth tokens page, to stay up and work if the OAuth token comes back invalid. Does NOT work for first-time setup (gmt2001)
➡️ Added support for Windows Terminal, which provides UTF-8 and Emoji support. This is now the default launch option on Windows, if available (gmt2001)
➡️ Added a JavaScript auto-redirect to fix when /login or /panel are missing the trailing slash (gmt2001, reported by ZeldaZach #2562 gmt2001#166)
➡️ Added JSONObject StreamLabsDonationEvent.getData() (gmt2001)
➡️ Added PubSub topic video-playback-by-id for more reliable stream online/offline detection (gmt2001 #2527)
➡️ Added PubSub topic following for more reliable follow alerts (gmt2001 #2527)
➡️ Added the ability to have multiple groups of notice timers, each with their own settings (robsdedude #2528)

🌀 Changed:
➡️ Changed Docker builds to run as a service user instead of root (gmt2001, reported by bonny1992 #2465)
➡️ Changed the Discord posting of Twitch moderation logs to no longer be dependent on enabling the txt file moderation logs (PhantomBot/logs/moderation) feature via Twitch chat (gmt2001 gmt2001#28)
➡️ Open bets, raffles, ticket raffles, and polls are now saved across restarts (gmt2001 gmt2001#84 gmt2001#85 gmt2001#145)
➡️ Updated Discord4J to version 3.1.5 (gmt2001)
➡️ Moved !shoutout to the core (gmt2001)
➡️ Adjusted the colors for the event feed on the panel dashboard (gmt2001)
➡️ Changed the built-in panel to internally use the same logic as the remote panel, but hide it on the login page (gmt2001 gmt2001#151)
➡️ Changed the remote panel to be an automatic copy of the built-in panel (gmt2001 gmt2001#151)
➡️ Changed the input field for Discord channels on the panel to be a drop-down of channels, with free-form text still allowed (gmt2001 gmt2001#137)
➡️ Changed the OAuth refresh timer to only trigger when the tokens are nearing expiration (gmt2001)
➡️ Changed TwitchValidate to validate tokens hourly per Twitch rules (Only the initial validation will print to console unless debugging is on) (gmt2001)
➡️ Updated ticket raffle output messages to indicate purchased tickets and multiplier tickets separately (gmt2001 gmt2001#155)
➡️ Changed CaselessProperties to store/return the keys in lexicographical order (gmt2001)
➡️ Changed /oauth to make the difference in instructions for a single user performing both OAuths vs the Broadcaster doing theirs separately more clear (gmt2001)
➡️ Changed DonationsCache to track the last donationId via database (gmt2001, reported by Alucard2112 #2567)
➡️ Changed DonationsCache to send donation events before the initialized event (gmt2001)
➡️ Changed donationHandler to store the raw JSON String in the table (gmt2001)
➡️ Updated TwitchAlertsAPIv1 to use the after parameter of /donations (gmt2001, reported by Alucard2112 #2567)
➡️ Changed failed to dispatch messages to print the underlying stack trace to the console, instead of only to the logs (gmt2001 gmt2001#167)
➡️ Changed init.js to auto-subscribe to all event hooks with the standard handler, unless a special handler is set (gmt2001 gmt2001#157)
➡️ Changed exclude checkboxes in moderation filter settings to match the implementation (gmt2001, reported by alexratman #2535)
➡️ Changed the GH (remote) panel to use the latest stable panel release when connecting from a stable release of v3.5.0 or later (gmt2001 gmt2001#154)

🛠️ Fixed:
➡️ Fixed command cooldown triggering even if the sender didn't have enough points to use the command (Corben78 #2472)
➡️ Fixed Twitch online/offline/game change notifications in Discord (from !streamhandler) not removing @mentions in the embed card (gmt2001 gmt2001#94)
➡️ Fixed the !botname moderate command (gmt2001, reported by Sartharon #2456)
➡️ Fixed DiscordUtil.removeRole not issuing a subscribe() against the Mono object, thus preventing the command from processing (gmt2001, reported by Eriphram)
➡️ Fixed missing mirror of compiler --add-exports directives in launch scripts (gmt2001, reported by MyHollo #2473)
➡️ Fixed !stealsong not always refunding points if triggered from the panel (gmt2001 gmt2001#107)
➡️ Fixed BSD crashing due to using SQLite when there is no driver. BSD will default to H2 (gmt2001, reported by PaulTGG gmt2001#153)
➡️ Fixed DataStore.GetBoolean and DataStore.SetBoolean being incompatible with Rhino (gmt2001)
➡️ Fixed the Recent Events list failing to update in the panel once it had 50 items (gmt2001, reported by FlikstRR)
➡️ Fixed some command tags failing on a keyword due to expecting a CommandEvent (robsdedude #2526)
➡️ Fixed !traffle messagetoggle missing a ticket raffle entry success message (gmt2001, reported by nononom12 gmt2001#155)
➡️ Fixed ticket raffle counting bonus entries against the entry cap (gmt2001, reported by nononom12 gmt2001#155)
➡️ Fixed potential for ticket raffle to give fractional tickets via the multiplier (gmt2001 gmt2001#155)
➡️ Fixed potential for viewers to request a fractional number of tickets in a ticket raffle (gmt2001 gmt2001#155)
➡️ Fixed the OAuth page using the wrong login URI (gmt2001)
➡️ Fixed the OAuth page messing up the Twitch Connect URL after a successful authorization (gmt2001)
➡️ Fixed TwitchCache.updateClips not working due to the absence of tracking_id (gmt2001 rb#6 rb#127)
➡️ Fixed the panel login page ignoring the kickback parameter (gmt2001 gmt2001#163)
➡️ Fixed the broadcaster URL on the OAuth page being incorrect (ZeldaZach #2560)
➡️ Fixed a few JSONException (gmt2001 rb#134 rb#138 rb#128)
➡️ Fixed a potential StringIndexOutOfBoundsException caused by calling DataStore.IncreaseBatchString with an empty keys array (gmt2001 rb#125)
➡️ Fixed rare NPE when retrieving roles from Discord (gmt2001 rb#137)
➡️ Fixed donations that have already been seen repeatedly getting sent to the panel feed (gmt2001, reported by Alucard2112 #2567)
➡️ Fixed chat message for inbound raids showing the wrong number of times the raider has previously raided (UserModel, reported by therentabrain #2566 #2570)
➡️ Fixed TwitchAPIv5.translateFollowData forcing _success to false, causing followers to not register from the API (gmt2001 gmt2001#167)
➡️ Fixed (random) sometimes printing Undefined when no users have been detected by the bot in chat yet (gmt2001, reported by Motyldrogi #2544)
➡️ Fixed excluding VIPs from chatMod filters causing a script error that prevented moderation filters from triggering (gmt2001, reported by Lyeos #2549)
➡️ Fixed (playsound) tags with non-existent filenames causing follower, subscription, bits, host, raid, and donation responses to not fire (gmt2001)
➡️ Fixed DiscordUtil causing an Exception when a new channel type that our current D4J doesn't support is encountered (gmt2001)

🗑️ Deprecated:
➡️ The OAuth page on https://phantombot.github.io is deprecated, may be removed in the future, and may be missing OAuth scopes required for certain features. After using this page to setup, please switch to automatically refreshing OAuth tokens from the bots built-in webserver http://localhost:25000/ (gmt2001)

🛑 Removed:
➡️ Removed all updater tasks from before PhantomBot v3.3.0 (gmt2001)
➡️ The file addons/hostHandler/latestHostOrAutoHost.txt is removed, please switch to addons/hostHandler/latestHost.txt (gmt2001 #2431)

🐞 Known Issues:
➡️ Due to the sub tiers not being previously saved in the panel dashboard event feed, existing event feed entries for subs will show the sub tier as undefined
➡️ The donation repeating issue is expected to occur 1 time if updating from a version that does not have the fix. After the 1 occurrence, the new tracking should kick in and prevent future occurrences

🌐 Download It:
➡️ Downloads attached to the bottom of this release notice

❗ Remember to install to a separate folder, then copy over the config dir, as well as any custom scripts or files in addons

➡️ PhantomBot official builds are available on Docker at gmt2001/phantombot-stable and gmt2001/phantombot-nightly. See the readme text on the appropriate Docker Hub pages for Docker Compose files

🗒️ Notes:
➡️ We have guides on PhantomBot. You can contribute by submitting a Pull Request adding or editing .md files in the /docs/guides/content folder of the repo. See the guides for info about formatting.

➡️ $.inidb.executeSql is designed for personal, custom script use where the DataStore backend being used is known and will not change. Issues can, and will, occur if the SQL is written for one DataStore backend and the statement is then executed on a different backend.

➡️ As of this release, the PhantomBot-x.y.z-arm.zip package has been renamed to PhantomBot-x.y.z-arm-bsd-other.zip

➡️ The Windows launch script supports the --nowt command line argument to force launching from Command prompt instead of switching to Windows Terminal