Messenger Platform

 
 
 

Setup

When your app is in Development Mode, plugin and API functionality will only work for admins, developers and testers of the app. After your app is approved and public, it will work for the general public.

Requirements

To create a new Messenger Platform integration, you will need the following:

  • Facebook App: The Facebook App contains the settings for your Messenger Platform integration. This is where you will setup your webhook, retrieve your page access token, and submit your app for approval.

  • Facebook Page: A Facebook Page will be used as the identity of your bot. When people chat with your bot, they will see the Page name and the Page profile picture.

  • Webhook URL: We use secure callbacks in order to send you messaging events. These will be sent to your webhook.

1. Add the Messenger Platform to your app

Go to your app settings and under "Product Settings" add a product. Select "Messenger."

2. Setup your webhook

Webhooks are used to send you a variety of different events including messages, authentication events and callback events from messages.

In the Messenger Platform tab, find the Webhooks section and click Setup Webhooks. Enter a URL for a webhook, define a Verify Token and select message_deliveries, messages, messaging_optins, and messaging_postbacks under Subscription Fields.



3. Add verification code to your webhook

At your webhook URL, add code for verification. Your code should expect the Verify Token you previously defined, and respond with the challenge sent back in the verification request. Click the "Verify and Save" button in the New Page Subscription to call your webhook with a GET request.

Example (Node.js)

  app.get('/webhook', function (req, res) {
    if (req.query['hub.verify_token'] === 'YOUR_VERIFY_TOKEN') {
      res.send(req.query['hub.challenge']);
    } else {
      res.send('Error, wrong validation token');    
    }
  });

Read more details on these fields in the Webhook Reference for Messenger.

4. Get a Page Access Token

A Page Access Token is based on an app, page and user and has scopes associated with it. In the developer app, go to the Messenger tab. Select your page and generate a token:

This will generate a Page Access Token with the manage_pages, pages_messaging, and pages_messaging_phone_number scopes. Save this token as it will be used throughout your integration. You must be an admin on the page in order to generate a valid page access token.

These tokens are non-expiring. However, in rare cases, they may be invalidated. Read about debugging and error handling for these cases. You can also read more general details about page access tokens.

5. Subscribe the App to a Page

In order for your webhook to receive events for a specific page, you must subscribe your app to the page. You can do this in the Webhooks section under the Messenger Tab.

Or you can do this via API by using your Page Access Token and making a POST request to /me/subscribed_apps.

curl -X POST "https://graph.facebook.com/v2.10/me/subscribed_apps?access_token=PAGE_ACCESS_TOKEN"

If successful, you will receive a response:

{
  "success": true
}

6. Test your Bot

At this point in the setup you should have:

  • Created an App and a Page
  • Setup a Webhook
  • Generated a Page Access Token
  • Subscribed your App to your Page

Once you have completed these steps, you'll be ready to test your integration and receive messages sent to your Page.

To test you're receiving updates via the Webhook, simply send a message to your page. You can do that from your page on facebook.com, the Facebook mobile app, searching your page on Messenger, or using your Messenger short url https://m.me/PAGE_USERNAME.

If you don't receive an update via your Webhook, please ensure you didn't receive any errors when you setup your Webhook and you subscribed your App to your page.