OwnchatBot

OwnchatBot

A feature rich chatbot for Owncast.

Table of Contents

• Features
• Screenshots
• Requirements
• Installation
• Upgrading
• Running OwnchatBot
• Final Configuration
• Donations
• Kofi Integration
• GiveButter Integration
• Overlays
• To-do List
• Alerts
• Chat Commands
• Roadmap
• Support
• Contributing
• License
• Attribution

Features

• Compatible with Owncast v0.2.4.
• The standard chat points/rewards system most of us are familiar with. Viewer redeems their points for a reward, streamer does a thing or some other function gets triggered.
• Voting. The streamer can create votes for viewers to choose from.
  • The current vote tally can be set up as a browser source, to display on-screen.
• Special rewards that will run commands for things like triggering webhooks and running scripts.
• Goals that viewers can collectively contribute points to for rewards.
  • Goal progress can be set up as a browser source in your streaming software, to display on-screen.
  • Milestones can be set up within goals, for little rewards along the way.
• Cool down timers for rewards and specials.
• Automated announcements at regular intervals.
• Web based viewer panel for viewing the reward queue, and points and reward information.
• Web based management panel.
  • Authentication handled by your Owncast server, using IndieAuth. Use the same credentials you use for your Owncast admin page.
  • Configure OwnchatBot settings, Owncast integration and Kofi integration.
  • Add/edit/remove rewards and reward categories.
  • Viewer management for manually adjusting viewers' points.
  • A queue manager, where the streamer can mark rewards fulfilled as they go, or refund rewards if needed.
• Kofi and GiveButter integration.
  • Your viewers can get points for donating via Kofi or GiveButter, and as part of their monthly Kofi membership.
• To-do list. Add tasks and cross them off as you complete them.
  • Also has an overlay to display the list on your stream.

Screenshots

Vote, goal, and to-do list overlays

Viewer Panel

  

Management Panel

                    

Requirements

• Git
• A recent version of Python.
  • If using Debian, make sure python3-venv is installed.
• Your Owncast instance must be running in https for IndieAuth authentication to function correctly.
• It is HIGHLY recommended to run OwnchatBot behind a reverse proxy.
  • If your Owncast instance has a reverse proxy, you'll need a separate reverse-proxy for OwnchatBot.

Installation

1. You can simply download the zip/tar file from the git repo, and decompress it, but I recommend cloning the repo instead. It will make upgrading to future versions much easier.

   git clone https://git.deadtom.me/deadtom/OwnchatBot.git
   

2. At the command line, descend into the "OwnchatBot" folder.

3. To start the install, run:

   bash install.sh
   

4. The install script provides the URL for your OwnchatBot management panel. Bookmark it.

Upgrading

Get the latest version

Make a backup of your OwnchatBot/instance folder.

Descend into the OwnchatBot directory. Run:

  git pull

If you installed by downloading from the repo, rather than doing a git clone, simply download the new version and extract the file over your existing installation.

Run the upgrade script

This will make any necessary upgrades to your existing database and config files. Run:

  bash upgrade.sh

Running OwnchatBot

Port 8081 used here as an example. Change it to whatever port you'd like your bot to listen on.

Run OwnchatBot:

env/bin/python -m gunicorn -b 0.0.0.0:8081 -w 1 'ownchatbot:create_app()'

The above command directs all output to the console, but I prefer to have it all dump into a log file. You can do this with a small modification to this command:

env/bin/python -m gunicorn --error-logfile ownchatbot.log -b 0.0.0.0:8081 -w 1 'ownchatbot:create_app()'

A caveat here: Some features are managed by a module called apscheduler. I chose this for its simplicity, however, it doesn't play well when trying to run the app with more than one worker. The "-w 1" option in the gunicorn command specifies just one worker. If you run it with more, it will multiply the jobs that apscheduler manages. For example, "-w 4" will start four workers, and every job apscheduler performs will get run four times. OCB will continue to function fine, but you'll see fun things like announcements getting repeated four times, and viewers getting awarded four times your configured points awards. OCB isn't yet so huge that it really needs more than one worker, but at some point I might try to move away from apscheduler.

Final configuration

Once OwnchatBot is running, you can start setting up your rewards and other options at /mgmt.

Authentication is handled using your Owncast server as an IndieAuth server, so your login credentials are the same credentials you use to log into your Owncast Admin page.

