A Twitch bot: commands, polls, giveaways and more
Python
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Firebot

Overview

Firebot is a command-line utility that connects to a Twitch.tv channel and acts as an IRC client, receiving chat messages and also being able to send them. But Firebot is much more than a normal IRC client, Firebot has customizable commands, giveaway and poll support, and many more features.


Features

  • Receive and send chat messages
  • Basic commands
  • Custom commands
  • Giveaways and polls support
  • Caps protection
  • Fully configurable

Dependencies

To run Firebot you will need Python 2.7.


Usage

By default Firebot will connect to the channel specified in the config file. If you want to quickly connect to another channel you can specify the channel when launching Firebot.

python firebot.py [channel]

Config

Firebot will use the options values in the config file if no other values are specified when launching Firebot.

General options

Option Type Description
bot_user string Username of the account with which Firebot will connect to the channel.
bot_password string The password should be an OAuth token. You can get your OAuth token here.
channel string The channel Firebot will connect to.
commands boolean If set to true Firebot will process user commands as specified in the file commands.
If set to false Firebot will not process user commands.
log_chat boolean If set to true Firebot will log all chat messages to a file called channel-yyyy-mm-dd-hh-mm-ss.log in the logs folder.
If set to false Firebot will not log any messages.

Caps protection options

Option Type Description
enabled boolean If set to true Firebot will monitor the chat for excessive caps.
If set to false Firebot will not monitor the chat for excessive caps.
min_length integer Minimum number of characters in a message for Firebot to check caps.
lower_limit integer Lower limit to which the maximum percentage of caps will be bound.
upper_limit integer Upper limit to which the maximum percentage of caps will be bound.
warn boolean If set to true Firebot will send a warning message when excessive caps are used.
If set to false Firebot will not send a warning message when excessive caps are used.
warning string Warning message Firebot will send if warn is set to true.
timeout boolean If set to true Firebot will timeout users who use excessive caps.
If set to false Firebot will not timeout users who use excessive caps.
timeout_time integer Duration of the timeout in seconds.

Polls options

Option Type Description
enabled boolean If set to true Firebot will respond to poll commands.
If set to false Firebot will not respond to poll commands.
start string Message Firebot will send when a poll is started.
You can use the variable $options$ to display the poll options.
start_error string Message Firebot will send when trying to start a poll while a poll is already running.
end string Message Firebot will send when a poll is ended.
You can use the variable $options$ to display the poll options.
restart string Message Firebot will send when a poll is restarted.
You can use the variable $options$ to display the poll options.
stats string Message Firebot will send when the poll stats are requested.
You can use the variable $options$ to display the poll options.

Giveaways options

Option Type Description
enabled boolean If set to true Firebot will respond to giveaway commands.
If set to false Firebot will not respond to giveaway commands.
start string Message Firebot will send when a giveaway is started.
You can use the variable $keyword$ to display the giveaway keyword.
start_error string Message Firebot will send when trying to start a giveaway while a giveaway is already running.
end string Message Firebot will send when a giveaway is ended.
restart string Message Firebot will send when a giveaway is restarted.
You can use the variable $keyword$ to display the giveaway keyword.
stats string Message Firebot will send when the giveaway stats are requested.
You can use the variable $n$ to display the number of persons in the giveaway.
draw string Message Firebot will send when a giveaway winner is requested.
You can use the variable $winner$ to display the giveaway winner's username.

Commands

All commands must have all their options specified to prevents errors.

Options

Commands options are defined in the commands file in JSON format.

Option Type Description
enabled boolean If set to true Firebot will process this command.
If set to false Firebot will not process this command.
This option is only used in the basic commands.
mod boolean If set to true Firebot will not process from users who aren't moderatos.
If set to false Firebot will process from users who aren't moderators.
subscriber boolean If set to true Firebot will not process from users who aren't subscribers.
If set to false Firebot will process from users who aren't subscribers.
owner boolean If set to true Firebot will not process from users who aren't the owner of the channel.
If set to false Firebot will process from the owner of the channel.
respond boolean If set to true Firebot will respond to this command.
If set to false Firebot will not respond to this command.
This option can't be used in the custom commands.
response string Message Firebot will respond to this command.
Variables can be used.

Basic commands

Command Description
!timeout [user] [time] Timeouts [user] for [time]. If [time] isn't set the the time specified in the commands file will be used.
!ban [user] Bans [user].
!unban [user] Unbans [user].
!silence [on/off] If set to on Firebot will be silenced.
If set to off Firebot will not be silenced.

Custom commands

Custom commands are defined in the commands file in JSON format.

Example

"!firebot": {
	"mod":        false,
	"subscriber": false,
	"owner":      false,
	"response":   "To find more about Firebot visit http://github.com/PacoHobi/Twitch-Firebot"
}

Poll commands

Command Description
`!poll start option1 option2
!poll end Ends the current poll.
!poll restart Restarts the votes of the current poll.
!poll stats Firebot will respond with the current poll results.
!vote [OptionNumber] Votes for the [OptionValue] option of the current poll.

Giveaway commands

Command Description
!giveaway start [keyword] Starts a giveaway with the keyword [keyword].
!giveaway end Ends the current giveaway.
!giveaway restart Restarts the current giveaway.
!giveaway stats Firebot will respond with the current number of people who have entered the giveaway.
!giveaway draw Firebot will respond with a giveaway winner.
!enter [keyword] Enters the current giveaway if the correct keyword is given.

Variables

This variables can be used in any custom command response and will be replaced by the apropiate value.

Variable Value
$user$ Username of the user who sent the command.
$target$ Username of the target of certain commands. Can only be used on the !timeout, !ban and !unban commands.
$time$ Current time of the machine where Firebot is running, with format hh:mm:ss AM/PM.