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//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//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//webhooks/. One will be automatically set for you if you do not specify a token. |
| FB_AUTOHEAR | boolean | false | Prepend a @ 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

$3

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

$3


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.