assistant

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

• Telegram Adapter
• Shell Adapter

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 a random 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...