faizshukri/hubot-fb

A Hubot adapter for the Facebook Messenger Platform

hubot-fb

A Hubot adapter for the Facebook Messenger Platform. This adapter fully supports everything the v2.6 Messenger platform API is capable of:

• Token validation and botside autosetup
• Resolving user profiles (name and profile pictures from ids)
• Send and receive text messages
• Send templates and images (jpgs; pngs; animated gifs)
• Receive images, location, and other attachments
• Template postbacks

Changelog

Installation

See detailed installation instructions here.

• For setting up a Hubot instance, see here
• Create a Facebook page and App (you can skip Quick Start after you create an App ID and enter your email), or use existing ones.
• Install hubot-fb into your Hubot instance using by running npm install -save hubot-fb in your Hubot's root.
• Configure hubot-fb. Setting up webhooks and subscribing to pages will be done automatically by hubot-fb.
• Set hubot-fb as your adapter by launching with bin/hubot -a fb. (Edit your Procfile to do the same on Heroku.)

Warnings

This adapter will truncate messages longer than 320 characters (the maximum allowed by Facebook's API). For alternate behavor, use a script like hubot-chunkify or hubot-longtext

If you update a webhook, allow up to 10 minutes for Facebook to propagate your webhook, then it will start posting to the new webhook url.

Configuration

Required variables are in bold.

config variable	type	default	description
FB_PAGE_ID	string	-	Your Facebook Page ID. You can find it at https://www.facebook.com/<YOUR PAGE USERNAME>/info?tab=page_info.
FB_APP_ID, FB_APP_SECRET	string	-	Your App ID and App Secret. You can find them at https://developers.facebook.com/apps/.
FB_WEBHOOK_BASE	string	-	The base url for a Facebook webhook subscription. This will be joined with FB_ROUTE_URL, e.g. FB_WEBHOOK_BASE=https://mybot.com and FB_ROUTE_URL=/hubot/fb will be passed to Facebook as https://mybot.com/hubot/fb. Note that the URL must use https.
FB_ROUTE_URL	string	/hubot/fb	The webhook route path hubot-fb monitors for new message events.
FB_PAGE_TOKEN	string	-	Your page access token. You can get one at https://developers.facebook.com/apps/<YOUR APP ID>/messenger/.
FB_VERIFY_TOKEN	string	-	Your verification token. This is the string your app expects when you modify a webhook subscription at https://developers.facebook.com/apps/<YOUR APP ID>/webhooks/. One will be automatically set for you if you do not specify a token.
FB_AUTOHEAR	boolean	false	Prepend a @<robot.name> to all dirrect messages to your robot, so that it'll respond to a direct message even if not explicitly invoked. E.g., for a robot named "hubot", both "ping" and "@hubot ping" will be passed as "@hubot ping"
FB_SEND_IMAGES	boolean	true	Whether or not hubot-fb should automatically convert compatible urls into image attachments

Use

Sending Rich Messages (Templates, Images)

Note: If you just want to send images, you can also send a standard image url in your message text with FB_SEND_IMAGES set to true. To send rich messages, include in your envelope

envelope = 
{
    fb: {
        richMsg: [RICH_MESSAGE]
    },
    user[...]
}

In a response, this would look something like:

robot.hear /getting chilly/i, (res) ->
    res.envelope.fb = {
      richMsg: {
        attachment: {
          type: "template",
          payload: {
            template_type: "button",
            text: "Do you wanna build a snowman?",
            buttons: [
              {
                type: "web_url",
                url: "http://www.dailymotion.com/video/x1fa7w8_frozen-do-you-wanna-build-the-snowman-1080p-official-hd-music-video_music",
                title: "Yes"
              },
              {
                type: "web_url",
                title: "No",
                url: "http://wallpaper.ultradownloads.com.br/275633_Papel-de-Parede-Meme-Okay-Face_1600x1200.jpg"
              }
            ]
          }
        }
      }
    }
    res.send()

See Facebook's API reference here for further examples of rich messages.

Events

Events allow you react to input that Hubot doesn't natively support. This adapter emits fb_postback, fb_delivery, fb_richMsg, and fb_richMsg_[ATTACHMENT_TYPE] events.

Register a listener using robot.on [EVENT_NAME] [CALLBACK].

event name	callback object	description
fb_postback	{ event: msgevent, user: hubot.user, room: string, payload: string }	Emitted when a postback is triggered.
fb_delivery	{ event: msgevent, user: hubot.user, room: string }	Emitted when a delivery confirmation is sent.
fb_richMsg	{ event: msgevent, user: hubot.user, room: string, attachments: array[msgevent.message.attachment]}	Emitted when a message with an attachment is sent. Contains all attachments within that message.
fb_richMsg_[ATTACHMENT.TYPE]	{ event: msgevent, user: hubot.user, room: string, attachment: msgevent.message.attachment}	Emitted when a message with an attachment is sent. Contains a single attachment of type [ATTACHMENT.TYPE], and multiple are emitted in messages with multiple attachments.
fb_optin or fb_authentication	{ event: msgevent, user: hubot.user, room: string, ref: string }	Emitted when an authentication event is triggered

fb_postback example

Responding to an event is a bit more manual—here's an example.

# You need this to manually compose a Response
{Response} = require 'hubot'

module.exports = (robot) ->

  # This can exist alongside your other hooks
  robot.on "fb_postback", (envelope) -> 
    res = new Response robot, envelope, undefined
    if envelope.payload is "send_ok_face"
      res.send "http://wallpaper.ultradownloads.com.br/275633_Papel-de-Parede-Meme-Okay-Face_1600x1200.jpg"

Of course, postbacks can do anything in your application—not just trigger responses.