Botmetrics

Botmetrics is a service that lets you collect & analyze metrics from your bots (Slack, Facebook, Kik, Telegram and more).

This Node.JS client lets you register your bot with Botmetrics and starts metrics collection.

Installation

To install this as part of your Node.JS project, add this to your dependencies in your application's package.json:

botmetrics

or run

$ npm install --save botmetrics

Setting your API Host (for Self-Hosting)

If you are using your own self-hosted version of Botmetrics, remember to set the BOTMETRICS_API_HOST environment variable to your host (If you have hosted your Botmetrics instance at https://my-botmetrics-instance.herokuapp.com, set BOTMETRICS_API_HOST to https://my-botmetrics-instance.herokuapp.com.

Usage (Facebook)

Register your Facebook bot with Botmetrics. Once you have done so, navigate to "Bot Settings" and find out your Bot ID and API Key.

Set the following environment variables with the Bot ID and API Key respectively.

BOTMETRICS_BOT_ID=your-bot-id
BOTMETRICS_API_KEY=your-api-key

track

Call the track API in the webhook receiver that handles all of your Facebook messenger callbacks.

BotMetrics.track(req.body);

If you are using an Express app, this is what it would look like:

// Remember to run `npm install --save botmetrics` in your app.
//
// If you are using an Express-based app, parse the request body
// and pass along req.body as an argument to Botmetrics
// for example:
var express = require('express');
var app = express();
var bodyParser = require('body-parser');
var Botmetrics = require('botmetrics');

app.use(bodyParser.json()); // for parsing application/json

app.post('/webhooks', function(req, res) {
  Botmetrics.track(req.body);
  res.status(200).send("");
});

app.listen(5000, function () {
  console.log('facebook bot listening on port 5000!');
});

Usage (Kik)

Register your Kik bot with Botmetrics. Once you have done so, navigate to "Bot Settings" and find out your Bot ID and API Key.

Set the following environment variables with the Bot ID and API Key respectively.

BOTMETRICS_BOT_ID=your-bot-id
BOTMETRICS_API_KEY=your-api-key

track

Call the track API in the webhook receiver that handles all of your Kik bot callbacks.

Usage (Slack)

Log in to your BotMetrics account, navigate to "Bot Settings" and find out your Bot ID and API Key.

Set the following environment variables with the Bot ID and API Key respectively.

BOTMETRICS_BOT_ID=your-bot-id
BOTMETRICS_API_KEY=your-api-key

Once you have that set up, every time you create a new Slack Bot (in the OAuth2 callback), and assuming the bot token you received as part of the OAuth2 callback is bot-token, make the following call:

BotMetrics.registerBot('bot-token', function(err, status) {

});

Retroactive Registration

If you created your bot in the past, you can pass in createdAt with the UNIX timestamp of when your bot was created, like so:

BotMetrics.registerBot('bot-token', {createdAt: 1462318092}, function(err, status) {

});

User Enrichment

You can retroactively add information to users of your bot, for e.g. timezone information. If the ID of your user is bot-user-id (this is the ID you receive from the provider, in the case of Facebook, the Page Scoped ID of the user), you can call the enrichUser API to add more information:

BotMetrics.enrichUser('bot-user-id', {timezone: 'US/Pacific'},
function(err, status) {

});

Shortening Links

You can shorten a link that you want to send your users via a bot so that you can track link follows with Botmetrics. If the ID of your user is bot-user-id (this is the ID you receive from the provider, in the case of Facebook, the Page Scoped ID of the user), you can call the shortenLink API to attribute the link follow to that user.

BotMetrics.shortenLink('https://www.google.com', 'bot-user-id', function(err, shortenedLink) {
  // shortenedLink will look something like https://bot.af/to/deadbeef
  // which you can then use to send as part of your message payload
});

For Slack users, you will also have to send the team_id as a parameter:

BotMetrics.shortenLink('https://www.google.com', 'bot-user-id', {team_id: 'TDEADBEEF1'}, function(err, shortenedLink) {
  // shortenedLink will look something like https://bot.af/to/deadbeef
  // which you can then use to send as part of your message payload
});

Messaging a user or channel

You can use Botmetrics to message a user (via DM) or a channel for a given team. You can do this like this:

BotMetrics.message('slack-team-id', {user: 'USLACKBOT', text: 'hello there'}, function(err, status) {

});

For a channel, pass the Slack Channel ID as a parameter:

BotMetrics.message('slack-team-id', {channel: 'CCAFEDEAD1', text: 'hello there'}, function(err, status) {

});

To send attachments, you can send an attachments array:

Botmetrics.message('slack-team-id', {channel: 'CCAFEDEAD', attachments: [{"fallback": "hello", "text": "hello"}] }, function(err, status) {
  expect(status).to.be.true;
  expect(scope.isDone()).to.be.true;
  done();
});

To read more about Slack attachments, you can check it out at this Slack API Docs page.

BotMetrics will queue your message for sending. If your message is correctly formatted, you will receive status=true in the callback.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/botmetrics/botmetrics.js. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.