hubot-fb-platform

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
• Quick replies

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.