The first thing you'll want to visit is the settings page. Each option is explained in detail. Then you'll need to get it talking to your Owncast instance, and Kofi if you'll be using it, both covered below.

Owncast connection

OwnchatBot accesses Owncast chat room information via a webhook. You'll need to point Owncast at that webhook for things to function.

1. Go to your Owncast Admin panel -> Integrations -> Webhooks
2. Click on "Create Webhook"
3. In the top field, enter OwnchatBot's address and port which you set up in the "Running OwnchatBot" section, with /ocbHook appended. Example: http://<your.ocb.address>/ocbHook
4. Click the "Select All" button.
5. Click "OK"

Owncast viewer panel button

You need to create a button on your Owncast page, so your viewers can access the Rewards Panel to view their points, the rewards queue, and other helpful information. This will only work with an SSL enabled server. If you're running Owncast behind a reverse proxy (which you really should be) then you need to set up another reverse proxy for OwnchatBot. Sorry, you're on your own for how to do that. It's way outside the scope of this document.

1. Go to your Owncast Admin panel -> Integrations -> External Actions.
2. Click on "Create New Action"

3. Set the second field to your external OwnchatBot server address, and the port you set up in the "Running OwnchatBot" section, with /userpanel appended. Example:

   https://<your_external.ownchatbot.url>/userpanel
   

4. Set the third field (action title) to "Stream Rewards". Example:

   Action Title: Stream Rewards
   

5. Configure the remaining fields/options as desired.

Donations

Only Owncast authenticated users can get donation benefits. So the first thing viewers need to do is authenticate their username with Owncast.

OwnchatBot associates viewer accounts with Ko-fi and GiveButter accounts using the viewer's email address. So in order for viewers to get donation benefits in-stream, they must enter their email address in OwnchatBot viewer panel -> OwnchatBot Info -> Donations.

If a viewer donates/subscribes before entering their email address, OwnchatBot creates a temporary entry with their email and points award, and then applies it once the viewer enters their email address into the viewer panel. If there is any sort of mix-up here, the streamer can manually connect the viewer's email and account via the management panel by entering the email into the viewers account. OwnchatBot will do the merge automatically. There are more details about this in the Manage Accounts panel

Email addresses are ONLY used for donation integration. They are not sent to any other individual or company, will not be used to create or send mailing lists of any kind, or for any other purposes. Ever.

Ko-fi has support for anonymous donations built right in, but GiveButter doesn't yet. So as a work-around, I've put instructions for setting up GiveButter custom fields at the bottom of the Donations management panel. Keep in mind this only makes them anonymous for OwnchatBot. All details are still visible in the GiveButter dashboard. Ownchatbot will still send a chat alert for anonymous donations, but no identifying information is included. OwnchatBot also does not log any identifying information related anonymous donations.

Kofi Integration

Make sure you don't lose your viewers' benefits! It is extremely important that you back up your instance folder daily, if not hourly.

Integration is accomplished via a webhook triggered by Ko-fi every time a donation or subscription is made. Again, this webhook is your external OwnchatBot server address with /kofiHook appended.

A Ko-fi alert overlay is not built in to OwnchatBot, since Ko-fi already provides a fairly customizable alert webhook for just this purpose.

Paste the webhook address into Ko-fi -> More -> API -> Webhooks -> Webhook URL.

  https://<your_external.ownchatbot.url>/kofiHook

Click "Update", but stay on this page.

You need the verification token from Ko-fi. Ko-fi sends this token when it triggers the webhook. Below "Webhook URL", click on "Advanced". A pre-generated token will already be there. Copy that token, and paste it into the OCB Management Panel -> Donations -> Kofi -> Verification Token. Then click "Save".

GiveButter Integration

Make sure you don't lose your viewers' benefits! It is extremely important that you back up your instance folder daily, if not hourly.

Integration is accomplished via a webhook triggered by Kofi every time a donation or subscription is made. This webhook is also your external OwnchatBot server address with /gbHook appended.

Enter this in the GiveButter dashboard -> Settings -> Developers -> Webhooks -> +New Webhook.

  https://<your_external.ownchatbot.url>/gbHook

