BotMetrics Documentation

If you're building a bot for Facebook Messenger, use the Facebook Messenger SDK for the most simple & complete integration.

For other messaging platforms, see below.

Facebook Messenger SDK

The Facebook Messenger SDK gives you out-of-the box support for many Facebook Messenger features. This includes viewing rich conversations with image attachements, button/generic/receipt templates, quick replies, etc.

NodeJS

Official NodeJS client: https://github.com/mnort9/node-botmetrics

var botmetrics = require('node-botmetrics')('API_TOKEN').facebook;
            

Track incoming messages

app.post('/webhook', function(req, res) {
    botmetrics.trackIncoming(req.body);
    
    // Handle incoming message...
}
            

Track outgoing messages

// Example POST to Facebook

var fbData = {
    recipient: { 
        id: fbUserId 
    },
    message: {
        text: 'Hi there!'
    }
};

var options = {
    url: 'https://graph.facebook.com/v2.6/me/messages',
    qs: { access_token: FB_PAGE_TOKEN },
    method: 'POST',
    json: fbData
};

request(options, function(err, res, body) {
    if (err) return console.log(err);
    
    // After FB post is successful, send req data to BotMetrics
    botmetrics.trackOutgoing(fbData);
});
            

And that's it! You're completely integrated!

REST

The Facebook Messanger SDK can also be used via the REST API.

Along with the "token" and "message_type" parameters, be sure to include "platform=facebook" to specify that you're using the Messenger SDK.

Example
https://api.bot-metrics.com/v1/messages?platform=facebook&message_type=incoming&token=API_TOKEN

URL Params

Param	Description
platform	Must equal "facebook" for the Messenger SDK	required
message_type	Incoming/outgoing message (must be 'incoming' or 'outgoing')	required
token	Bot API token	required

Request Body

The body of the POST request should match the payload that is sent to or received from Facebook.

Track incoming message

curl -XPOST -H "Content-type: application/json" -d '{ 
    "object": "page",
    "entry":[{
        "id": "FB_PAGE_ID",
        "time": 145869242290,
        "messaging": [{
            "sender": {
                "id": "FB_USER_ID"
            },
            "recipient": {
                "id": "FB_PAGE_ID"
            },
            "timestamp": 145869242290,
            "message": {
                "mid": "mid.1457764197618:41d102a3e1ae206a38",
                "seq": 73,
                "text": "hello, world!",
                "quick_reply": {
                    "payload": "DEVELOPER_DEFINED_PAYLOAD"
                }
            }
        }]
    }]
}' 'https://api.bot-metrics.com/v1/messages?platform=facebook&message_type=incoming&token=API_TOKEN'
        

Track outgoing message

curl -XPOST -H "Content-type: application/json" -d '{ 
    "recipient": {
     	"id": "FB_USER_ID"
     },
     "message": {
         "attachment": {
             "type": "template",
             "payload":{
                 "template_type":"button",
                 "text": "What kind of pizza do you want?",
                 "buttons": [{
                     "type": "web_url",
                     "url": "https://awsesomepizzabot.com",
                     "title": "Show Website"
                  }, {
                      "type": "postback",
                      "title": "Pepperoni",
                      "payload": "USER_DEFINED_PAYLOAD"
                  }]
             }
         }
     }
}' 'https://api.bot-metrics.com/v1/messages?platform=facebook&message_type=outgoing&token=API_TOKEN'
        

Other Platforms

The NodeJS client and REST API support generic tracking capability for all platforms (slack, kik, telegram, etc.)

NodeJS

Official NodeJS client: https://github.com/mnort9/node-botmetrics

var botmetrics = require('node-botmetrics')('API_TOKEN');

botmetrics.track({
    text: 'Hi there!',
    message_type: 'outgoing',
    user_id: '54367392345234',
    platform: 'kik'
});
            

*See below REST Request Body for all available properties

REST

Example
https://api.bot-metrics.com/v1/messages?token=API_TOKEN

URL Params

Param	Description
token	Bot API token	required

Request Body

Key	Description
text	Message text	required
message_type	Incoming/outgoing (must be 'incoming' or 'outgoing')	required
user_id	Unique identifier for a user	required
platform	Messaging platform ('slack', 'kik', etc.)	required
created_at	Timestamp when message was sent/received. If not provided, the current time will be used. ISO8601 format (ex: '2016-04-06T15:18:50Z')	optional
metadata	Custom string or JSON	optional

Example Request

curl -XPOST -H "Content-type: application/json" -d '{ 
    "text": "Hi there!",
    "message_type": "incoming",
    "user_id": "5436734",
    "platform": "kik"
}' 'https://api.bot-metrics.com/v1/messages?token=API_TOKEN'