AchoBot is an open-source Twitch chatbot I built for myself. It allows you to manage your chatbot's commands using Notion:
It relies on the power of Notion Databases to manage command responses, permissions, and documentation.
Table of contents
The repo
Check the repo here 👇
Use Notion to configure your Twitch chatbot commands!
Features
Manage your Twitch Chatbot from Notion
Add, update or delete commands in a Notion database. AchoBot will use the information from Notion to answer your viewers when they invoke a command.
Assign Permissions to each Command
The database includes a Permissions
column where you can specify who can invoke each command. Leave it empty, and everyone will have access to it.
The column accepts one or more of the following values:
- Broadcaster
- Moderator
- Subscriber
- Viewer
Specific user permissions
You can also create commands that can only be invoked by a single specific user. To do that use the value usr:<username>
, for example: usr:paulasantamaria
Commands
…Features
Here's the complete list of features:
Manage your Twitch Chatbot from Notion
Add, update or delete commands in a Notion database. AchoBot will use the information from Notion to answer your viewers when they invoke a command.
Assign Permissions to each Command
The database includes a Permissions
column where you can specify who can invoke each command. Leave it empty, and everyone will have access to it.
Specific user permissions
You can also create commands that can only be invoked by a single specific user. To do that use the value usr:<username>
, for example: usr:paulasantamaria
Commands view
Navigate to /commands
to get a list of every public command. Your viewers can use it to see the available commands.
Also, you can navigate to /commands?mode=image
to get a ready-to-download image you can add to your Twitch panels.
Scripted commands
You can specify the type of command in the "Type" column. Available options are:
Text commands return a plain text response. E.g: "Welcome to the stream".
Scripted commands can implement some logic (JavaScript) and receive parameters.
For example, imagine the following command !say <text>
:
(context) => {
const textToPrint = context.params.text;
return `You said: ${textToPrint}`;
}
When a viewer invokes it: !say hello
Output: You said: hello
This feature is new and still has some limitations and issues. Writing code in a Notion DB cell is not ideal 😅.
Single account
The chatbot service will work only for the accounts and channels specified in the environment variables.
If any other account tries to log in using the chatbot authorization endpoints, it will get an authorization error.
The service is not currently designed to handle multiple accounts. This is a limitation, but it also makes the hosting and configuration of the service easier.
Status view
Use the status view to see if your bot's Twitch account is correctly authorized.
You can use this view in OBS to get real-time feedback on your chatbot status (it auto-updates every minute).
Built-in commands
Built-in commands are defined in the codebase instead of Notion. They usually require more logic and access to resources unavailable to the Notion commands. There are currently two built-in commands that you can use:
-
!help
prints a list of available commands. -
!refresh
invalidates the command cache, so next time a command is triggered, the app needs to go to Notion to retrieve the commands, thus updating them to the latest version. Only available for Broadcaster and Moderators.
Placeholder commands
Some commands are triggered via code but defined in Notion. This allows AchoBot to react to certain events (like a user logging in or subscribing) while also allowing each user to specify what they want AchoBot to do in each case.
Right now, the only placeholder command is:
-
!welcome
: Executed when AchoBot joins the chat room immediately after a stream starts. If you define this command in Notion when the bot logs in, it can say hi and leave some relevant information in the chat. E.g., "Hi, I'm AchoBot! Type !help to see what I can do".
Development
AchoBot runs on Node.js. It was developed with TypeScript and uses Nodemon to run the development server. It relies on tmi.js to connect and interact with Twitch's chat.
How it works
Once the service starts, AchoBot retrieves the commands from Notion (and other sources) and stores them in cache. When viewers execute a command, we search for it in the cache and execute it to generate a response:
Extensible
The project is designed to be easily extensible. It uses the command pattern to define the list of commands. You can extend this list using different strategies depending on what you aim to achieve. To know more: Extend AchoBot
Try it
Here's a detailed step-by-step guide on how to run AchoBot: AchoBot Setup - Full Guide
Stream
I developed this chatbot live on stream. Join me if you are interested in live coding sessions where I experiment with different tech stacks and build open-source software!
Right now, I'm working on a new portfolio with Svelte-kit, markdown, and TailwindCSS.
Top comments (5)
Nice work!
I have a bot as well, but I love the idea to use Notion as "commands database"!
Thank you!
Yes, it's super convenient to have your commands in Notion. I can just update everything I need before every stream without having to login anywhere. Can't wait to.keep adding more features to use on my streams!
how often do you update your bot commands? or do non-developers need to update those often?
Nice work
Thanks!