You need a signing secret from GiveButter. This is sent when it triggers the webhook. To get this, go to the Webhooks page in the GiveButter dashboard, and click on the eye icon (View) next to the webhook you set up for OwnchatBot. Copy the signing secret, and paste it into the OCB Management Panel -> Donations -> GiveButter -> Signing Secret. Then click "Save".

Overlays

To display vote and goal progress on-screen, in your stream, create two browser sources in your streaming software.

If you'd like to use custom fonts in any of these overlays, put the font file in your instance/assets folder and reference the following location in your CSS: /assets/yourfont.ttf

Votes: http://<your.ocb.address>/votes

• Recommended width: 420
• Recommended height: 150
• In OBS, check "Refresh browser source when scene becomes active"

Goals: http://<your.ocb.address>/goals

• Recommended width: 610
• Recommended height: 210
• In OBS, check "Refresh browser source when scene becomes active"

Example CSS:

td {
    font-size: 20px;
}

To-do list

You can set up a to-do list to display over your stream. Add, cross off or remove tasks using the "To-Do list" menu in the management panel. To display the list on-screen, create a browser source in your streaming software using the following information.

To-do list: http://<your.ocb.address>/todo

• Recommended width: 420
• Recommended height: 500
• In OBS, check "Refresh browser source when scene becomes active"
  • Use the "Custom CSS" field to spruce up your list with fonts, colors, or anything else you'd like.

Example CSS:

h4 {
    font-size: 32px;
    text-decoration: underline;
    text-align: center;
    margin-bottom: 0;
    padding-bottom: 0;
}

ul {
    margin-top: 0;
    padding-top: 0;
}

li {
    font-size: 30px;
}

Alerts

You can upload custom images and videos to display on your stream when a viewer follows you, or when a goal or milestone is reached. To display these on-screen, create browser sources in your streaming software using the following information.

Follower alert: http://<your.ocb.address>/alert/follower

Milestone alert: http://<your.ocb.address>/alert/milestone

Goal alert: http://<your.ocb.address>/alert/goal

• Recommended width: 200
• Recommended height: 200
• In OBS, check "Refresh browser source when scene becomes active"
  • Use the "Custom CSS" field to set the font and position of viewer names displayed over your alert images.

Example CSS:

#nameBox {
    top: 50%; /* Vertical position */
    left: 50%; /* Horizontal position */
    font-size: 20px; /* Adjust as needed */
    font-weight: bold; /* Adjust as needed */
}

Chat commands

All command and rewards are preceeded with a prefix configured in the management panel. "!" by default.

• !help - Displays a short summary of features available to viewers.
• !rewards - Displays currently active rewards, votes and goals.
• !points - Displays the viewer's current points balance.

Roadmap

In this order

• Vision impaired accessibility changes.
• GiveButter integration.

Not necessarily in this order

• Streak tracker, to track how many consecutive streams a viewer has watched, and reward accordingly.
• Get emojis in OwnchatBot panels working correctly, because Wonderwmn insists on it.
• Option to only allow authenticated users or Kofi subscribers to redeem certain rewards.
• !Timer - Set a timer that will sound an audible alarm. A command only available to the streamer or mods.
• A "watch" function that watches chat for certain words or phrases, and responds with preset messages.

Support

For support (a bug, feature request/tweak, question or comment), you can contact DeadTOm via the following methods:

• Mastodon
• Email: deadtom@deadtom.me
• XMPP: deadtom@deadtom.me

Contributing

If you are thrilled to death with OwnchatBot, and want to throw a bit of monetary love DeadTOm's way, you can do so via Kofi. If you'd like to contribute code, contact DeadTOm about setting up an account on his Gogs instance.

License

OwnchatBot © 2025 by DeadTOm is licensed under Creative Commons Attribution-ShareAlike 4.0 International.

Attribution

The SmallRobo image was created by Mike Carey, mikecarey134@gmail.com. I've modified the image, but you can find the original image at Open Game Art. At the time of this writing, it is released under a Creative Commons CC-BY 3 license.

The basic layout of the user and management panels was copied from the tab bar tutorial on w3schools.com.

Screen reader readability tested by The esoteric programmer.

Various testing for installation and GiveButter integration was done with the help of Ozoned.

The overlays screenshot was provided by Wonderwmn, from one of her co-working streams.

The food that keeps me alive during all-weekend coding sessions is also provided by Wonderwmn.