@botpress/channel-messenger

    10.51.10 • Public • Published

    Botpress Messenger

    Install

    npm i @botpress/channel-messenger
    

    Getting started

    1. Run npm start. Since you don't have configuration an error will be displayed to console which is fine. Once it's displayed bot will create default configuration which you'll need to edit after stopping the bot.
    2. You need to create Facebook App

    1)

    Create App 2) Click on Messenger `Set Up` Set Up Messenger 3. Get all required fields from `config/channel-messenger.json` [config template](https://github.com/botpress/botpress/blob/master/packages/channels/botpress-channel-messenger/config.json)

    1)

    App ID 2) App Secret 3) App Token 4) Webhook
    1. In you facebook-app configuration at https://developers.facebook.com/ set webhook (an url should be something like https://[bot-hostname]/api/botpress-messenger/webhook) and chose next option.. (webhook template https://[bot-hostname]/api/botpress-messenger/webhook)

    2. You need to send review request to FB. Do following:

    1. Go to https://developers.facebook.com -> Select your App -> App Review -> Submit Items for Approval -> Start a Submission -> pick up: publish_pages and manage_pages -> Resolve all Additional Information Required
    Start submission Pick fields
    1. Messenger -> Settings -> Go to section App Review for Messenger -> Select all fields -> Resolve all Additional Information Required
    Pick fields
    1. Go to Settings -> Basic -> Need resolve all Currently Ineligible for Submission
    Pick fields

    Explaining config keys

    Config template

    "displayGetStarted" - exclude/include interaction with Get Started. Default: true

    "greetingMessage" - set default messege. Default: "Default greeting message"

    "enableAllProfileFields" - If you need to know user timezone, gender, locale set true and send you app to review.

    Greeting Message

    "persistentMenu" - added menu to your messenger. See more

    "persistentMenuItems" - <needs investigation>

    "composerInputDisabled" - <needs investigation>

    "targetAudience" - decied who will can/can't use your chat. Default: "openToAll"

    1. "openToAll"
    2. "openToSome" - chat is available for people from "targetAudienceOpenToSome" list
    3. "closeToSome" - chat isn't available for people from "targetAudienceCloseToSome" list
    4. "closeToAll" - chat unavailable for all

    "autoResponseOption" - used for send automaticaly something (depend on used value) to user when he/she click on Get Started It has three variant of value "autoResponseText"|"autoResponsePostback"|"noResponse"

    1. "autoResponseText" - send text to user. Text takes from autoResponseText
    2. "autoResponsePostback" - <needs investigation>
    3. "noResponse" - auto response off

    Features

    Incoming

    Outgoing

    Reference

    Incoming

    You can listen to incoming event easily with Botpress by using bp built-in hear function. You only need to listen to specific Messenger event to be able to react to user's actions.

    bp.hear({ platform: 'facebook', type: 'postback', text: 'GET_STARTED' }, (event, next) => {
          bp.renderers.sendToUser(event.user.id, '#!text-77734', { typingIndicators: false })
       }
    })

    In fact, this module preprocesses almost all types of message (message, attachment, postback, quick_reply, delivery, read, optin, referrals...) and send them to incoming middlewares. When you build a bot or a module, you can access to all information about incoming messages that have been send to middlewares.

    bp.middlewares.sendIncoming({
       platform: 'facebook',
       type: 'message',
       user: profile,
       text: e.message.text,
       raw: e
    })

    Profile

    You can acces to all user's profile information by using this module. A cache have been implemented to fetch all information about users and this information is sent to middlewares.

    {
      id: profile.id,
      platform: 'facebook',
      gender: profile.gender,
      timezone: profile.timezone,
      locale: profile.locale,
      picture_url: profile.profile_pic,
      first_name: profile.first_name,
      last_name: profile.last_name
    }

    Note: All new users are automatically saved by this module in Botpress built-in database (bp.db).

    Text messages

    An event is sent to middlewares for each incoming text message from Messenger platform with all specific information.

    {
      platform: 'facebook',
      type: 'message',
      user: profile,
      text: e.message.text,
      raw: e
    }

    Then, you can listen easily to this event in your module or bot

    bp.hear('hello')

    Postbacks

    {
      platform: 'facebook',
      type: 'postback',
      user: profile,
      text: e.postback.payload,
      raw: e
    }

    Attachments

    The original attachments messenger event. May contain multiple attachments. Individual attachments are also emmited individually (see Image, Video, File below)

    {
      platform: 'facebook',
      type: 'attachments',
      user: profile,
      text: e.message.attachments.length + ' attachments',
      raw: e
    }
    Image

    Individual Attachment extracted from the Attachments event.

    Note that Stickers, Thumbs Up, GIFs and Pictures are considered images too.

    {
      platform: 'facebook',
      type: 'image', // Same for 'video', 'file' and 'audio'
      user: profile,
      text: 'http://www.image.url',
      raw: { type: 'image', payload: { url: '...' }}
    }
    Audio
    Video
    File

    Same signature as Image above.

    Referrals

    {
      platform: 'facebook',
      type: 'referral',
      user: profile,
      text: e.referral.ref,
      raw: e
    }

    Quick Replies

    {
      platform: 'facebook',
      type: 'quick_reply',
      user: profile,
      text: e.message.quick_reply.payload,
      raw: e
    }

    Optins

    {
      platform: 'facebook',
      type: 'optin',
      user: profile,
      text: e.optin.ref,
      raw: e
    }

    Delivery

    {
      platform: 'facebook',
      type: 'delivery',
      user: profile,
      text: e.delivery.watermark,
      raw: e
    }

    Read

    {
      platform: 'facebook',
      type: 'read',
      user: profile,
      text: e.read.watermark,
      raw: e
    }

    Outgoing

    By using our module, you can send anything you want to your users on Messenger. In fact, this module support all types of messages that are available on Facebook (text, images, videos, audios, webviews...).

    Send element

    bp.renderers.sendToUser(userId, elementOrRenderer, data) -> Promise

    1. userId (String): Correspond to unique Messenger's recipient identifier
    2. elementOrRenderer (String): The name of the renderer to use OR an element id
    3. data (Object): Additionnal data that will be passed to the renderer
      bp.renderers.sendToUser(event.user.id, '#!text-77734', { typingIndicators: false })

    Postbacks

    This module support postbacks. Postbacks occur when a Postback button, Get Started button, Persistent menu or Structured Message is tapped (facebook doc).

    Referrals

    This module also support referrals. In fact, the value of the ref parameter is passed by the server via webhook and we are able to access these referrals in parameters of input messages (facebook doc).

    Display Get Started

    To active get started button on Messenger, users can modify display setting directly in user interface (facebook doc).

    Get started button

    Greeting message

    Directly in module view, users are able to modify greeting message (facebook doc).

    Greeting message

    Persistent menu

    Users can directly modify persistent menu in module user interface. By using UI, it's possible to add, modify and remove items (facebook doc).

    Persistent menu

    Automatically mark as read

    Directly in UI, users can setup if they want to automatically mark all messages as read (facebook doc).

    Mark as read

    Composer input disabled

    Directly in UI, users can setup if they want to deactivate or not the user input (facebook doc).

    Trusted domains

    By using UI, users can configure (add, modify and remove) trusted domains (facebook doc).

    Trusted domains

    Chat Extensions

    Using the UI, you can set the home URL for your chat extension (facebook doc).

    Note: the URL you specify must use HTTPS. Facebook will return an error if you enter an URL that is not using HTTPS.

    Chat Extensions

    Chat extensions supports the following configuration options:

    • Update Home URL: the url that hosts your chat extension. You can remove the URL by leaving the box blank.
    • Show Share Button: if checked, this will show a Facebook share button in the header of your webview.
    • In Test: if checked, your chat extension is in test mode and is only viewable by people associated with your Messenger app in the developer console. Uncheck this box when you want your chat extension to be viewable to the general public

    Payment Testers

    Using the UI, you can assign users to be "Payment Testers."

    In order for this to work, the user must be a registered admin, developer or test user through your Facebook developer console and they must have initiated conversation with your bot. You cannot just add any user to be a payment tester. It is also important to note that this is the only way to run a test payment with Messenger Extensions.

    Payment Testers

    When adding a new user, you can start typing their name into the box. This will pull up a list of matching users who have been communicating with your bot. The value in the parentheses is the page-scoped user ID for that user.

    Automatic profile lookup

    Profiles are automatically lookedup using Facebook Graph API. The profile of the user can be found in the incoming middleware events: event.user

    The following properties are available: first_name, last_name, locale, gender, timezone.

    Save users in Database

    Users are automatically persisted in the built-in botpress database using the built-in bp.db.saveUser function.

    Webhook security check

    botpress-messenger verifies that requests really come from Facebook's servers by validating requests hash.

    Example

    Community

    There's a Slack community where you are welcome to join us, ask any question and even help others.

    Get an invite and join us now! 👉 https://slack.botpress.io

    License

    botpress-messenger is licensed under AGPL-3.0

    Install

    npm i @botpress/channel-messenger

    DownloadsWeekly Downloads

    32

    Version

    10.51.10

    License

    AGPL-3.0-only

    Unpacked Size

    1.05 MB

    Total Files

    24

    Last publish

    Collaborators

    • laurentlp
    • samuelmasse
    • slvnperron
    • spgingras
    • franklevasseur