Writing Hubot Plugins with CoffeeScript

The skys the limit with Hubot.

Let’s first install Node.js. Open a terminal window and type which node. If you get back a file system path, then you can skip this section. If you see node not found or something similar, then you’ll need to install it. Head over to the Node.js website and download (and install) the appropriate binary for your operating system. Unless you’ve recently installed Node, it’s probably a good idea to go ahead and install the most recent version. Newer versions of Node ship with NPM (or Node Package Manager) which we’ll use to install our software.

Next up we’ll need to install Hubot. Type npm install hubot -g into your terminal window and let NPM do it’s work. I prefer to install plugins like this globally, thus the -g flag.

Using Hubot Locally

After the installation completes, we’ll cd to the hubot install directory and run it for the first time. That directory can differ depending upon your paricular machine, but it is at /usr/local/lib/node_modules/hubot on my machine. Fire up hubot with the following command . bin/hubot. Then test it out with the command hubot ping. Hubot should immediately respond with PONG. Let’s take a quick look at that plugin before writing our own. It’s three lines of code are the guts of almost every other Hubot plugin. Here it is in all it’s glory:

module.exports = (robot) ->    robot.respond /ping$/i, (msg) ->        msg.send "ping"

When Hubot first starts up, it runs through every plugin in the scripts directory. Each plugin is written using the common module.exports Node pattern, which allows the plugin to identify itself to Hubot, and it also allows Hubot access to the plugin’s inner workings. Also found in a plugin are one or more respond function calls. Each of these calls correlates to a an event listener that waits to hear a specific keyword or pattern. Lastly, this plugin sends back a value using msg.send, returning any arbitrary msg you prefer.

By the way, if you’re curious (like I was) to see just what the robot, or msg, arguments contain, simply add a console.log statement anywhere in the code. For example, adding console.log(robot) immediately after the module.exports statements displays the following information:

{      name: 'Hubot',      commands: [],      version: '2.3.4',      server: {}      documentation: {},      listeners:      [            {                  robot: [Circular],                  regex: /^Hubot[:,]?\s*(?:PING$)/i,                  callback: [Function],                  matcher: [Function]            }      ],      [more stuff]}

Now you’re ready to start working on our first Hubot plugin.

Your First Hubot Plugin

Okay, enough already. I know you’re ready to write your own plugin, so lets do a quick one of our own. Create a new file within the scr/scripts directory of your Hubot install. Name it deepthoughts.coffee, open it in your editor of choice, and then input the following lines:

# Configures the pluginmodule.exports = (robot) ->    # waits for the string "hubot deep" to occur    robot.respond /deep/i, (msg) ->        # Configures the url of a remote server        msg.http('https://andymatthews.net/code/deepthoughts/get.cfm')            # and makes an http get call            .get() (error, response, body) ->                # passes back the complete reponse                msg.send body

You’re already familiar with the first two lines so we won’t review them. The third line begins the set up of an HTTP request; in this case, it’s a GET that sends no parameters to the remote site. The fourth line executes the HTTP request and sets up a callback function that receives any errors, the raw response, and the body of the returned page. In this case, the loaded page’s body doesn’t even have any HTML…it’s simply a string. This allows us to return it directly to the user by way of msg.send. Save that file, restart Hubot with a hubot die and a bin/hubot, and then get yourself a random deep thought with a hubot deep. Hopefully, it’s something profound, deeply thought provoking and not the one about the trampoline salesman or the golden skunk.

Your Hubot Homework

Now that you’ve written your first plugin, here’s the code for another one. See if you can figure out what it does and how to use it.

QS = require 'querystring'module.exports = (robot) ->    robot.respond /post (.+)/i, (msg) ->        url = 'https://httpbin.org/post'        data = QS.stringify({'hubot-post': msg.match[1]})        msg.http(url)            .post(data) (err, res, body) ->                msg.send body

• Notice the import happening at the top.
• What’s the respond method listening for?
• What is msg.match?
• See that the plugin can also do post requests?

Go Forth and do Likewise

As you can see from these few examples, writing Hubot plugins is a fairly straightforward task. Plugins can be useful or whimsical, but they’re fun to write and even more fun to use. What sort of plugin will you create for the world?

The one unfortunate thing about writing Hubot plugins is that the documentation isn’t super clear on some subjects, and you might sometimes spin your wheels trying to figure out what part belongs to what app if you’re unfamiliar with Node, CoffeeScript, or Hubot. But with a little perseverence, and this article, you’ll be on your way.

Share this article:  Tweet