Facebook Messenger

Our Facebook Messenger integration allows your users to send you Facebook messages through your Facebook Page which you receive in a business system or with Webhooks. Your replies are sent back as a Facebook message to the user.

Capabilities

Facebook Messenger supports a wide variety of capabilities as seen in the channel capabilities grid. Below is a detailed view of each capabilities.

Content Types

  • Full Support

    API

    Text

    Plain text messages

  • Full Support

    API

    Image

    Display static images

  • Partial Support

    API

    File

    Send and receive any file types

  • Full Support

    API

    Emoji

    Unicode Emojis✨

  • Full Support

    API

    GIF

    Send animated GIFs

  • Partial Support

    API

    Location

    Receive the geolocation of the user

Action Types

  • Full Support

    API

    Link

    Display web links as buttons

  • Full Support

    API

    Extensions

    Send custom interactive experiences built with Jav...

  • Full Support

    API

    Buy

    Request payments within a conversation

  • Full Support

    API

    Postback

    Send buttons to trigger events on your server

  • Full Support

    API

    Replies

    Suggest a few answers to reply to a message

  • Full Support

    API

    Location Request

    Request the current location of the user

Structured Messages

  • Full Support

    API

    Compound Messages

    Compose messages with multiple actions

  • Full Support

    API

    Carousel

    Send an horizontally scrollable set of cards that ...

Indicators

  • Full Support

    API

    Typing

    Display a typing indicator

  • Full Support

    API

    Read

    Display read status

  • Full Support

    API

    Conversation Start

    Recieve a <a href="https://docs.smooch.io/rest/#co...

Configuring Facebook Messenger

A business on Facebook Messenger is represented by a Facebook page, which is owned by a Facebook account. A page owner can grant access to a 3rd party Facebook app, allowing it to interact with that page on the owner’s behalf. This is how the Smooch Facebook Messenger integration works.

There are two ways to configure a new integration. If you’re integrating Smooch with your own Facebook page, you can do so via the web dashboard. With this option you’re granting Smooch’s own Facebook app access to your page. However, if you’re integrating Smooch on behalf of your customer then you will need to use the Integration API.

Using the Dashboard

In this option you’re granting Smooch access to your own Facebook page. Note that your Facebook account must have Admin access to the page in question. You can check this from your Facebook page by browsing to Settings > Page Roles.

You can find the Smooch Messenger integration in the Integrations menu bar tab of the Smooch dashboard. When you click Authenticate, you will be redirected to Facebook where you will be prompted to grant Smooch access to interact with pages on your behalf.

Facebook Messenger OAuth Prompt

Once your Facebook account is connected to Smooch, select your Facebook page and hit save. You should now be able to receive messages from your Facebook page and reply via any of your configured business systems or with the Smooch API.

Using the Integration API

If you’re building your own user experience for users integrating their Facebook page with your software, this option is for you. In this scenario after you’ve obtained authorization from the Facebook page owner, you will create the Smooch integration via the Integration API. To begin you must first have your own Facebook app with your own company name and logo. This Facebook app represents your business identity in the Facebook platform whenever you request permission to act on behalf of another Facebook user.

Quick Start

Before you submit your App Review you can get a Smooch integration up and running quickly on one of your own pages by issuing yourself a page access token via the Facebook dashboard. From your App settings choose Messenger > Settings > Token Generation.

Generate a page token for your own page
Facebook App Permissions

Before you go live your app will need to request some special Facebook permissions in order to integrate with Smooch. These additional permissions will require your Facebook app to pass an App Review. The permissions subject to review are:

  • manage_pages: Required for listing a user’s pages and obtaining page access tokens. To add review submission, from the Facebook dashboard browse to the App Review section, then click Start Submission.
  • pages_messaging: Required for sending and receiving messages. First, add the Messenger product to your app, and then add this permission to your review request from the Messenger section of the Facebook dashboard.
Integration Flow Overview

