AutonomousKoi - Banter

The banter module adds custom commands and periodic messages to Twitch chat. The twitch module must be started and connected to chat for this module to work.

Custom Commands

Custom chat commands provide a simple way for chatters to get information on demand. Custom commands in banter have a command that users type in chat and text that the bot will respond with. Commands in banter must have a ! prefix.

For example, you might define a command !website with the text I have a website at https://autonomouskoi.org/!. When a user in the chat types !website, the bot will respond with I have a website at https://autonomouskoi.org/!.

Custom commands can be individually enabled and disabled. This provides a way to make different content available, depending on the type of stream.

Users can list the available commands by typing !banter.

Random Commands

Each command can also be set as random. At a configurable interval (e.g. every five minutes), banter will randomly select a custom command that is both enabled and set as random and send it to the channel.

Random commands have a cooldown period. To avoid repeating a command too frequently, a command that's been used recently will not be eligible to be randomly sent for that cooldown period (e.g. 15 minutes). If all commands are on cooldown when banter attempts to send a random command nonne will be sent. Commands on cooldown can still be activated by users.

The banter module provides one link for configuration.

Configuration

Random Commands

The first configuration section allows you to configure general random command settings. Random Comman Interval specifies how many seconds banter should wait between random commands. The minimum is 30 seconds. Setting this to be too frequent will annoy chatters.

Random Command Cooldown specifies how long, in seconds, banter should wait before a recently selected command is eligible to be sent again. If this value is lower than Random Command Interval there is effectively no cooldown.

Changes to either of these settings are saved when and take effect when you click out of the input box.

Messages

The second configuration section allows you to manage your commands. To create a new command, click the + button in the bottom left. A new empty row will appear.

Command

The command users will type into chat to get this message. It must begin with ! and must be a single word.

Text

The text sent to the chat when the command is activated by a user or as a random command.

Enabled

If not enabled, this command can't be invoked by users, won't be selected as a random command, and won't appear in the command list reported by !banter.

Random

If checked, this command can be randomly selected and sent to the channel.

Changes to a command are not saved automatically; you must hit Save.

Message Processing

When a command is triggered by a user in chat the text will go through processing before being sent to chat. The text can include special values that will be replaced with something based on context.

The placeholders begin and end with double curly braces: ({{ placholder }}). One placeholder is .PostCommand, representing all the text that came after the !command. For example, say you created a command !said with the text You said "{{ .PostCommand }}". That's cool!. If a user entered !said this is an apple, banter would send to the channel You said "this is an apple". That's cool!

The .Sender placeholder has data about the user who ran the command. You can access specific pieces of data about the user, for example: {{ .Sender.DisplayName }} will be replaced by sender's display name. The available details are:

Login

The login of the sender

DisplayName

The display name of the sender

BroadcasterType

affiliate for an affiliate, partner for a partner, and nothing for neither

Description

The user’s description of their channel.

For example, give a command !bonk with the text {{ .Sender.DisplayName }} bonks {{ .PostCommand }} and the user AutonomousKoi enters !bonk @SelfDrivingCarp, banter will send to the channel AutonomousKoi bonks @SelfDrivingCarp.

The .Original placeholder has details about the original message the user sent. It has details like .Sender. The available details are:

Text

The complete text the user sent to the channel.

IsMod

Whether or not the sender is a channel mod.

It's possible to create invalid placeholders. If you save an invalid message banter will save it but it won't appear in chat. When an invalid command is run an error with details will be written to the logs.

Under the hood banter is using Go's text/template for text processing. All of that package's functionality is available if you're adventerous. There's no limit to the length of the text banter will save for a command but there is a limit to the length of a valid chat message. The full details of the data available to the template are in the source for Sender (a User struct) and Original (a TwitchChatEventMessageIn struct).