fbmessenger

    5.0.3 • Public • Published

    fbmessenger

    Greenkeeper badge Build Status Coverage Status npm version npm

    A library to integrate with the Facebook Messenger Platform.

    Notice: Please see the CHANGELOG for any breaking changes.

    Table of contents

    Installation

    Execute this line in your app directory:

    yarn add fbmessenger
    

    or for npm

    npm install --save fbmessenger
    

    Import library into your app:

    import { Messenger } from 'fbmessenger';

    Initialize it:

    const messenger = new Messenger({
      pageAccessToken: '<PAGE_ACCESS_TOKEN>'
    });

    Configuration of facebook app

    First of all visit the official tutorial and make sure you complete these 3 steps:

    Steps:

    Express.js (example usage)

    This is basic usage within an express.js application. For more detailed example look here.

    import bodyParser from 'body-parser';
    import { Messenger } from 'fbmessenger';
     
    // Configuring Body Parser middleware to parse the incoming JSON and Url-encoded data
    app.use(bodyParser.json());
    app.use(bodyParser.urlencoded({ extended: true }));
     
    // Initialize Messenger
    const messenger = new Messenger({
      pageAccessToken: '<PAGE_ACCESS_TOKEN>'
    });
     
    // here we define some listeners:
    messenger.on('message', (event) => {
      // put your logic here
    });
     
    messenger.on('postback', (event) => {
      // put your logic here
    });
     
    // This example shows how to setup verification using express
    app.get('/webhook', (req, res) => {
      if (req.query['hub.mode'] === 'subscribe' &&
        req.query['hub.verify_token'] === process.env.VERIFY_TOKEN) {
        res.send(req.query['hub.challenge']);
      } else {
        res.sendStatus(400);
      }
    });
     
     
    // This route handles the webhook callbacks from Facebook
    app.post('/webhook', (req, res) => {
      res.sendStatus(200);
      messenger.handle(req.body);
    });

    Verifying Requests

    It's important but not fundamental to verify each request that your application receives to make sure that who is calling your /webhook endpoint is Facebook and not some other person. That could be done by through verifying the Signature Hash that Facebook sends on every request. You will need to have your APP_SECRET in hands for performing such verification.

    // Function that verifies the signature hash
    const verifyRequestSignature = (req, res, buf) => {
        const signature = req.headers['x-hub-signature'];
     
        if (!signature) {
            throw new Error('Couldn\'t validate the signature.');
        } else {
            const elements = signature.split('=');
            const signatureHash = elements[1];
            const expectedHash = crypto.createHmac('sha1', process.env.APP_SECRET).update(buf).digest('hex');
     
            if (signatureHash !== expectedHash) {
                throw new Error('Couldn\'t validate the request signature.');
            }
        }
    };
     
    // Pass a function that verifies the signature instead of just calling app.use(bodyParser.json())
    app.use(bodyParser.json({ verify: verifyRequestSignature });

    Events

    Events are triggered when Facebook posts to your webhook url. The following events can be listened for:

    • message
    • delivery
    • optin
    • read
    • account_linking
    • postback
    • referral
    • checkout_update
    • payment
    • pre_checkout

    Listening for events

    messenger.on(<event>, (message) => {
        console.log(message);
    });

    example console output

    {
      sender: {
        id: 1234,
      },
      recipient: {
        id: 1234,
      },
      timestamp: 1457764197627,
      message: {
       text: 'Hello World!'
      }
    }

    Sending messages

    Messages are sent using the send(message, recipient) method. It returns a Promise (from node-fetch).

    If replying to a user, the recipient can be obtained from message.sender.id in the event listener. Otherwise it should be a Facebook page scope ID from a database or other data store.

    Send a simple text reply

    messenger.on('message', (message) => {
      messenger.send({ text: 'Hello' }, message.sender.id);
    });

    Catching errors

    You can add a catch to get errors from the request.

    messenger.send({ text: "Hello" })
      .then(console.log(res))
      .catch(err => console.log(err));

    or if using async/await you can wrap your code in a try/catch block

    messenger.on('message', async (message) => {
      try {
        await messenger.send({ text: 'Hello' }, message.sender.id);
      } catch (err) {
       console.error(err);
      }
    });

    Get a user's details

    Example usage:

    messenger.getUser()
      .then((user) => {
        messenger.send({
         text: `Hey ${user.first_name} ${user.last_name}`
        }, message.sender.id);
    });

    Returns object with user data:

    • first_name
    • last_name
    • profile_pic
    • locale
    • timezone
    • gender
    • is_payment_enabled

    Elements

    Text

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/text-message

    Example usage:

    import { Text } from 'fbmessenger';
     
    messenger.send(new Text('Hello World!'), message.sender.id);

    you can also just pass an object to the send method like this

    { text: 'Hello World!' }

    Button

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons

    Example (with ButtonTemplate):

    import {
      Button,
      ButtonTemplate
    } from 'fbmessenger';
     
    messenger.send(new ButtonTemplate(
      'Hey user! Watch these buttons:',
      [
        new Button({
          type: 'web_url',
          title: 'Web Url Button',
          url: 'http://www.example.com',
        }),
        new Button({
          type: 'postback',
          title: 'Postback Button',
          payload: 'POSTBACK_INFO',
        }),
      ]
    ), message.sender.id);

    For more examples, check out the tests.

    Element

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template

    Example usage:

    import {
      Button,
      Element,
    } from 'fbmessenger';
     
    ...
    new Element({
      itle: 'Title',
      item_url: 'http://www.example.com',
      image_url: 'http://www.example.com',
      subtitle: 'Subtitle',
      buttons: [
        new Button({
          type: 'web_url',
          title: 'Web Url Button',
          url: 'http://www.example.com',
         }),
        new Button({
          type: 'postback',
          title: 'Postback Button',
          payload: 'POSTBACK_INFO',
          })
      ]
    });
    ...

    Address

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

    This element must be used with the Receipt template.

    Example usage:

    import { Address } from 'fbmessenger';
     
    ...
    new Address({
      street_1: '1 Hacker Way',
      street_2: '',
      city: 'Menlo Park',
      postal_code: '94025',
      state: 'CA',
      country: 'US'
    });
    ...

    Summary

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

    This element must be used with the Receipt template.

    Example usage:

    import { Summary } from 'fbmessenger';
     
    ...
    new Summary({
      subtotal: 75.00,
      shipping_cost: 4.95,
      total_tax: 6.19,
      total_cost: 56.14
    });
    ...

    Adjustment

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

    This element must be used with the Receipt template.

    Example usage:

    import { Adjustment } from 'fbmessenger';
     
    ...
    new Adjustment({
      name: 'Adjustment',
      amount: 20
    });
    ...

    Attachments

    Image

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/image-attachment

    Example usage:

    import { Image } from 'fbmessenger';
     
    messenger.send(new Image({
      url: 'http://lorempixel.com/400/400/sports/1/',
    }), message.sender.id);

    Audio

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/audio-attachment

    Example usage:

    import { Audio } from 'fbmessenger';
     
    messenger.send(new Audio({
      url: 'http://example.com/audio.mp3',
    }), message.sender.id);

    Video

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/video-attachment

    Example usage:

    import { Video } from 'fbmessenger';
     
    messenger.send(new Video({
      url: 'http://example.com/video.mp4',
    }), message.sender.id);

    File

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/file-attachment

    Example usage:

    import { File } from 'fbmessenger';
     
    messenger.send(new File({
      url: 'http://example.com/file.txt',
    }), message.sender.id);

    Reusable attachments

    Attachments can be reused by passing true as the second parameter. This sets the is_reusable flag.

    const image = new Image({
      url: 'http://lorempixel.com/400/400/sports/1/',
      is_reusable: true
    });
    messenger.send(image, message.sender.id);

    You can then use the attachment_id from the response to send the same attachment again

    messenger.send(new Image({ attachment_id: 12345 }, message.sender.id);

    Attachment Upload API

    const image = new Image({
      url: 'http://lorempixel.com/400/400/sports/1/',
      is_reusable: true
    });
    messenger.messageAttachment(image);

    This will return a reusable attachment ID.

    Templates

    ButtonTemplate

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/button-template

    Example usage:

    import {
      Button,
      ButtonTemplate
    } from 'fbmessenger';
     
    messenger.send(new ButtonTemplate(
      'Hey user! Watch these buttons:',
      [
        new Button({
          type: 'web_url',
          title: 'Web Url Button',
          url: 'http://www.example.com',
        }),
        new Button({
          type: 'postback',
          title: 'Postback Button',
          payload: 'POSTBACK_INFO',
        })
      ]
    ), message.sender.id);

    GenericTemplate

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template

    Example usage:

    import {
      Button,
      Element
      GenericTemplate
    } from 'fbmessenger';
     
    messenger.send(new GenericTemplate(
    [
      new Element({
        title: 'Title',
        item_url: 'http://www.example.com',
        image_url: 'http://www.example.com',
        subtitle: 'Subtitle',
        buttons: [
          new Button({
            type: 'web_url',
            title: 'Button',
            url: 'http://www.example.com',
          }),
        ]
      }),
      ...
    ]
    ), message.sender.id);

    ReceiptTemplate

    https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

    Example usage:

    import {
      Button,
      Element,
      Address,
      Summary,
      Adjustment,
      ReceiptTemplate
    } from 'fbmessenger';
     
    messenger.send(new ReceiptTemplate({
      recipient_name: 'Name',
      order_number: '123',
      currency: 'USD',
      payment_method: 'Visa',
      order_url: 'http://www.example.com',
      timestamp: '123123123',
      elements: [
        new Element({
          title: 'Title',
          image_url: 'http://www.example.com',
          subtitle: 'Subtitle',
          currency: 'USD',
          quantity: 1,
          price: 15
        })
      ],
      address: new Address({
        street_1: '1 Hacker Way',
        street_2: '',
        city: 'Menlo Park',
        postal_code: '94025',
        state: 'CA',
        country: 'US'
      }),
      summary: new Summary({
        subtotal: 75.00,
        shipping_cost: 4.95,
        total_tax: 6.19,
        total_cost: 56.14
      }),
      adjustments: [
        new Adjustment('Adjustment', 20)
      ]
    }), message.sender.id);

    Thread settings

    Greeting Text

    https://developers.facebook.com/docs/messenger-platform/thread-settings/greeting-text

    import { GreetingText } from fbmessenger
     
    const greeting = new GreetingText('Hello');
    messenger.setThreadSetting(greeting);

    There is also a method to delete the greeting text called deleteGreetingText

    Get Started Button

    https://developers.facebook.com/docs/messenger-platform/thread-settings/get-started-button

    import { GetStartedButton } from 'fbmessenger';
     
    const getStarted = new GetStartedButton('start');
    messenger.setThreadSetting(getStarted);

    When someone first interacts with your bot they will see a Get Started button. When this is clicked it will send a postback to your server with the value of start.

    There is also a method to delete the Get Started Button called deleteGetStarted

    Persistent Menu

    https://developers.facebook.com/docs/messenger-platform/thread-settings/persistent-menu

    import {
      PersistentMenu,
      PersistentMenuItem
    } from 'fbmessenger';
     
    const item_1 = new PersistentMenuItem({
        item_type: 'web_url',
        title: 'Menu button 1',
        url: 'http://facebook.com'
    });
     
    const item_2 = new PersistentMenuItem({
        item_type: 'payload',
        title: 'Menu button 2',
        payload: 'menu_button_2'
    });
     
    const item_3 = new PersistentMenuItem({
        item_type: 'web_url',
        title: 'Menu button 3',
        url: 'http://facebook.com',
        webview_height_ratio: 'tall',
        messenger_extensions: true
    });
     
    const menu = new PersistentMenu([item_1, item_2, item_3]);
    messenger.setThreadSetting(menu);

    You can delete the Persistent Menu using the deletePersistentMenu method

    Sender Actions

    Available actions are

    • typing_on
    • typing_off
    • mark_seen
    messenger.senderAction('typing_on', message.sender.id);

    Quick Replies

    Quick Replies work with all message types including text message, image and template attachments.

    const reply1 = new QuickReply({
      title: 'Example',
      payload: 'payload',
    });
    const reply2 = new QuickReply({
      title: 'Location',
      content_type: 'location',
    });
    const quick_replies = new QuickReplies([reply1, reply2]);
     
    const text = new Text('A simple text message')
     
    const payload = Object.assign(text, quick_replies)
     
    messenger.send(payload, message.sender.id)

    Whitelisted domains

    Adding

    // Single
    messenger.addWhitelistedDomain('http://example.com');
     
    // Multiple
    messenger.addWhitelistedDomains(['http://example.com', 'http://example2.com']);

    Removing

    // Single
    messenger.removeWhitelistedDomain('http://example.com');
     
    // Multiple
    messenger.removeWhitelistedDomains(['http://example.com', 'http://example2.com']);

    Messenger Code API

    messenger.messengerCode({ size: 1000 });
    messenger.messengerCode({ ref: 'MY_REF' });

    Subscribing an app to a page

    The easiest way to do this is now through the Facebook developer site. If you need to do this progamatically you can use subscribeAppToPage

    Account linking

    You can link and unlink accounts with linkAccount and unlinkAccount

    messenger.linkAccount('ACCOUNT_LINKING_TOKEN');
    messenger.unlinkAccount('PSID');

    Sending raw payloads

    You can also send raw payloads with send. This lets you use any new features from Facebook while waiting for support to be added to this library.

    messenger.on('message', () => {
      messenger.send({
        "attachment":{
          "type":"template",
          "payload":{
            "template_type":"button",
            "text":"What do you want to do next?",
            "buttons":[
              {
                "type":"web_url",
                "url":"https://petersapparel.parseapp.com",
                "title":"Show Website"
              }
            ]
          }
        }
      }, message.sender.id);
    });

    Install

    npm i fbmessenger

    DownloadsWeekly Downloads

    46

    Version

    5.0.3

    License

    MIT

    Unpacked Size

    1.06 MB

    Total Files

    171

    Last publish

    Collaborators

    • rickydunlop