Claptrap is a rule-based bot engine for the Mattermost Chat platform. It allows you to define rules for various events and react upon them. Also, it is possible to implement custom responses to extend it with custom API integrations.
The following conditions and responses are supported:
Conditions:
- Text Starts With
- Text Equals
- Text Matches (RegEx)
- Random
- User Equals (User/Actor)
- User Is Role (User/Actor)
- Channel Equals
- Channel Is Type
Multiple conditions are supported, currently all conditions have to be met to trigger the responses (WIP)
Responses:
- Message (Public/DM)
- Invite
- Kick
- Delete Message
- Custom Callback Function
Currently Claptrap requires an system administrator account to execute delete/kick/invite actions. It is possible that Claptrap joins all public channels automatically on system startup, for private groups an invite is required. DM support is right now not given (unless direct chat with Claptrap itself).
The simplest way to get Claptrap up and running will be to download the binary releases from Github. After downloading the release for your platform, place it in a directory and create a config file for it (See Configuration). Afterwards you can start claptrap:
./claptrap -config_file=config.yaml
The process does not fork and logs to stdout in the current version.
The application is configured using a single YAML file with the following parameters:
general:
auto_join_all_channel: true [true/false]
case_dir: cases/ [directory path]
mattermost:
api_url: localhost:5000 [domain/ip:port]
username: [email protected] [email]
password: hunter2 [password]
team: nsf [mattermost team name]
There are various message types the bot can react on, currently implemented:
- message
- user_add
- user_removed
Rules for the message types are defined in JSON files in the case_dir, e.g. cases/message.json:
[{
"name": "Regexp Message",
"conditions": [
{"type": "text_matches", "condition": "^a[0-9]b$"}
],
"responses": [
{"action": "message_channel", "message": "Yes, Regexp works!"}
]
},
{
"name": "Debug",
"conditions": [
{"type": "text_equals", "condition": "!debug"}
],
"responses": [
{"action": "kick_user"},
{"action": "delete_message"}
]
}
]
TODO: Add Table for condition / response per message type supported and their parameters.
If you are interested in extending or supporting development of Claptrap, create a fork and download it to your local
Gopath. If you are interested in extending Claptrap with own callbacks for cases, you can modify cmd/claptrap/claptrap.go
and extend it with your own functions, e.g.:
func main() {
// ...
lmgtfyCase := rules.Case{
Name: "LMGTFY",
Conditions: []rules.Condition{
rules.TextStartsWithCondition{Condition:"!lmgtfy"},
},
ResponseFunc: lmgtfyCaseCallback,
}
botServer.AddCase("message", lmgtfyCase)
botServer.Start()
}
func lmgtfyCaseCallback(event provider.Event, p provider.Provider) bool {
mattermostHandler := p.(*provider.Mattermost)
message := strings.Replace(event.Text, "!lmgtfy ", "", 1)
message = "http://lmgtfy.com/?q=" + strings.Replace(message, " ", "+", -1)
mattermostHandler.MessagePublic(event.ChannelID, message)
return true
}
TODO: Add dependency management
The test suite is still work in progress, right now the only major parts that are tested in-depth are the test conditions. Tests can be invoked with:
go test ./...
When deploying Claptrap in a production environment, it is recommended to configure it as a system service. Claptrap can be running either on an independent machine or on the Mattermost host itself. An example configuration for systemd can be found here: claptrap.service
The service expects that the Claptrap binary is placed in /opt/claptrap/claptrap and a dedicated claptrap user will
be created.
- Daniel Schalla
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE.md file for details