assistant
v0.1.1
Published
A bot to assist with day-to-day operations
Downloads
12
Readme
Assistant
A bot to assist with day-to-day operations
This is a self-hosted bot service similar to Hubot (except it's not written in coffeescript!) that executes arbitrary commands to perform certain actions with a variety of adapters to allow it to run on any platform, simultaneously.
Why?
Hubot is great. The concept of knocking together a quick script to perform simple tasks, perfect! But Hubot is not. Ignoring the coffeescript source (because when did we start labelling a project as "bad" because of the source language?) it can't function across multiple adapters, and in order to get around this problem you are forced to run multiple Hubot processes per adapter. That's where Assistant comes in.
Installation
$ npm install --save assistant
The default installation doesn't come with any adapters but it does come with a selection of scripts to help you test your bot, and hey who doesn't love an automated service that replies to your "Hello" :wink:
Usage
Most of the configuration for the Assistant can be in your package.json
file, although you can specify additional
config files as you see fit. A typical package.json
file would look like:
{
"name": "Baymax",
"version": "0.1.0",
"description": "Your personal healthcare companion",
"private": true,
"scripts": {
"start": "assistant-server"
},
"dependencies": {
"assistant": "^0.1.0"
},
"assistant-adapters": {
"telegram": "assistant-adapter-telegram"
},
"assistant-config": {
"adapters": {
"telegram": {
"token": "1926482dcb7fac2585775a65a7b98611ed969af"
}
},
"http": {
"hostname": "0.0.0.0",
"port": 4000
}
}
}
And to boot the server you would use:
$ npm start
That just boots an empty bot. Now we can add some adapters and start plugging your bot into your services!
Adapters
To add adapters, install the relevant adapter and add it to your package.json
file under assistant-adapters
:
{
"assistant-adapters": {
"telegram": "assistant-adapter-telegram"
},
"assistant-config": {
"adapters": {
"telegram": {
"token": "1926482dcb7fac2585775a65a7b98611ed969af"
}
}
}
}
Configuration for adapters goes under assistant-config.adapters
, and the key should match the key in the
assistant-adapters
. Assistant doesn't come bundled with any adapters, so you need to install enough adapters to suit
each of your service. For now I've written two, one for Telegram
and one for a shell, although I plan to make one for various Slack
interactions very soon!
Known Adapters
If you're interested in writing your own services interaction, check out the Adapters wiki page.
Scripts
Now onto the cool stuff! Scripts are individual files that you use to give power to your bot! All you have to do is
register listeners to your assistant based on regular expressions (just like Hubot - if it isn't broken don't fix it).
To demonstrate, here's the hello.js
script
that's included with Assistant:
module.exports = function (assistant) {
var hellos = [
'Well hello there, NAME',
'Hey NAME, hello!',
'Whaddup NAME',
'Good day, NAME',
'How\'s it going, NAME',
'How can I help, NAME?'
];
var mornings = [
'Good morning, NAME!',
'Good morning to you too, NAME!',
'Good day, NAME',
'Good \'aye, NAME'
];
assistant.hear(/(^hello|good( [d'])?ay(e)?)/i, function (message) {
message.reply(message.random(hellos).replace('NAME', message.author.name));
});
assistant.hear(/(^(good )?m(a|o)rnin(g)?)/i, function (message) {
message.reply(message.random(mornings).replace('NAME', message.author.name));
});
};
This script demonstrates some of the features of the assistant:
- Attach functions to listeners based on regular expressions
- Functions take a single
(message)
argument for synchronous functions, and two arguments(message, callback)
for asynchronous functions. - Because regular expressions, there may be a chance your function will run with other listeners, so be wary :wink:
- For ease of variance, each
message
has arandom
function that will return a random element from an array of responses, so you can make your assistant sound more life-like!
Messages have the following properties:
{
name: 'The name of the Assistant, defaults to {name} from package.json',
identifier: 'An identifier for this bot, defaults to {name-version} from package.json',
environment: 'The Node-JS environment, in lowercase',
// The author object comes from the adapter, detailing who this person is
// At a minimum, an ID and a Name is present. More properties may be present depending on the adapter, but always
// have some defaults at the ready!
author: {
id: 'some-unique-id',
name: 'Some Relevant Name'
},
// A source object detailing the original request that hit the adapter
source: {
name: 'Telegram',
slug: 'telegram',
update_id: 1232942,
message: { '...': '...' }
},
// The raw message from the adapter
message: req.message.message,
// An array of matches returned from `regex.exec` so you can capture input for your script
matches: [ 'hello', 'hello', undefined, undefined, index: 0, input: 'hello' ],
// Adds each string argument to the immediate response
reply: function reply(string[, string[, ...]]) { },
// For delayed responses, you can call `adapter.send` directly (aliased as `message.send`)
send: function send(messages, callback) { }
}
Questions
- Questions? Awesome! Open an issue or feel free to tweet me and I'll get back to you!
- Who am I? If you really wanna know here's my website...