Rate this page:

Facebook Messenger Quickstart

Twilio is launching a new Console. Some screenshots on this page may show the Legacy Console and therefore may no longer be accurate. We are working to update all screenshots to reflect the new Console experience. Learn more about the new Console.

Facebook has recently opened an API to Messenger that you can use to send messages to users. We bring this new, exciting channel into the Notify product to make it easier for you to reach your customers where they already are. Let's see how to do it.

Create a Facebook page and an app

If you already have a Facebook page or an app you can skip the respective steps.

The first things you need in order to send a notification is a Facebook page and an app. You can create a page in the top right corner of your Facebook profile.

Create a new Facebook Page

Next we need to create an app for this page. Open the Facebook Developer portal and create a new app or select an existing one.

Create a new Facebook app

Select Website and Skip the rest of the quick start by clicking the button in the top right corner.

Skip Facebook app quick start

Take a note of your App ID, we will use it later.

Facebook app id

Next add Messenger as a product to your app by clicking Add product on the left hand side menu and select Messenger.

Facebook app add product

Generate a Facebook access token by selecting your Facebook page in the Token Generation section.

Generate Facebook access token

Take note of your Access Token you will need it soon.

Add pages_messaging permission request to your submission. You do not need to submit your app for review but you do need to add this request to your configuration.

Add pages_messaging permission

We are done for now with setting up Facebook. Let's go over to Twilio and continue setting up there.

Create a Facebook Messenger configuration

Open the Channels Catalog in the Twilio Console.

Select Facebook Messenger.

Click Install.

Click Install

Agree to the Terms and Conditions.

Under Credentials Select the Facebook page you want to use from the drop down menu. If you do not see your facebook page that you just created, click the Logout button on the Console page to logout Twilio from Facebook and then log back in again to Facebook.

Select a page

Click Save at the bottom of the page and you have connected your Twilio account to Facebook Messenger.

Create a Notify Service

In the console, create a Notify service. Make note of the SID! You will use this later when you start writing code (don't worry, that's what we'll do next).

Twilio Console - Notify service creation

When creating the service configure it to use the Facebook Page you just configured for sending messages and save.

Configure the Notify Service

Now we're ready to write some code!

Create a webpage for registering users

We will create a single webpage that will have the Send to Messenger button on it. When the user clicks the button Facebook will call a webhook of ours and we will create a Binding in Notify to store the user id of the user. This is one of the many ways to acquire user consent for sending Facebook messages.

A Binding is a combination of a user and device that can receive a notification. For Messenger notifications, all you'll need is a user's user id to create a binding for them.

Important note: If your app is not yet approved for using Messenger (most probably the case) then you will need to be logged in to Facebook and be an admin, developer or tester of the app to see the button.

To get you going quickly, we've created a Node.js app that does the job.

You can browse the source code on GitHub as well.

Unzip the app you just downloaded, and navigate to that folder in a Terminal window on your Mac. You'll need to install Node.js if you haven't already, you can do that here. Now, we just need to configure and run the app. In the terminal, copy the .env.example file to .env. Edit the .env file to include your configuration parameters: - Twilio Account SID and Auth token can be found in the Twilio console. - Twilio Notify Service SID can also be found in the console.

Furthermore you also need to enter your own app id and page id in the public/notify/facebook-messenger.html file.

// You can find your app id in the Facebook Developer console
// The easiest way to find your page id is by looking in the Twilio console

  appId: "<YOUR-APP-ID>",
  xfbml: true,
  cookie: true,
  version: "v2.8"

<div class="fb-send-to-messenger"

Now we'll want to install our dependencies:

npm install

Once we've done that we're ready to start the server - again in your terminal, run:

npm start

To confirm the server is running, visit http://localhost:3000 in a web browser. You should see a brief message indicating the server is running.

However in order for Facebook to be able to validate our service, we will need to make it available on the Internet. We recommend using ngrok for that.

Complete Facebook app configuration

Now that we have the server up and running we can complete our Facebook app configuration by adding our server as the webhook destination.

Setup a webhook to complete your Facebook Messenger registration.

Copy the access token generated before to the clipboard.

Click Setup Webhooks and complete the form.

Paste your access token to the Verify Token field.

Use "<YOUR SERVER>/messenger_auth" as the Callback URL.

Select "messaging_optins" and click Verify and Save.

Setup Facebook webhook

Finally make sure to subscribe your new webhook to the page that you just created.

Subscribe Facebook webhook to page

Now you are ready to test your new website that collects people's consent for receiving Facebook Messenger messages.

Open https://<YOUR SERVER>/notify/facebook_messenger.html in your favourite browser and click Send to Messenger.

You should see in your server's logs the webhook request from Facebook and the Binding resource created in Twilio. Take note of the identity attribute of the Binding. You can use that to send notifications to it. In the sample app we have set it up so that it uses the Facebook user's id. Please do not use any personal information (such as name, email address, phone number) for the user identity in your application.

Now that we have a binding, all we need to do is send a notification!

Send a Notification

To send a notification we simply make a request to the Twilio Notify REST API with the content of the notification we wish to send and the identity. In our case this is the id of the Facebook Messenger user we want to target. No database queries or state management on our end - w00t!

You can use the /notify/ page in the web application to send a message to this user. Just use the numeric Facebook messenger user id as the identity in the text box. To get that id, check the logs of your server application, it will be part of the binding.

You will get a Facebook messenger notification from your page with the hardcoded 'Hello World!' message!

You're all set! From here, you can start building your own application.

Final notes

There are other ways you can use to acquire a user id, like by receiving a message first from a user. Check out Facebook's guide on entry points to learn more.

Also there are few terms and conditions you need to adhere when engaging users via Facebook Messenger. Please, check out the platform policy before submitting your application for review.

Finally, there's much more you can do with Notify, like alerting users on different kinds of devices or notifying a segment of your users in a single API call.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more