# OwnchatBot
A chatbot for Owncast, enabling viewers to accumulate points which can be used to redeem stream rewards.
## Table of Contents
- [Features](#features)
- [Screenshots](#screenshots)
- [Roadmap](#roadmap)
- [Installation](#installation)
- [Running OwnchatBot](#running-ownchatbot)
- [Final Configuration](#final-configuration)
- [Overlays](#Overlays)
- [License](#license)
- [Attribution](#attribution)
## Features
* The standard chat redeems most of us are familiar with. Viewer spends points for the redeem, streamer does/says a thing.
* Voting. The streamer can create votes, and viewers can vote for them.
* The current vote tally can be set up as a browser source, to display on-screen.
* Special redeems 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.
* Cool down timers for redeems and specials.
* Web based viewer panel for viewing the reward queue, and points and reward information.
* Web based management panel.
* Configure OwnchatBot and Owncast integration settings.
* Add/edit/remove rewards and reward categories.
* Points management for manually adjusting viewers' points.
* A queue manager, where the streamer can mark rewards fulfilled as they go, or refund rewards if needed.
## Screenshots
#### Votes and Goals Overlays
#### Viewer Panel
#### Management Panel
## Roadmap
* Get emojis in OwnchatBot panels working correctly, because my partner insists on it
* Order reward list by price
* Audible sound when goal is reached
* Streak tracker, to track how many consequitive streams a viewer has watched, and reward accordingly
* Option to only allow authenticated users and/or followers to redeem.
* !Timer - Set a timer that will sound an audible alarm. A command only available to the streamer or mods.
* A system where OCB generates a code, which can be entered into the user panel to get points.
* The idea is to enable streamers to use services like Kofi or Patreon, which have an API, so users can purchase stream points, subscribe for monthly perks, or whatever else people might come up with.
* A "watch" function that watches chat for certain words or phrases, and responds with preset messages.
* Automated system messages at regular intervals.
## Installation
#### These instructions assume that you have git, and a recent version of python installed.
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.
```bash
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
bash init-ocb.sh
```
4. The last lines of init-ocb's output tell you how to proceed to the management panel, where you can set up Owncast integraion, and other odds and ends.
More detailed instructions for running OwnchatBot are covered below.
## Running OwnchatBot
### Running in Flask's native server
Port 8081 is used here as an example. Be sure to set a correct, usable port number.
Set the FLASK_APP variable:
```bash
export FLASK_APP=ownchatbot
```
Run the bot in debug mode:
```bash
env/bin/python -m flask --debug run --host=0.0.0.0 -p 8081
```
Run the bot:
```bash
env/bin/python -m flask run --host=0.0.0.0 -p 8081
```
### Running in Gunicorn
Set the FLASK_APP variable:
```bash
export FLASK_APP=ownchatbot
```
Run OwnchatBot:
```bash
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:
```bash
env/bin/python -m gunicorn --error-logfile ownchatbot.log -b 0.0.0.0:8081 -w 1 'ownchatbot:create_app()'
```
## Final configuration
Once OwnchatBot is running, you can start setting up your rewards and other options via the Management Panel. When you finish running init-ocb.sh, it gives you a URL for your management panel. It will look something like this, with a proper, pregenerated auth code attached to it.
http://localhost:8081/mgmt?auth=yourMGMT_AUTHcode
Once you're in the OwnchatBot management panel, bookmark it.
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, covered below.
### Owncast chat 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, with `/chatHook` appended (Example: http://localhost:8081/chatHook), which you'll set up below in the "Running OwnchatBot" section.
4. Click the "Select All" button.
5. Click "OK"
### Owncast user 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 OwnchatBot server address, and the port you set up in the "Running OwnchatBot" section.
4. Set the third field (action title) to whatever you want the button to be named.
Example:
```
http://localhost:8081/userpanel
Action Title: Points Rewards
```
5. Configure the remaining fields/options as desired.
Happy streaming!
### Overlays
To display vote and goal progress on-screen, in your stream, you need to create two browser sources in your streaming software.
Votes: ```http://localhost:8081/votes```
* Recommended width: 420
* Recommended height: 150
* Check "Refresh browser source when scene becomes active"
Goals ```http://localhost:8081/goals```
* Recommended width: 610
* Recommended height: 210
* Check "Refresh browser source when scene becomes active"
## License
OwnchatBot © 2025 by [DeadTOm](https://www.deadtom.me) is licensed under [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/).
## 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](https://opengameart.org/content/smallrobo).
At the time of this writing, it is released under a [Creative Commons CC-BY 3](https://creativecommons.org/licenses/by/3.0/) license.
The basic layout of the user and management panels was copied from the [tab bar tutorial on w3schools.com](https://www.w3schools.com/howto/howto_js_tabs.asp).
The food that keeps me alive during all-weekend coding sessions is provided by [Wondrwmn](https://wondrwmn.deadtom.me).
#### Management Panel
## Roadmap
* Get emojis in OwnchatBot panels working correctly, because my partner insists on it
* Order reward list by price
* Audible sound when goal is reached
* Streak tracker, to track how many consequitive streams a viewer has watched, and reward accordingly
* Option to only allow authenticated users and/or followers to redeem.
* !Timer - Set a timer that will sound an audible alarm. A command only available to the streamer or mods.
* A system where OCB generates a code, which can be entered into the user panel to get points.
* The idea is to enable streamers to use services like Kofi or Patreon, which have an API, so users can purchase stream points, subscribe for monthly perks, or whatever else people might come up with.
* A "watch" function that watches chat for certain words or phrases, and responds with preset messages.
* Automated system messages at regular intervals.
## Installation
#### These instructions assume that you have git, and a recent version of python installed.
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.
```bash
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
bash init-ocb.sh
```
4. The last lines of init-ocb's output tell you how to proceed to the management panel, where you can set up Owncast integraion, and other odds and ends.
More detailed instructions for running OwnchatBot are covered below.
## Running OwnchatBot
### Running in Flask's native server
Port 8081 is used here as an example. Be sure to set a correct, usable port number.
Set the FLASK_APP variable:
```bash
export FLASK_APP=ownchatbot
```
Run the bot in debug mode:
```bash
env/bin/python -m flask --debug run --host=0.0.0.0 -p 8081
```
Run the bot:
```bash
env/bin/python -m flask run --host=0.0.0.0 -p 8081
```
### Running in Gunicorn
Set the FLASK_APP variable:
```bash
export FLASK_APP=ownchatbot
```
Run OwnchatBot:
```bash
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:
```bash
env/bin/python -m gunicorn --error-logfile ownchatbot.log -b 0.0.0.0:8081 -w 1 'ownchatbot:create_app()'
```
## Final configuration
Once OwnchatBot is running, you can start setting up your rewards and other options via the Management Panel. When you finish running init-ocb.sh, it gives you a URL for your management panel. It will look something like this, with a proper, pregenerated auth code attached to it.
http://localhost:8081/mgmt?auth=yourMGMT_AUTHcode
Once you're in the OwnchatBot management panel, bookmark it.
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, covered below.
### Owncast chat 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, with `/chatHook` appended (Example: http://localhost:8081/chatHook), which you'll set up below in the "Running OwnchatBot" section.
4. Click the "Select All" button.
5. Click "OK"
### Owncast user 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 OwnchatBot server address, and the port you set up in the "Running OwnchatBot" section.
4. Set the third field (action title) to whatever you want the button to be named.
Example:
```
http://localhost:8081/userpanel
Action Title: Points Rewards
```
5. Configure the remaining fields/options as desired.
Happy streaming!
### Overlays
To display vote and goal progress on-screen, in your stream, you need to create two browser sources in your streaming software.
Votes: ```http://localhost:8081/votes```
* Recommended width: 420
* Recommended height: 150
* Check "Refresh browser source when scene becomes active"
Goals ```http://localhost:8081/goals```
* Recommended width: 610
* Recommended height: 210
* Check "Refresh browser source when scene becomes active"
## License
OwnchatBot © 2025 by [DeadTOm](https://www.deadtom.me) is licensed under [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/).
## 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](https://opengameart.org/content/smallrobo).
At the time of this writing, it is released under a [Creative Commons CC-BY 3](https://creativecommons.org/licenses/by/3.0/) license.
The basic layout of the user and management panels was copied from the [tab bar tutorial on w3schools.com](https://www.w3schools.com/howto/howto_js_tabs.asp).
The food that keeps me alive during all-weekend coding sessions is provided by [Wondrwmn](https://wondrwmn.deadtom.me).