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.

Configuring Facebook Messenger

To use the Facebook Messenger integration, you need a Facebook account with permissions to manage a published Facebook page. You then need to visit the Facebook Messenger integration page and press on “Connect your Facebook account”. This will redirect you to Facebook where you will need to allow Smooch to access your account information.

Once your Facebook account is connected to Smooch, select the Facebook page you want to use 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.

Facebook Messenger Integration Page Settings

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