Platforms: Facebook

At A Glance

Facebook Messenger bots launched in 2016 and has quickly emerged as a popular, fully-featured chatbot platform. Dexter bots for Facebook are built on top of the robust Messenger Platform part of the overall Facebook Developer and Pages ecosystem.

If all this looks scary and intimidating, or maybe you've even tried deploying a bot to Facebook before, don't worry! All of Dexter's platform configuration walkthroughs give you a step-by-step tutorial through in the configuration process so you don't have to worry about anything to do with coding or servers. Please also note all Messenger bots built on Dexter must comply with Facebook's messaging policies.

After you've followed our step-by-step platform configuration walkthrough on the Platforms tab of your bot's editor, read below for some pointers that ever Facebook Messenger bot creator should know:

Messaging Your Bot

There are several ways to reach your bot: from the your page on Facebook.com, searching for the page on the Facebook Messenger app, and by using the Messenger short url: https://m.me/PAGE_USERNAME.

Pro-tip: If you haven’t already, don’t forget to set a username for your Facebook page!

Messenger Bot Testers

Only certain people can interact with your Messenger bot prior to Facebook approving the bot and making it discoverable and usable by the general public. Add new test users by following the steps below:

  1. Find the Facebook app associated with your bot
  2. In your app's configuration page, go to Roles
  3. Add people to the Testers list (Developers or Administrators will also work—be sure to understand the elevated permissions you are giving them. They have to accept the invite to join the app, while Testers will be added automatically.)

Facebook roles

Approval of Bots

When you are ready for your bot to be accessible to the whole world, you need to go through Facebook's App Review process.

  1. Go to your Facebook app's configuration page.

  2. On the left sidebar, Click + Add Product and add Messenger.

  3. Next, click Messenger and scroll down to the App Review for Messenger section.

Facebook App Review

  1. Select which permissions you want to submit.

    • At a minimum, to have your bot respond to users, you must choose pages_messaging.
    • If you would like to send Broadcasts to your user, you must choose pages_messaging_subscriptions.
  2. Depending on which permissions, you select you need to fill out the associated notes before submitting your application.

    • If you select pages_messaging, you will need to provide a few sample user messages and expected bot responses.
    • If you select pages_messaging_subscriptions, you will need to provide a screencast of your bot with a simulated broadcast.
    • You may also need to add a Privacy Policy URL and an 1024 x 1024 App Icon to your Settings Page before submission.
  3. Submit and wait for approval. You can view your status on this App Review section of your app. Typically, this process will take 1-2 business days.

  4. After you receive approval, you must make your Facebook app live and available to the public. Toggle the switch to "Yes" in the App Review page:

Facebook App Review Public

Broadcasts

All broadcasts you send via Facebook must conform to their policies around messaging.

Facebook does not allow you to send advertisement or promotional messages. The bot must meet one of the following use cases: News, Productivity, or Personal Tracking. Learn more about Facebook's messaging policies here.

Best Practices

Add a “Send Message” button to your Page

To call attention to the existence of your bot from your Facebook Page, we recommend setting “Send Message” as your page’s primary CTA.

Facebook Send Message CTA button

User Names

The _userFirstName, _userLastName, and _userFullName data fields are automatically populated for use in Facebook bot responses. Learn more about available pre-populated namespace variables from Facebook.

+ hello
- Hi <get _userFirstName>! Thanks for messaging me.

Entry Points for Messenger Bots

There are few ways to reach your Messenger Bot, the most common of which are:

Referral Params

The aforementioned entry points allow bot developers pass in additional parameters that we capture in namespace variables for use in your bot script. Learn more about referral parameters here.


Troubleshooting

I am having difficulties deploying my bot on Facebook.

I can't deploy to my personal page.

Facebook won't let you deploy bots a personal page. To deploy a bot to a page, create a new business page on Facebook here.

I can’t find my bot in Messenger Search.

Bots are not discoverable to the general public until the app is approved. While in Development Mode, only Developers, Moderators, Administrators, or Testers can find the bot through search.

If your bot hasn't been messaged in a while, Facebook may unpublish your bot making it unavailable to the public. Visit your Facebook Page settings to re-publish any inactive Facebook pages.

I can't find my bot on my Facebook page.

The easiest way to find the bot for your Facebook page is to add a "Send Message" button as your primary call-to-action button.

My bot doesn't respond to a user.

I am seeing OAuthException: Code 2500 errors.

If you see an error message with "code":2500 when trying to deploy, double check that the Facebook Page that you're trying to use with Dexter is under your control. This error is sometimes surfaced when you aren't an admin of the Page.

I am seeing a "[Facebook Error: (#100) Message cannot be empty, must provide valid attachment or text]" error.

Facebook requires each response to include text. Make sure that your response includes text. This can be tricky if the given response has a combination of directions, topic redirects, or trigger redirects. Remember that <set> directions and topic redirects do not return text. Also, be careful about your use of multiple <send> and <delay> directions concurrently.

I am seeing a "[Facebook Error: (#100) Length of param message[text] must be less than or equal to 640]" error.

Facebook requires text messages to be UTF-8 and be shorter to 640 characters.

I am seeing a "[Facebook Error: (#10) Cannot message users who are not admins, developers or testers of the app until pages_messaging permission is reviewed and the app is live.]" error.

In order to authenticate and deploy a Messenger bot on Dexter, make sure you are either Admin or Editor on the Facebook page associated with the Page Id.

I am seeing a "[Facebook Error: (#100) Attachment size exceeds allowable limit]" error. Facebook is not rendering my image or video files.

There does not seem to be an official limit on image size. Keeping them under 10MB is advisable to keep the bot speedy. The max message attachment size is 25MB. In short, you shouldtry out your media files with your deployed Facebook bot to make sure they render well.

I want a Facebook Page username so that I can access my bot at m.me/PAGE_USERNAME instead of at m.me/PAGE_ID.

To be eligible to create a unique username for your Facebook Page, your page needs 25 page likes.