Skip to content

Latest commit

 

History

History
556 lines (368 loc) · 15.1 KB

README.md

File metadata and controls

556 lines (368 loc) · 15.1 KB
Raw

Redseligg

Build and Test Coverage Status Go Report Card Docker License

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.

Supported platforms

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

  • Go >= 1.12

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}].

RSS

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.