MapleBot
MapleBot is a simple XMPP bot built with nodejs. Its built using a number of configurable tasks. Each task binds a set of commands to the bot. When the bot encounters a command it knows. The connected function is run. MapleBot makes a great bot to use on company jabber networks, and can easily be trained to do things like send reminders or get the weather.
Dependencies
You can install all of Maplebot's dependencies using npm
.
npm install .
This will install all the dependencies. You can make sure things worked by running the tests:
npm test
Configuration
Included in the source is a sample configuration file, fill out the configuration values to get MapleBot running. Some of the most important configuration options are:
username
The login name MapleBot should use when joining the jabber service.password
The password to use.room
The room you want the bot to join.nick
The nickname the bot should use.tasks
The tasks the bot should bind.
Creating Tasks
Tasks in MapleBot are where you build the commands and features you want
MapleBot to have. Each task binds a number of commands to the bot.
When the bot receives a message in the group chat that starts with the
command value, it dispatches the remainder of the message to the bound
function. There is a built in task base to help facilitate building
tasks. Each task is expected to have a bindCommands
method that
accepts an object that commands are inserted into. See the provided
QueueManager or Weather tasks for how to build a simple task.
Configuring tasks
When defining tasks in your configuration file you can also pass in any additional configuration data for those tasks.
// in config.json
module.exports = {
tasks: {
'CodeReview': {
module: './code-review',
autoPairTime: '10:30:00'
}
}
};
When using an object for a task definition, you must include the
module
key. It has to point at the file containing the task you want
to use. All other keys + values will be passed to the tasks's
constructor as the second parameter. The first is the bot
the task
is bound to.
Creating responses
Responses can be created in a few different formats, each with different features:
- Plain text These are directly output to the group chat.
- Objects Simple object responses allow you to respond with both a subject and a body, and other properties. Useful for bot tasks that need to set the topic.
- Promises There is a simple built-in promise object in the task module. Promises are ideal for tasks that require additional asynchronous work to be done. By resolving the promise, the response will be delivered.
A response using a promise would look like:
var task = require('./lib/task');
function doSomething() {
var promise = new task.Promise();
doSomethingAsync(promise);
return promise;
}
An object response could look like:
var response = {
body: 'I am message text',
subject: 'I will be set as the group chat topic in most clients.'
};
You can use object responses with both synchronous responses, as well as
promises. When using object responses you can direct the message to
specific rooms for multi-room bots, by setting the room
property. The
room property lets you reply directly to people from a groupchat room. You
can also change set the type
key to specify whether or not you want to
send a 'direct' or 'groupchat' type of message.
Built in Tasks
There are a few built-in tasks, that do a few things I need on a day to day basis:
- QueueManager - manages queues of things to do.
- Weather - Query google's weather api to get local forecasts.
- Help - Display help text about all the other tasks. Called with
!help
- CodeReview - Helps do random pair ups for daily code reviews.
Running MapleBot
After setting up the configuration file, you can start the bot using
node bot.js
Calling commands
You call bot commands by sending the group chat a message starting with
one of the bound command keywords. For example, if you were using the
Weather
task, you could send:
!weather toronto,ontario
to the group chat. This will cause MapleBot to query the google weather api and reply with the result. Whenever a task command is called, it will be supplied one argument, a request. This request contains a number of properties that you can use:
room
The room the message came from.from
The person who sent the message.body
The message body text.type
Whether the the message was a direct or groupchat message.
The requests can also be treated as a string, and appended into other text. If a response doesn't contain a room the request's room will be used.