Redseligg
Description
This is Redseligg, an extensible Chat Bot for various platforms. It is based on a server architecture which can be controlled via a REST API.
These platforms are current supported (at least with the functionality to send and receive messages):
Discord
Matrix
Mattermost
Slack
Twitch
Releases
For releases binaries for Linux, Windows and Mac are provided. Check out the respective section on GitHub.
How to build from source
Requirements
Building
Clone the sources from the repository and compile it with
make deps
make
and optionally
make test
to run tests.
How to run it
Independent of the way you obtain it, you have to configure the bot first and it is necessary to have a registered bot account for the service you want to use.
- Discord: Please take a look at https://discordapp.com/developers/docs/intro on how to set up a bot user and generate the required authentication token. Then use the bot OAuth2 authorization link, which can be generated on your applications page at OAuth2 when you select as scope "Bot". Note: This authentication flow is much easier than the normal OAuth2 user challenge and does not require a callback link. For details on that visit https://discordapp.com/developers/docs/topics/oauth2#bot-authorization-flow.
- Matrix: For Matrix it is simpler, just create a user for the bot on your preferred Matrix server.
- Mattermost: For Mattermost a username and password with the necessary rights on the specified server is enough.
- Slack: The bot as to be added to the workspace and a token has to be generated.
- Twitch: It needs a username for the Twitch account and a list of channels to join. In addition a token is needed for that user. You can generate one here: https://twitchapps.com/tmi/
The bot configuration can either be stored in a toml file or in a MongoDB. An example for a toml file is provided in this repository in cfg/bots.toml.
Self-built or downloaded release
To start the Redseligg BotterInstance using the self-built or downloaded binary enter for use with a TOML config
BOTTER_BOT_CFG_SOURCE="TOML" BOTTER_BOT_CFG_TOML_FILE=/path/to/config/file.toml ./botterinstance
or
BOTTER_BOT_CFG_SOURCE="MONGO" BOTTER_BOT_CFG_MONGO_URL="mongodb://user:password@localhost/database" BOTTER_BOT_CFG_MONGO_DB="database" ./botterinstance
for use with a MongoDB for the Bot configuration.
Using Docker
Probably an easiest way to try out Redseligg is using Docker. To pull the latest version from DockerHub and start it type
docker run -d --name redseligg --env BOTTER_BOT_CFG_SOURCE=TOML --env BOTTER_BOT_CFG_TOML_FILE=/bots.toml -v /path/to/config/file.toml:/bots.toml:ro torlenor/redseligg:latest
or for MongoDB type
docker run -d --name redseligg BOTTER_BOT_CFG_SOURCE="MONGO" BOTTER_BOT_CFG_MONGO_URL="mongodb://user:password@localhost/database" BOTTER_BOT_CFG_MONGO_DB="database" torlenor/redseligg:latest
How to control it
We are providing a command line tool to control a BotterInstance called BotterControl.
Get all running bots of a BotterInstance
./bottercontrol -u URL_OF_BOTTER_INSTANCE -c GetBots
or
docker run --net host torlenor/redseligg:latest /usr/bin/bottercontrol -u URL_OF_BOTTER_INSTANCE -c GetBots
Start a bot on a BotterInstance
./bottercontrol -u URL_OF_BOTTER_INSTANCE -c StartBot -a BOTID
or
docker run --net host torlenor/redseligg:latest /usr/bin/bottercontrol -u URL_OF_BOTTER_INSTANCE -c StartBot -a BOTID
Stop a bot on a BotterInstance
./bottercontrol -u URL_OF_BOTTER_INSTANCE -c StopBot -a BOTID
or
docker run --net host torlenor/redseligg:latest /usr/bin/bottercontrol -u URL_OF_BOTTER_INSTANCE -c StopBot -a BOTID
Standalone version
We also provide a standalone version which does not depend on a control instance to launch bots, but just starts all enabled bots from the configuration.
You launch the standalone version type
BOTTER_BOT_CFG_SOURCE="TOML" BOTTER_BOT_CFG_TOML_FILE=/path/to/config/file.toml ./botter
or
BOTTER_BOT_CFG_SOURCE="MONGO" BOTTER_BOT_CFG_MONGO_URL="mongodb://user:password@localhost/database" BOTTER_BOT_CFG_MONGO_DB="database" ./botter
for use with a MongoDB for the Bot configuration.
Using Docker
To launch the standalone version using Docker type
docker run -d --name redseligg --env BOTTER_BOT_CFG_SOURCE=TOML --env BOTTER_BOT_CFG_TOML_FILE=/bots.toml -v /path/to/config/file.toml:/bots.toml:ro torlenor/redseligg:latest /usr/bin/botter
or for MongoDB type
docker run -d --name redseligg BOTTER_BOT_CFG_SOURCE="MONGO" BOTTER_BOT_CFG_MONGO_URL="mongodb://user:password@localhost/database" BOTTER_BOT_CFG_MONGO_DB="database" torlenor/redseligg:latest /usr/bin/botter
Storage
Some plugins can use a storage to store permanent data. Currently we are supporting MongoDB and SQLite3 as a storage backend.
MongoDB
To configure a MongoDB storage, add a section of the form
[bots.slack.storage]
storage = "mongo"
[bots.slack.storage.config]
URL = "mongodb://user1:test@localhost/testdb" # URL to connect to
Database = "testdb" # Database to use
to the bot for which you want to enable the storage (in the example above for a bot called 'slack'). The plugins for this bot will automatically use that storage.
SQLite3
To configure a SQLite3 storage, add a section of the form
[bots.slack.storage]
storage = "sqlite"
[bots.slack.storage.config]
Database = "/tmp/database.db" # Database file to use
to the bot for which you want to enable the storage (in the example above for a bot called 'slack'). The plugins for this bot will automatically use that storage.
Note: This is only supported in the pre-built binaries for Linux. Feel free to build it yourself if you want that support.
Custom call prefix
It is possible to specify a custom call prefix for the commands by adding a section
[bots.slack.general]
callprefix = "~"
to the bot for which you want to change it. The default is "!".
Plugins
Plugins are used to implement actual functionality of Redseligg. They serve as handlers of received messages and can send messages over the Bot to the platform.
In the future it is planed to support external Plugins via gRPC.
Currently these Plugins are part of Redseligg:
Name |
Type |
Description |
Archive |
archive |
The Archive plugin stores all messages with their timestamps in the storage. |
Custom Commands |
customcommands |
Allows to add custom commands which will return text. |
Echo |
echo |
The Echo plugin echos back all messages it received to the sender of the message. |
Giveaway |
giveaway |
The Giveaway plugin lets you hold giveaways in your channel and let the bot pick a winner. |
HTTPPing |
httpping |
The HTTPPing plugin will try to contact a web server and reports back the request duration or an error if the URL was not reachable. |
Quotes |
quotes |
Lets users/viewers or mods add quotes and randomly fetch one. |
Roll |
roll |
Sends back a random number in a custom range. |
RSS |
rss |
Subscribe to RSS feeds. |
Timed Messages |
timedmessages |
Posts messages automatically at a given interval. |
Version |
version |
Returns the version of redseligg. |
Vote |
vote |
Initiate a vote in the channel about arbitrary topics. |
The type column is the string that you have to use as "type" in the configuration for that particular plugin to activate/add it to the bot.
Example:
[bots.some_bot.plugins.1]
type = "echo"
Below you find the configuration options and detailed descriptions for the various plugins.
Archive
The Archive plugin stores all messages with their timestamps in the storage.
CustomCommands
Allow mods to add custom commands which will return text.
Configuration options
Example:
[bots.some_bot.plugins.1]
type = "customcommands"
[bots.some_bot.plugins.1.config]
mods = ["user"]
onlymods = true
When onlymods
is set to true
, only the users which are listed in mods
are allowed to add or removed custom commands. Per default everybody is allowed.
Adding a custom command
To add a custom command type
!customcommand add <customCommand> <your message>
Example:
!customcommand add hello Hi there!
When a user then types !hello
in chat the plugin will answer with Hi there!
.
Removing a custom command
Use
!customcommand remove <customCommand>
, e.g., !tm remove hello
, to remove the custom command.
Echo
The Echo plugin echos back all messages it received to the sender of the message. It listens to messages which start with !echo
followed by text.
Configuration Options
- onlywhispers: When set to true the EchoPlugin only echos in whispers (when supported by the used Bot)
Giveaway
Lets you hold giveaways in your channel and let the bot pick a winner.
Configuration options
Example:
[bots.some_bot.plugins.1]
type = "giveaway"
[bots.some_bot.plugins.1.config]
mods = ["user"]
onlymods = true
When onlymods
is set to true
, only the users which are listed in mods
are allowed to start/end giveaways. Per default everybody is allowed.
Starting a giveaway
To start a giveaway in the current channel type
!giveaway start <time> <secretword> [winners] [prize]
<time>
is the time the giveaway should run. It should include s/m/h to indicate seconds/minutes/hours.
<secretword>
is the word the bot should react for the people to participate.
[winners]
is the number of winners to pick in the end.
[prize]
is the prize the people can win.
Example:
!giveaway start 1m hello 2 Bananas
Ending a giveaway
To stop a currently running giveaway type !giveaway end
.
Rerolling the winner
Type !giveaway reroll
to pick a new winner from the last ended giveaway.
HTTPPing
The HTTPPing plugin listens to messages starting with !httpping
followed by an URL. If the URL is valid it will try to contact the server and reports back the request duration or an error if the URL was not reachable.
Quotes
Lets users/viewers or mods add quotes and randomly fetch one.
Configuration options
Example:
[bots.some_bot.plugins.1]
type = "quotes"
[bots.some_bot.plugins.1.config]
mods = ["user"]
onlymods = true
When onlymods
is set to true
, only the users which are listed in mods
are allowed to perform certain actions. Per default everybody is allowed.
Adding a quote
To add a quote type
!quote add <your quote>
Example:
!quote add This is awesome!
Getting a quote
!quote
will return a random quote.
!quote 2
will return the 2nd quote in the list.
The output will be similar to
123. "This is awesome!" - 2020-4-22, added by Somebody
Removing a quote
Use
!quote remove ID
to remove a quote.
Example:
!quote remove 123
Note: When onlymods
is set to true
in configuration, only mods are allowed to list all quotes.
Roll
This is a classic "Roll/Random" plugin which sends back a random number in the range [0,100] when it receives the !roll
command. When it receives !roll {PositiveNumber}
instead, it returns a random number in the range [0, {PositiveNumber}].
Subscribe to RSS feeds.
Note: Because of a much needed refactoring of the MongoDB storage backend, this plugin currently only works with SQLite as storage backend.
Configuration options
Example:
[bots.some_bot.plugins.1]
type = "rss"
[bots.some_bot.plugins.1.config]
mods = ["user"]
onlymods = true
When onlymods
is set to true
, only the users which are listed in mods
are allowed to perform certain actions. Per default everybody is allowed.
Adding a subscription
To add a RSS subscription for the current channel type
!rss add <link>
Example:
!rss add http://some.link/news.xml
Getting a list of all subscriptions
!rss list
Removing a subscription
Use
!rss remove <link>
to remove a quote.
Example:
!rss remove http://some.link/news.xml
Note: When onlymods
is set to true
in configuration, only mods are allowed to list all quotes.
Timed Messages
Posts messages automatically at a given interval.
Configuration options
Example:
[bots.some_bot.plugins.1]
type = "timedmessages"
[bots.some_bot.plugins.1.config]
mods = ["user"]
onlymods = true
When onlymods
is set to true
, only the users which are listed in mods
are allowed to add or removed timed messages. Per default everybody is allowed.
Adding a timed message
To add a timed message type
!tm add <interval> <your message>
Example:
!tm add 1m This is awesome!
Removing a timed message
Use
!tm remove <interval> <your message>
, e.g., !tm remove 1m This is awesome!
, to remove one message with a specific interval and text.
or use
!tm remove all <your message>
, e.g., !tm remove all This is awesome!
, to remove all message with a specific text, regardless of their interval.
Version
The Version plugin answers to !version
with the version of the bot.
Vote
Initiate a vote in the channel about arbitrary topics.
Configuration options
Example:
[bots.some_bot.plugins.1]
type = "vote"
[bots.some_bot.plugins.1.config]
mods = ["user"]
onlymods = true
When onlymods
is set to true
, only the users which are listed in mods
are allowed to start/end votes. Per default everybody is allowed.
Starting a vote
Type !vote message
to start the vote. The vote is limited to the channel where you initiate the vote. Per default the options are Yes/No. They can be changed by providing custom options (see below).
How to participate in the vote
React with the emoji assigned to the options you want to vote for.
Custom voting options
Provide the custom options in square brackets after the message, e.g.,
!vote What is the best color? [Red, Green, Blue]
Ending a vote
Type !vote end message
to end a vote. No additional choices will be counted. For example to end the vote started above type
!vote end What is the best color?
Deleting a vote
Just delete the vote message.