Facebook Messenger

Facebook Messenger has over 1.2 million users and is among the richest messaging channels available for businesses to reach customers. Engage them with experiences that includes carousels, quick replies, emojis and conversation extensions. Messenger supports it all.


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

  • Text

    Full SupportAPI
  • Image

    Full SupportAPI
  • File

    Partial SupportAPI
  • Emoji

    Full SupportAPI
  • GIF

    Full SupportAPI
  • Location

    Partial SupportAPI

Action Types

  • Link

    Full SupportAPI
  • Extension

    Full SupportAPI
  • Buy

    Full SupportAPI
  • Postback

    Full SupportAPI
  • Reply

    Full SupportAPI
  • Location Request

    Full SupportAPI

Structured Messages

  • Compound Message

    Full SupportAPI
  • Carousel

    Full SupportAPI


  • Typing

    Full SupportAPI
  • Read

    Full SupportAPI
  • Conversation Start

    Full SupportAPI

Delivery Events

Delivery events allow you to track deliveries of Smooch messages to Facebook Messenger by subscribing to the message:delivery:channel webhook. Failures to deliver a message to Facebook Messenger can be detected by subscribing to the message:delivery:failure webhook.

The Facebook Messenger message IDs associated with each Smooch message are available in delivery event payloads in the externalMessages property.

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?

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!


This section describes a number of problems that commonly affect Facebook integrations and how to solve them.

Missing OAuth Permissions

During the OAuth flow described above, when presented with the authorization dialog, a Facebook page owner may select the “Choose what you allow” option to reduce the scope of access that is granted to Smooch. If this is the case, the integration may be in a broken state. Deleting and re-creating the Facebook integration may not resolve the issue because Facebook will remember the user’s chosen scope of access during subsequent OAuth flows. To resolve this issue, access must first be fully revoked from the Facebook dashboard Business Integration page.

Facebook User Password Reset

If a page owner changes their Facebook account password, Smooch’s access to that user’s pages will be invalidated. This means that while user messages will continue to be received by Smooch, the business will be unable to respond. Facebook unfortunately offers no automated way to refresh the page access token. The integration must be recreated in order to resolve this issue.

You can proactively detect this error case by subscribing to the message:delivery:failure webhook trigger. You will know a Facebook password change is the cause of failed message deliveries by observing an error.code of unauthorized with the following underlyingError.message:

Error validating access token: The session has been invalidated because the user changed their password or Facebook has changed the session for security reasons.

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


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.


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.


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, trying to send a payment request in a currency other than USD to a Messenger user 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.