Home

Awesome

<img src="https://raw.githubusercontent.com/digitalocean/heartbot/master/heartbot.png" height="36" width="36"> Heartbot

Heartbot is a Hubot integration that can be plugged into Slack, Hipchat, IRC, or other chat clients. Once installed, type things like "ugh", ":(", or "kitty me" and Heartbot will bring a little love and joy into the room. Spread the love on Twitter with #heartbot

Getting Started

First, you need to have NodeJS installed on your server:

Then, you will want to install Hubot. Start by installing the yo and generator-hubot packages globally:

sudo npm install -g yo generator-hubot

Generate a Hubot instance:

mkdir heartbot
cd heartbot
yo hubot

You will be prompted for to choose a chat adapter. A list of chat adapters can be found here. For example, to install the Slack chat adapter, run the following command:

npm install hubot-slack --save

Then, create a Hubot service and copy the API token.

Next, install heartbot. While still in the heartbot directory, run:

npm install hubot-heartbot --save
cp node_modules/hubot-heartbot/config.yml heartbot.config.yml

To enable the Heartbot Hubot plugin, add hubot-heartbot to external-scripts.json:

...
  "hubot-youtube",
  "hubot-heartbot"
]

Sign up for forecast.io and copy your API key.

Finally, start Heartbot:

HUBOT_SLACK_TOKEN=slack-token-here HEARTBOT_FORECAST_API_KEY=forecast.io-api-token-here ./bin/hubot -a slack

Configuring Interactions

Heartbot comes with a number of interactions pre-configured. Heartbot's configuration file, heartbot.config.yml, can be found in your Hubot instance's root directory.

---
probability: 0.6
interactions:
    - pattern:
        ...

    - pattern:
        ...

The two main keys in the configuration file are:

probability

A number between 0-1 that specifies the probability of Heartbot responding to a trigger. Setting it to 0 disables all interaction, while setting it to 1 makes Heartbot respond to all interactions at all times. Setting it to .5 would ensure that Heartbot would respond half the time to interactions.

This is done so that Heartbot does not get overly annoying in busy channels/rooms.

In addition, a single interaction's probability can be modified independently of the global probability setting. You can do that by passing a probability key to the interaction.

interactions

A list of interactions that Heartbot should respond to.

An interaction should be written in the following format:

- pattern:
    regex: >-
      ((what|who)('?s| is) |\?)##heartbot##
  event: say
  message: I'm Heartbot, a Hubot integration that is here to bring a little love and joy into the room.
  probability: 1

pattern

The pattern object should include a regex key and, optionally, an options key, which describe the RegEx pattern that should be match in order to trigger the interaction.

message

The text that the interaction should respond with. This is usually a string, but can be an array of strings out of which a random message is picked depending on whether or not the event supports that, which the three events that Heartbot comes with (in the events directory) do.

There are a number of variables that can be used:

event

The name of the event that should be called once the interaction is triggered. Heartbot ships with three events (see the events directory):

say

Simply a message that Heartbot should respond with. Other than the variables described above, no additional processing is done.

The say event can accept an optional option:

forecast

Fetch the temperature in a specific location and respond with the message. Two additional keys are required:

In addition to these two keys, a forecast.io API key is required. You can pass the API key in an environment variable called HEARTBOT_FORECAST_API_KEY.

The forecast event supplies two variables to the message:

For example, to fetch the temperature in Oymyakon, Russia:

- pattern:
    ...
  event: forecast
  message: It could be worse. It’s currently $temperature° $units in Oymyakon, Russia
  location:
    latitude: 63.460833
    longitude: 142.785833
  units: C
giphy

Search Giphy for a random gif based on a specific search query.

The giphy event expects two options:

If you are using Heartbot in production, you should pass an API key as the public API key that is used by default is subject to rate limiting and is intended only for development usage.

Please see Giphy API Documentation > Access and API Keys. The API key can be passed using the environment variable HEARTBOT_GIPHY_API_KEY.

- pattern:
    regex: ^puppy me$
  event: giphy
  tag: cute puppy
  message: Here's a puppy: $gif

probability

A single interaction's probability can be overridden to make it different from the global probability value. Simply pass a probability key with the new probability value:

- pattern:
    regex: ^puppy me$
  event: giphy
  tag: cute puppy
  message: Here's a puppy: $gif
  probability: 1

Extending Heartbot

It is possible to write and use custom events. Events are written in CoffeeScript and should export a class with a method called process. The rest is entirely up to you.

The constructor is passed the interaction object from the configuration file.

The process method is called with one argument: msg, an instance of Hubot's Response class. Please see Hubot's official documentation on it.

A few helper functions are included in lib/common.coffee:

applyVariable = (string, variable, value, regexFlags = 'i')

For example:

string = 'Hello, $user!'

applyVariable string, 'user', 'Jane'
# 'Hello, Jane!'

msgVariables = (message, msg)

This function provides a few variables from msg to message.

stringElseRandomKey = (variable)

If variable is a string, it is simply returned back. However, if it is an array, a random item is returned.

regexEscape = (string)

Escape string so that it can safely be used in a RegEx pattern.