birchbot

An easy to use bot framrwork for owncast

env variables

| Variable | Default Value | |---------------------|---------------| | BIRCH_PORT | 8008 | | BIRCH_HOST | localhost | | BIRCH_CMD_DIR | commands | | BIRCH_HANDLER_DIR | handlers | | BIRCH_CMD_PREFIX | ! | | BIRCH_REMOTE | | | BIRCH_TOKEN | |

installation

docker compose (recommended)

Docker Compose is an easy way to orchestrate docker containers. There is an example compose file in this repo that you can adapt to you needs or use as is. The quickest way to get started is to clone this repo:

git clone https://codeberg.org/AnActualEmerald/birchbot.git

Then:

cd birchbot
docker-compose up

And BirchBot should be up an running! See the usage section below for ways to add commands and customize behavior.

manual

If you want you can also run BirchBot witout docker. The only prerequisite is that you have bun installed. Then clone the repo and run:

bun install --production

This will install any dependencies without all the types and stuff used for development. Then you can start the server with:

bun run src

usage

By default BirchBot doesn't do anything when it recieves a WebHook from owncast. Its job is to dispatch the WebHook payloads to user-defined handlers. There are two main ways to define behavior for BirchBot: chat commands and webhook handlers. The breakdown is like this:

| Event Type | Handler (.ts|.js|.cjs) | |------------------------|--------------------------| | CHAT | commands/* | | CHAT | handlers/chat | | NAME_CHANGED | handlers/nameChanged | | USER_JOINED | handlers/userJoined | | STREAM_STARTED | handlers/streamStart | | STREAM_STOPPED | handlers/streamStop | | STREAM_TITLE_UPDATED | handlers/streamTitle | | VISIBILITY-UPDATE | handlers/visibility |

Each file on the right should have a .ts, .js, or .cjs extension and must export a run function. That function should accept an argument that will be a Context<T> object, where the generic type is the value of Event Type in the table. The Context will contain the data from the webhook, as well as methods for sending API requests to the server.

chat commands

Handlers in the commands folder are treated somewhat differently. The name of the file will be the name of the command that it responds to. Command handlers also have a second argument passed to their run function which contains the rest of the text of the message in an array, split by spaces, excluding the name of the command itself. In order for an event to trigger a chat command the message must begin with the value of BIRCH_CMD_PREFIX, which defaults to !. The Context passed to a command handler also has some additional methods for replying to the user that invoked the command.

example handler

This is a very basic example that just logs out each chat message recieved

import type { Context } from "birchbot";
//handlers/chat.ts
export const run = async (ctx: Context<"CHAT">) => {
    console.log(ctx.event.user.displayName, "said", ctx.event.body, "at", ctx.event.timestamp);
}