Skip to main content

Facebook Messenger

Connect your Facebook Pages, send and receive messages from Facebook’s 1.3 billion users.

This document provides a step by step guide to integrate Facebook with your Airy Core Platform instance.

What you will learn
  • The required steps to configure the Facebook source
  • How to connect a Facebook page to Airy Core
note

The Facebook Messenger source is not enabled by default.

You need to add configuration in your airy.yaml file and apply it to activate it.

Configuration#

The Facebook source requires the following configuration:

Let's proceed step by step.

Step 1: Find the App ID and Secret#

To connect a page, you must have an approved Facebook app. If you don't have one, you must register and create a Business app on Facebook for Developers.

All of your registered apps are listed on developers.facebook.com/apps.

Facebook apps page

The dashboard of each registered app can be found on:

https://developers.facebook.com/apps/INSERT_YOUR_APP_ID_HERE/dashboard/

On your application's dashboard, note down the App ID of your application and then head to the Basic Settings page.

https://developers.facebook.com/apps/INSERT_YOUR_APP_ID_HERE/settings/basic/

You will find your App Secret on this page:

Facebook apps page

Copy and paste your App ID and App Secret as strings next to appId: and appSecret:, below components/sources/facebook in your airy.yaml file.

note

Refer to the Configuration Docs on how to input these values.

Step 2: Configure the webhook integration#

Facebook must first verify your integration with a challenge to start sending events to your running instance. To verify your Facebook webhook integration, set the value next to webhookSecret:, below components/sources/facebook in your airy.yaml file, to a value of your choice.

You are now ready to configure the webhook integration. Click on the + icon next to "Products" on the left sidebar of your app's dashboard: scroll down, a list of products will appear.

https://developers.facebook.com/apps/INSERT_YOUR_APP_ID_HERE/dashboard/#addProduct

Click on the button 'Set Up' on the Webhooks product card.

Facebook webhook add product

This will add the Webhooks as one of your app's products and will lead you to the Webhooks product page.

https://developers.facebook.com/apps/INSERT_YOUR_APP_ID_HERE/webhooks/
Facebook webhook

Select 'Page' from the dropdown (the default is 'User') and click on the button 'Subscribe to this object'.

This will open a modal box: add your Callback URL (your instance's Facebook Webhook URL) and Verify Token (the webhookSecret you added in your airy.yaml file in the previous step).

Facebook webhook
note

Your Facebook Webhook URL should have the following format:

https://your-public-fqdn/facebook

or if you are using Ngrok:

https://RANDOM_STRING.tunnel.airy.co/facebook

If you encounter errors, please make sure that the Verify Token matches the webhookSecret in your airy.yaml file and that your variables have been successfully set to your Airy Core instance.

note

Refer to the Configuration Docs on how to input these values.

Once the verification process has been completed, Facebook will immediately start sending events to your Airy Core instance.

Step 3: Obtain the page token#

Go to the Products page (click on the + icon next to Products on the left sidebar).

Click the 'Set Up' button on the Messenger product card.

https://developers.facebook.com/apps/INSERT_YOUR_APP_ID_HERE/dashboard/#addProduct
Facebook messenger product

This will add Messenger as one of your app's products and will lead you to the Messenger product page.

Notice that at the bottom of the page, the Webhooks product has been added with the variables you gave at the previous step.

Facebook messenger product

Click on the blue button 'Add or Remove Pages' and select your page.

Once your page has been added, scroll down and click on the button 'Add Subscriptions'.

Facebook page subscriptions

This opens a modal box: tick 'messages' and 'messaging_postbacks' from the Subscription Fields list.

Facebook page subscriptions

Next, scroll up, and click on the button 'Generate Token'.

Facebook page token

This will open a pop-up revealing your page Access Token. Copy it, you will need it to connect the Facebook page to your instance.

Facebook page token

Success! You are now ready to connect a Facebook page to your Airy Core instance 🎉

Connect a Facebook page to your instance#

There are 2 options to connect a Facebook source to your instance:

  • you can connect the source via an API request (using curl or platforms such as Postman)
  • you can connect the source via the UI

We cover both options in this document.

Connect a Facebook source via API request#

The next step is to send a request to the Channels endpoint to connect a Facebook page to your instance.

Channels endpoint

Connect a Facebook source to your Airy Core instance through the Channels endpoint


Connects a Facebook page to Airy Core.

POST /channels.facebook.connect
  • page_id is the Facebook page ID
  • page_token is the page Access Token
  • name is the custom name for the connected page
  • image_url is the custom image URL

Sample request

{
"page_id": "fb-page-id-1",
"page_token": "authentication token",
"name": "My custom name for this page",
"image_url": "https://example.org/custom-image.jpg" // optional
}

Sample response

{
"id": "channel-uuid-1",
"source": "facebook",
"source_channel_id": "fb-page-id-1",
"metadata": {
"name": "My custom name for this page",
// optional
"image_url": "https://example.org/custom-image.jpg"
}
}
note

If you encounter errors, please follow this debugging advice:

  • Make sure the credentials you have added to the airy.yaml file (refer back to step 1) have been applied to your Airy Core instance.

  • Verify your webhook integration (refer back to step 2). Make sure your Facebook Webhook URL has been correctly added on your app's dashboard. You should edit the 'Page' subscriptions for the Webhooks and Messenger product each time you create a new instance. Make sure that you have selected 'Page' subscription and not 'User' (which is the default).

Connect a Facebook source via the UI#

You can connect a Facebook source via your Airy Core instance UI.

On your instance's Airy Core UI, click on 'Channels' on the left sidebar menu and select the Facebook channel. Add your Facebook Page ID and Page Access Token in the respective fields. You can optionally add a name and an image.

Facebook connect

Your can find your Facebook Page ID and Page Access Token on your app's dashboard on Facebook For Developers: the Facebook Page ID is the ID of the page you want to connect and the Page Access Token is generated on the Messenger product section (refer back to the previous steps).

Make sure the variables have been successfully applied to your instance, otherwise you won't be able to connect the Facebook channel through the UI.

note

Refer to the Configuration Docs on how to input these values.

Send messages from a Facebook source#

To test this you can now send a message to Facebook page.

Once a conversation has been successfully created, you will be able to send messages through the Messages endpoint.

Messages endpoint

Send messages to your Airy Core instance from different sources through the Messages endpoint


Sending a text message

{
"conversation_id": "a688d36c-a85e-44af-bc02-4248c2c97622",
"message": {
"text": "Hello World"
}
}

Send and receive messages with the Inbox UI#

Now that you connected this source to your instance and started a conversation, you can see the conversations, messages, and templates in the Airy Inbox, and use it to respond to the messages.

Inbox

Receive messages from different sources and send messages using the Inbox UI

Last updated on