Tlapbot

Tlapbot is an Owncast bot that adds channel points and channel point redeems to your Owncast page.

Similar to Twitch channel points, Tlapbot rewards your viewers with points for watching, and allows them to spend their points on fun gimmicks, challenges, reaction requests, or whatever else you decide.

Tlapbot makes use of Owncast webhooks for chat interactions and Owncast external actions to display an informative dashboard.

Features

The bot gives points to everyone in chat -- 10 points every 10 minutes by default, but the time interval and amount of points can be changed.

The users in chat can then use their points on redeems -- rewards like "choose my background music", "choose what level to play next", "react to this video" etc. You can configure redeems to fit your stream and the activities you're doing, and sort them into categories that can be turned on and off.

The redeems then show on a "Redeems dashboard" that everyone can view as an External Action on the Owncast stream, or at its standalone URL. This allows easy browsing of active challenges and recent redeems, without quitting the stream.

Tlapbot currently doesn't support any automated integrations (or an API). That means no 'Crowd Control' plugin, no instant effects in OBS or VTube Studio, etc. The streamer decides how they respond to redeems or how to make them take effect. (I'd love to support more seamless, automatic redeems in the future!)

Tlapbot bot commands

Tlapbot has these basic commands:

• !help sends a help string in the chat, explaining how tlapbot works.
• !points shows a chatter how many points they have.
• !name_update is a special debug command, to be used with the user's name displays wrong in the redeem dashboard. Normally, it shouldn't have to be used at all, as display names get updated automatically when the bot is running.

(If you change the default prefix of ! to something else, these commands will use the new prefix instead.)

Tlapbot also automatically adds a command for each redeem in the redeems file.

Tlapbot dashboard

Tlapbot dashboard is a standalone page available at /dashboard, made to be easily viewable as an owncast external action. The Tlapbot dashboard shows all redeems and active counters.

Counters are at the top, followed by a list of active milestones and their progress.

Tlapbot dashboard also shows the chatter's points balance when they open it as an external action.

Tlapbot dashboard when viewed as an external action.

Redeem queue tab

The redeem queue shows a chronological list of note and list redeems with timestamps, the redeemer's username, and the note sent.

Redeem queue tab.

Redeems help tab

The dashboard also has a "Redeems help" tab. It shows an explanation of redeem types, and lists all active redeems, along with their price, type and description.

Passive mode

Tlapbot can also be run in passive mode. In passive mode, no redeems will be available, and Tlapbot will not send any messages.

However, it will still give points to viewers, and track username changes.

The Tlapbot dashboard will display a passive mode disclaimer instead of redeems.

Tlapbot redeems types

Tlapbot currently supports four different redeem types. Each type of a redeem works slightly differently, and displays differently on the redeems dashboard.

Redeems can also optionally be sorted into "categories" that can be turned on or off in the config file. This means that the redeems file can list redeems for different types of streams, and you can turn them on or off. Examples on how to do that are listed later in the config file examples.

List

List redeems are basic redeems, most similar to the ones on Twitch.

Every time a chatter redeems a List redeem, the redeem gets added to the list of recent redeems with a timestamp, similar to how redeems on Twitch get added to the Twitch redeem queue.

Unlike the Note redeems, chatters can't write messages to send along with their List redeems, so make sure the redeem makes sense on its own, like "stop talking for one minute", or "drop your weapon", etc.

Note

Note redeems are like List redeems, they get added to the list of recent redeems.

Unlike the List redeems, chatters can add a message to their Note redeems, so this is the ideal type for open-ended redeems like "choose what character I play as next", "choose what song to play next", etc.

Counter

Counter is a unique redeem type, in that it doesn't show up in the list of recent redeems, and counters don't list the people who redeemed them. This redeem type is good for any rewards or incentives where the important thing isn't "who redeemed it?" but rather "how many people redeemed it?"

Instead, the tlapbot dashboard keeps a number for each "counter", and each redeems adds +1 to it.

Counter redeems can be used to gauge interest, tally up votes, or to keep track of how many emotes should be added to an OBS scene.

Milestone

Milestone redeems are long-term goals that are reset separately from other redeems. Viewers donate variable amounts of points that add up together to fulfill the milestone goal.

Each milestone has a goal, a number of points required to send, and the points from all users add together to progress and reach the goal.

Milestones show as a progress bar on the dashboard.

Milestone redeems can be used as long-term community challenges, to start streamer challenges, decide new games to play, etc.

License & Contributions

Tlapbot as it currently is does not come with a license. If you're a content creator, streamer, vtuber, etc. I'll be happy to give you permission to use Tlapbot, or make changes that'd fit your stream.

I didn't make Tlapbot available under a permissive or a free software license, as Owncast is also used by some religious groups, extremist individuals, and dubious corporations to self-host their streams, and I do not want for them to use the bot.

Setup

Tlapbot requires Python 3, probably a fairly recent version of it too. (My live instance runs on Python 3.9.2.)

The Python prerequisites for running tlapbot are the libraries flask, requests and apscheduler. If you follow the installation steps below, they should automatically be installed if you don't have them.

You can also run Tlapbot in a Python virtual environment.

Install from git repo (as a folder)

1. Clone the repository.

2. Run pip install -e . in the root folder. This will install tlapbot as a package in editable more.

3. Set the FLASK_APP environment variable.

   export FLASK_APP=tlapbot
   

4. Initialize the database:

   python -m flask init-db
   

5. Create an instance/config.py file and fill it in as needed. Default values are included in tlapbot/default_config.py, and values in config.py overwrite them. (The database also lives in the instance folder by default.)

   Tlapbot might not work if you don't overwrite these:

   SECRET_KEY # get one from running `python -c 'import secrets; print(secrets.token_hex())'`
   OWNCAST_ACCESS_TOKEN # get one from owncast instance
   OWNCAST_INSTANCE_URL # default points to localhost owncast on default port
   

6. OPTIONAL: Create an instance/redeems.py file and add your custom redeems.
   If you don't add a redeems file, the bot will initialize the default redeems from tlapbot/default_redeems.py.
   More details on how to write the config and redeems files are written later in the readme.

7. If you've added any new counters or milestones, run refresh-counters or refresh-milestones commands to initialize them into the database.

This installation is fine both for just running Tlapbot as it is, but it also works as a dev setup if you want to make changes or contribute.

Updating should be as easy as git pulling the new version. Sometimes, if an update adds new database tables or columns, you will also need to rerun the init-db CLI command.

Owncast configuration

In the Owncast web interface, navigate to the admin interface at /admin, and then go to Integrations.

Access Token

In the Access Tokens tab, generate an Access Token to put in the config file in the instance folder. The bot needs both the "send chat messages" and "perform administrative actions" permissions, since getting the list of all connected chat users is an administrator-only action.

Webhook

In the webhooks tab, create a Webhook, and point it at your bot's URL with /owncastWebhook added.

In debug, this will be something like localhost:5000/owncastWebhook. If you're not running the debug Owncast instance and bot on the same machine, you can use a tool like ngrok to redirect Owncast traffic to your localhost.

External Action

In External Actions, point the external action to your bot's URL with /dashboard added.

External Actions only work with https. Your server will need to support SSL and https connections for this part to work.

In development, a localhost address will not work with External Actions, since it doesn't provide https. If you use ngrok to redirect Owncast traffic to localhost, it will work because the ngrok connection is https.

External Action config example:

URL: MyTlapbotServer.example/dashboard
Action Title: Redeems Dashboard

Note about https and reverse proxying

Sin