twason/README.md

Twason is an opinionated Twitch chatbot created with the KISS principle in mind. It is based on the IRC protocol and is configurable in just one JSON file.

What the hell is that name!?

Twason is a portmanteau based on two words: Twitch (the platform the bot is designed for) and Jason (as the JSON file that you use to wonfigure it).

What features does it provide?

Currently, Twason has the following features:

• Commands: automatically answer to messages that start with a given command
  • Customizable commands prefix (useful if you’re using multiple bots)
  • Mention the user who invoked the command in the answer
  • Help command auto-generation
• Timer: automatically send pre-defined messages
  • Only one timer to keep the bot from spamming in the chat
  • Configurable time and number of messages between each automatic message
  • Two strategies available:
    • round-robin: send the messages in the same order they have been set in the configuration file
    • shuffle: send the messages in a random order

More features will be available in the future.

How do I use it?

Twason is currently in development and may contain bugs, but it is globally usable. Actually, I’m using it on my Twitch channel. The simplest (and safest) way to use it is to use the Docker image: deuchnord/twason. A Docker-Compose file is also available for facility.

About the Twitch token

To enable the bot to connect to Twitch chat, you will need to generate a token. Head to the Twitch Chat OAuth Password Generator and follow the instructions to generate it. Then, you will need to give it to the bot through the TWITCH_TOKEN environment variable.

The JSON configuration file

To configure the bot, you will need to create a JSON file in config/config.json as defined in the docker-compose.yml file. You can find a minimal configuration in the config.json.dist file in this repository. You can have an interface to create and validate your config file .

Below is the complete configuration reference:

{
  "nickname": "yourbot",                        // the Twitch name of your bot
  "channel": "yourchannel",                     // the channel the bot must follow
  "command_prefix": "!",                        // the prefix the commands will have (defaults to '!')
  "help": true,                                 // if true, a help command will be automatically generated (defaults to true)
  "commands": [                                 // a list of commands that your bot will recognize and respond to (empty by default)
    {
      "name": "ping",                           // the command name - spaces are not recommended here (even though they are technically accepted)
      "aliases": ["pong"],
      "message": "Pong @{author} Kappa"         // the message the bot must send when someone invokes this command ('{author}' will be replaced with the user who invoked the command)
    }
  ],
  "timer": {                                    // the configuration of the automatically sent messages
    "between": {
      "time": 10,                               // the minimum time that must have passed between two messages (defaults to 10)
      "messages": 10                            // the minimum number of messages that the chat members must have sent between two messages (defaults to 10)
    },
    "strategy": "round-robin",                  // the strategy used to send the messages: "round-robin" or "shuffle" (defaults to "round-robin")
                                                // the messages are actually commands with the same options as above
    "pool": [                                   // a list of commands to send (empty by default)
      {
        "name": "hello",
        "aliases": ["hi"],
        "message": "Hello World! HeyGuys"
      }
    ]
  }
}