search

chen-ye / hubot-fb

A Hubot adapter for the Facebook Messenger Platform
https://www.npmjs.com/package/hubot-fb
87 stars 21 forks source link

readme

hubot-fb

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:

Changelog

Installation

See detailed installation instructions here.

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.