A Hubot adapter for the Facebook Messenger Platform





GitHub Stars



Last Commit

5yrs ago








Type Definitions






NPM Version Dependency Status

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



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.)


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.


Required variables are in bold.

config variabletypedefaultdescription
FB_PAGE_IDstring-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_SECRETstring-Your App ID and App Secret. You can find them at https://developers.facebook.com/apps/.
FB_WEBHOOK_BASEstring-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_URLstring/hubot/fbThe webhook route path hubot-fb monitors for new message events.
FB_PAGE_TOKENstring-Your page access token. You can get one at https://developers.facebook.com/apps/<YOUR APP ID>/messenger/.
FB_VERIFY_TOKENstring-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_AUTOHEARbooleanfalsePrepend 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_IMAGESbooleantrueWhether or not hubot-fb should automatically convert compatible urls into image attachments


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]

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"

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


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 namecallback objectdescription
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.

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0