When a user integrates their page with your software, the sequence will typically follows these steps:

  1. Obtain a user access token
  2. Use this token to query a list of the user’s Facebook pages
  3. Present this list to the user and prompt them to choose one
  4. Obtain a page access token for the selected page
  5. Create a new Smooch integration using this page access token

The first step is to request a user access token. This step represents the user granting you permission to act on their behalf. This can be done in a number of ways, each with their own strengths and weaknesses that are detailed below.

User Access Token: Facebook JavaScript SDK

The easiest way to implement a user access token flow is by using the Facebook JavaScript SDK. We’ve created a github sample project here that demonstrates this process end-to-end.

The first step is to embed the Facebook SDK script tag into your website. Then you’ll call FB.login(), requesting the scopes manage_mages and pages_messaging as seen below:

FB.login((data) => {
    const userAccessToken = data.authResponse.accessToken;
}, {
    scope: 'manage_pages,pages_messaging'
});

This will prompt the user to grant your app these requested permissions. If the user agrees, an access token will be returned to you in the FB.login() callback.

User Access Token: Build a custom OAuth flow

In this option you’ll be building an OAuth flow based on browser redirects. The advantage with this option is that it doesn’t rely on the Facebook JavaScript SDK’s popup window. Instead, this flow redirects the user to Facebook in order grant access. A browser redirect based flow might be preferable for native apps and mobile devices.

OAuth Flow

The flow begins with redirecting the user’s browser to Facebook, where they will be shown an access grant dialog. Upon granting permission, Facebook will redirect the user back to your site using a predefined callback URL. This callback will include a code that your server side application can then exchange for an access token, using your Facebook app ID and secret. The endpoints your web service will need to implement in order to achieve this flow are detailed in the Facebook article Manually Build a Login Flow.

Page Access Token

You’ll now use the user access token obtained in the previous step to obtain a page access token. You can query the user’s pages with the /me/accounts API.

First, obtain your Facebook App ID and secret from Facebook dashboard. You’ll use these in addition to the user access token to make a server-to-server API call. You must not make this call from the user’s browser because doing so would force you to expose your App secret.

GET https://graph.facebook.com/me/accounts?
    client_id=facebook_app_id
    &client_secret=facebook_app_secret
    &access_token=user_access_token
    &limit=500

The response will include a list of users’ pages and their associated page access tokens. All that’s left to do is to prompt the user to choose which one they wish to integrate. Once the user has selected the page you can now call the Smooch integration API to connect their page with Smooch, passing along your app id, app secret, and the page access token.

Congratulations! You’re Done!

Action Buttons

Facebook Messenger currently supports all available action types.

The number of message actions allowed in a given message or message item is limited by the Facebook Messenger platform. For actions of type reply and locationRequest, the limit is eleven. For all other action types, the limit is three. If the actions array of a message or message item exceeds the number of actions that Facebook Messenger allows, the list will be truncated to fit the limit, and actions beyond the allowed size will be ignored.

Reply

Reply buttons (also known as ‘Quick Replies’) provide a way to present a set of up to 11 buttons in-conversation that contain a title and optional image, and appear prominently above the composer. When a reply button is tapped, the list of buttons that was presented disappears and the text associated to the button is sent as a user message to the business.

These buttons are useful for presenting a list of multiple choice options to a user that are only relevant as an answer to a question being asked of the user at that time. For example, you can use reply buttons to send a set of buttons labelled 0-10 in order to measure NPS at the end of a customer service interaction.

Messenger Reply Buttons

You can send reply buttons via the Post Message API or through the use of messaging shorthand. The latter technique allows you to easily send reply buttons (and other interactive message types) to the user, without adding support for them directly to your application’s code.

Messenger offers full support for carousels which allows you to send a set of horizontally scrollable items that combines text, image and message actions.

Carousel example

You can send carousels containing up to 10 items via the Post Message API. Note that reply and location buttons are not allowed in a carousel.

List

Messenger also has full support for list messages. List messages are a vertically scrollable set of items that may each contain text, an image, and an message action.

List example

