TimberBot

TimberBot is a chat bot written in Python that features a plugin-based architecture and is geared towards use on the Twitch.tv platform.

This is a project that has grown and diminished slowly over the years. It started in 2014 as a small query-response bot for one specific Twitch channel, then grew to a flexible bot service framework spanning two handfuls of channels across Twitch, Hitbox, Picarto and Discord, before contracting back down to a simplified version that's reasonably easy to self-host for your own Twitch chat. If you are looking for a technical reason to choose this bot over competing products, there probably isn't any. I just want to publish the code I've written to allow people to reuse it. It never achieved the stability it needed to become a full-fledged service, but maybe it'll find its niche as a self-hostable open source project that's easy to extend. Use at your own risk.

Basic things you should know if you want to self-host TimberBot:

• The main way to configure it is through the chat itself. Chat commands are used to enable and disable functionality, to change configuration settings, and virtually all other admin tasks. There is no graphical interface.
• Almost all user-facing functionality is contained in plugins that can be enabled and disabled individually.

Project website: https://fietkau.software/timberbot

Requirements

TimberBot requires a reasonably recent Python 3 along with the websocket-client package (not to be confused with websocket or websockets). More packages may be required depending on the plugins you choose to enable. It feels at home on Linux, but should be OS-agnostic (albeit untested).

Installation

From a fresh copy of the repository, you should be able to run timberbot.py through Python 3 to check whether your Python environment is supported. If you are missing any required packages, it'll tell you right away. If not, it will try (and fail) to connect to the Twitch chat from the example configuration. Whenever it hangs, it can be interrupted using Ctrl+C.

Connecting to Chat

To connect your bot to Twitch chat, you will need an OAuth access token. The process to create one is a bit of a pain in the rear. First you need to register your bot as a new Twitch app. Unless you coincidentally have a self-hosted Twitch app token generator ready to go, you can set the redirect URL to https://localhost:3000 as this tutorial recommends at the time of writing. Mainly you need to acquire your bot's Client ID before you can proceed. With the Client ID in hand, you can follow the second tutorial I just linked (the "for testing chat functionality" part) to acquire your OAuth token from your redirect URL. It will look like a long-ish random alphanumeric string. Whatever Twitch account you are logged into when you do this, that will be the Twitch account that the bot will appear as. If you want to register a custom Twitch account for it, you can, or you can just use your streamer account.

Next, edit config.ini in a text editor of your choice. In the [main] section, change nick to the name of the Twitch account you want to use for your bot. This must match the account that owns the OAuth token you just created. Change password to your OAuth token, keeping the oauth: prefix. Change channel to your Twitch channel name, i.e. the chat where you want the bot to appear, and admins to your own Twitch account name (and a space-separated list of other bot admins if desired). Everything else can be left as-is for now.

Now run timberbot.py again. If everything is correct, the bot should log in and appear in your chat. Any chat messages you type should appear in the Python window. You can use the "!about" command to test whether it can post messages of its own.

Enabling and Disabling Plugins

Note: Never edit config.ini while your bot is running. It will almost certainly overwrite your changes. TimberBot makes changes to the config file as needed while it is running and keeps an internal copy for that purpose.

You should be good to go to test some basic functionality now. Try putting !plugins in chat to get a list of plugins that are currently enabled as well as a list of the ones that are additionally available. Type !enable announcements to enable the announcements plugin. If you get any errors here, they should be investigated and fixed before you proceed.

You'll find that the current list matches the plugins entry in your config file. As you make changes to the configuration, you should see your config.ini file update itself. When the bot is not running, you can also edit the list of enabled plugins through the config file. Please note that the order may matter: some plugins depend on others, for example the stream_tracking plugin depends on the stream_platform_twitch one. If you want to make sure you enable them in a working order, you need to do it one by one through the chat interface, which will respond with an error message if something does not work.

What you do from here on is up to you. Most of the plugins are not documented, so your best bet is probably to experiment with whatever seems interesting, especially at the beginning when you have nothing to lose yet. Plugins should generally not be able crash the entire bot, even if you do something wrong.

Optional: Connect Your Bot to the Twitch API

So far your bot can interact with chat messages, but not much else. To access more Twitch integration functionality, such as follower alerts or stream game tracking, we're going to need to mess with more access tokens. If your bot is still running, shut it down for this.

In the default config.ini, there is a pre-populated section for the stream_platform_twitch plugin. Change channel to your channel name, client_id to your bot's Client ID from earlier, and client_secret to your bot's client secret. We have not needed that last one so far, but you can access it in the developer portal alongside the Client ID. As the website notes, you can generate a new secret whenever you want (invalidating any previous ones), but the website will only show it one time, so make sure to store it safely and never expose it to the public.

With the changes to the configuration made, start your bot and enable the stream_platform_twitch plugin. Watch the Python console window for any errors. If there are none, you should see some added configuration parameters in your config file afterwards. Your bot is now connected to the Twitch API and you can enable plugins like stream_tracking and stream_game.

Optional: Setting Your Bot up as a Linux System Service

Assuming you want to run your bot as a 24/7 service on a Linux server, my recommendation is to create a timberbot user that has its own home directory where you can install the bot's code.

Here's an example for a systemd service file that will make it run as a persistent service:

[Unit]
Description=TimberBot
After=network.target

[Service]
User=timberbot
ExecStart=/usr/bin/python3 -u /home/timberbot/timberbot.py

[Install]
WantedBy=multi-user.target

Place that into /etc/systemd/system/ as timberbot.service, run systemctl daemon-reload and systemctl enable timberbot.service (both as root) to make it run automatically at system startup.

If you want to reboot your bot automatically every 24 hours, for example at 2:10 in the morning, add the following line to your /etc/crontab:

10 2 * * * root service timberbot restart

Valuable Knowledge

This is a list of unsorted bits of information that seem worth knowing, but do not have a good place in the above introduction.

• In the config file, you can change the data directory from the default to a different path anywhere on your system. The data directory is where plugins will save all their persistent files.
• The bot provides a !help command that lists all currently enabled commands. You can get help text for a specific command by typing !help commandname.
• The default command prefix is the exclamation mark "!" but you can change this to whatever you want, including multi-character words, in the config file. Spaces act as separators for multiple alternatives.
• From practical experience, the bot seems to sometimes silently lose the connection to the chat and miss out on messages. The only way I ever came up with to fix this is to kill and restart the timberbot.py script. If you run your bot as a 24/7 service, consider implementing an automatic kill switch every 24 hours at some time you are unlikely to be streaming.
• Instead of editing the config file while the bot is stopped, you can also use the !conf command (restricted to bot admins) to read or write any configuration setting including plugin settings by specifying a section name, a setting name, and optionally a new value.
• Plugins are Python files that can be modified and shared between TimberBot users. Plugins are not sandboxed, they have full access to your system and may take any action on your behalf. Do not install or use plugins provided by people you would not trust with your computer.
• If you'd like to separate the config file from the bot's Python code, you can provide a path to a different config file as a command line parameter to the timberbot.py script. This way you can use the same copy of the bot code to run multiple bot instances.

License

TimberBot (c) 2014-2022 Julian Fietkau

The bot itself consisting of all Python files in the root directory is using the GPLv3 (or later) license. The plugins inside their directory are all using the MIT license to make it easier to create derivative works.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE-GPLv3 for details.