You can send list messages containing up to 10 items via the Post Message API. Note that each items in a list can only contain 1 button (Link, Buy, Postback & Share are the only allowed action types). Each item also supports a default action. Using this, you can enable people to open a URL when the row of the list item is tapped.

List messages can also append 1 message action at the bottom of the list. For example, you can use this extra action to let users see more items as shown above (More choices).

Call Buttons

A link action with a tel: protocol will be delivered as a Call Button.

Persistent Menu

Facebook Messenger Persistent Menu

It’s possible to configure a menu on the Messenger UI by calling the Smooch REST API. Messenger allows up to three levels of menu hierarchy and they can contain 1 to 3 menu items at its first level and 1 to 5 menu items for submenus. Menus are configured per app or per integration, not per user. Menu items can be link, postback or submenu type actions.

Payments

Facebook Messenger Payments

You can request a one time payment from your users on Facebook messenger by sending a Buy button, either via our button syntax or the Post Message API. Payments support is native on Facebook Messenger and payments processing goes through their own payment gateway instead of our Stripe integration which is used for all other customer channels. You can learn more about Facebook Payments here.

Setup

To send a payment request, you’ll first need to be approved into Facebook Payments’s beta program. Facebook is giving select US-based partners the opportunity to collect payments from customers over Messenger.

If you wish to apply, please contact us and we’ll reach out to Facebook to open up payments for your account.

Send Buy Buttons

You can send Buy buttons either via the $[label](9.99) syntax or by including Buy actions in your call to the Post Message API.

Buy buttons can be combined with a text message, other actions, an image and/or in a list or carousel message type.

Facebook limits messages to contain only one buy button per list item and they must be in the first position.

Currency limitation

If you are using our Stripe integration to power payments on other channels, enabling Facebook payment will force your default currency to USD since Facebook Payments only support USD at the moment.

The default currency is automatically selected when using the button syntax. When using the Post Message API you can specify the currency for each call. However if that message needs to be delivered to Messenger, it will be rejected.

Webhook Events Workaround

When integrating a Messenger page with Smooch for the first time, a setup flow is initiated in which Smooch will automatically set a webhook subscription for your app. We do this with a call to the subscriptions API. This call creates a webhook pointing to the Smooch platform, and subscribes to all required events. However, due to a new bug in the Facebook platform, the call that Smooch makes is not able to add the required events. To work around this issue, after Smooch creates a webhook subscription, you must go into the developer dashboard and manually add the required events. To configure this setting:

  1. Head to the Facebook developer dashboard
  2. Select the app that you have just integrated with Smooch
  3. In the left sidebar, under “Products”, select “Messenger” and click “Settings”. If you don’t see Messenger in the list of Products, click the ”+” button beside “Products” and add Messenger to your app.
  4. In the Messenger settings page, scroll down to the “Webhooks” section, and click the “Edit Events” button.
  5. In the events dialog, select all of the following events: messages, messaging_postbacks, messaging_optins, message_reads, and messaging_referrals
  6. Click save. Your settings should now look like this Facebook Messenger Webhook Events

Your webhook is now created and correctly configured to receive events from your integrated pages. However, because this flow did not work correctly during the original API call to Smooch, your app is not yet subscribed to receive events from the page you just integrated. To subscribe your app to the page, you can either:

  • If you are an admin on the page you would like to subscribe, you can add the subscription manually from the Facebook developer dashboard. In the same section where you configured events in the previous steps, you will see an option to “Select a page to subscribe your webhook to the page events”. Select your page from the dropdown and click Subscribe.
  • If you are not an admin on the page you would like to subscribe, you must delete the integration and re-create it using the Smooch API. Smooch will now be able to create the subscription automatically, since your webhook is correctly configured.

Your app should now be subscribed to receive updates for the page and webhook events should now be sent to Smooch. To verify, send a test message to your page and ensure that a message is indeed received from your Messenger integration.

When integrating a second page for the same Facebook app, or if your webhook is already created and subscribed to the correct events, you will not need to go through this flow again. The bug only affects Facebook apps which do not yet have a webhook configured.