Connect your Facebook page

Follow these steps to subscribe a page to our messenger system, using the Facebook messenger API

Step-by-step guide

Before we start register the Facebook account of the administrator of the Facebook page you want to subscribe, as a Facebook Developer via the following link: https://developers.facebook.com/. This will prepare your account for all the next steps. After the set-up is completed you will need to provide the Social25 team with data that is generated throughout the set-up, we recommend to copy/past this template into a document so you can easily update it with the correct values whilst setting everything up.

We recommend to share the Page Access Token and the App Secret through our Password sharing tool which can be found here. This will provide the Social25 team with a one time available link to copy/paste the values. Please make sure to set the expiration to 7 days before sharing the details.

App Info	Page Access Token: copied in step 11 of the Generating Page Access Tokens section. Please use this tool to share this and set expiration to a week
	App ID: find it on the dashboard of the app
	App Secret: find it on the Settings > Basic page of the app, click Show next to the secret. Please use this tool to share this and set expiration to a week
	Webhook URL: The webhook URL you've linked the app to
Page Info	Page ID: see Get Page ID section below
	your page's URL for verification purposes. This should be in the format www.facebook.com/<page_id>

1. Create and configure a Facebook App

For the use of Social25 we ask you to create your own Facebook development app. If your organisation already has an app, make sure you get access to this app.

Why do I have to create my own Facebook app?

Social25 asks you to create your own app because of several reasons.

If you ever migrate to another platform you can reuse the app and the user ids in your Salesforce org will stay the same, making sure you never get duplicates.
You are in control of which permissions you request with Facebook and how much data provides Social25 besides the standard amount of data included with the pages_messaging permission.
You are capable of integration other apps or build bots using the handover protocol and maintain the app scoped ids of your users.

Creating a development app from a Facebook Business

If you do not have a Facebook Business, skip the following steps and expand "Creating a development app without having a Facebook Business" just below step 7.

Navigate to https://business.facebook.com and select the business you want to create the development app for.
Click on Business Settings, this button is located on the top right corner of the page.
Navigate to Accounts → Apps
Click on + Add
Select Create a new app ID
Under Audience, select Manage integrations for your business
Under Type, select Business
Enter a Display Name (For example "Social25 Integration")
Click on Create App ID

Once your app has been created make sure to add a web platform. This won't be used for anything but is required according to the Facebook platform terms.

From Facebook Business Settings, go to your App Dashboard
Navigate to Settings → Basic
Scroll down to where you see the button "Add Platform"
Click on "[Website]".
Enter the https URL to your website.
Click on "Add"
Click the blue-button "Save Changes" at the bottom

Creating a development app without having a Facebook Business

If you do not have a Facebook Business yet make sure to take into account that before your app can go live you will have to request the pages_messaging permission and business verification which can take up to several weeks. So prepare for that before planning your go-live date.

Navigate to https://developers.facebook.com/
Click on "My Apps" which is located on the top right corner of the page.
Click on "Create App"
Enter a Display Name (For example "Social25 Integration")
Click on "Create App ID"

What should I do if I have a DTAP environment?

If you have multiple stages in your development process and want to connect a separate Facebook Page to every stage we recommend to create multiple apps. For your test apps you do not have to request the pages_messaging permission, nor do you have to set the status of your test app to "In Production". Messages sent to pages linked to this app will only come into Social25 if the sender is a tester, developer or admin of the Facebook Development app. Later on in this document we explain you how to add other people to your app.

Setting up the Messenger Product and webhooks

After creating your Facebook Development app you will be redirect to the "Products" page of your Facebook app. From this page we will immediately add the Messenger product to the app and configure the webhook.

Search for the product called "Messenger" and click on "Set Up". (If you have already added the product navigate to the Settings page of the Messenger product.)
Scroll down to the section that has the header "Webhooks"
Click on "Add Callback URL"

Enter the following details:

Production	Production Callback URL	https://social25.herokuapp.com/v1/webhook/facebook/
	Production Verify Token	ogbfb1ckiiszmnsp5cdqcevabebef9mz
Sandbox	Sandbox Callback URL	https://social25-staging.herokuapp.com/v1/webhook/facebook/
	Sandbox Verify Token	5544612db8c4e0626147a136ca6de183

Acceptance

Acceptance

Acceptance receives releases before staging and can be used to test new functionalities of Social25 before we push the to Staging.

Callback URL	https://social25-acc.herokuapp.com/v1/webhook/facebook/
Verify Token	e4e9bb3c0eb94e7ea20a765ffce30d74

Click on "Verify and Save"
Your Webhooks are now configured and should look something like this.

Webhook Field Version Controls?
You might notice the section Webhook Field Version Controls. Social25 aims to keep the Facebook Messenger integration as up to date as possible. However, if you experience any unexpected issues while setting-up Social25 make sure to tell the Social25 team which version of the webhooks you're using. Make sure to keep the values of the webhooks consistent and don't randomly change the versions without testing in your testing environment first.

Generating Page Access Tokens

In this section we assume a page has already been created that will be linked to the development app.

Navigate to the Access Tokens section on the Messenger Settings page of you development app.
Click on "Add or Remove Pages".
Make sure you've allowed pop-ups and click on "Continue as <Your Name>"
Check the box that is shown behind the pages you want to connect
Click on "Next"
Verify that the "Manage and access Page conversations on Messenger" permission is checked.
Click on "Done"
Click on "OK"
Now you should see the page in the overview under Access Tokens.
Click on "Generate Token"
Copy/paste the token into the template that we provided at the start as you will have to share this value with the Social25 team.
Click on "Done".
You should now see "Token Generated" in the overview.
Once this is complete you can use the the information gathered and add this via the wizard. Add new social messaging channels

If you ever need to add any additional pages or regenerate tokens you can follow along with the steps from this section again.

Subscribing Pages to Webhooks

At this point everything has been configured and prepared for the connection to Social25. We recommend to send all details to the Social25 team first and wait until they have configured everything before actually subscribing pages to the webhook.

Navigate to the Webhooks section under Messenger > Settings in the menu on the left (NOT Webhooks directly in the left menu)
Click on "Add Subscription" next to the page you want to connect.
Select the following Subscription Fields:
Click on "Save"
You've now successfully linked your page to Social25!

If you ever need to add any additional pages to Social25 you can follow along with the steps from this section again.

Preparing for the pages_messaging permission

This pages_messaging permission is only required if you want to take your app Live. Taking your app live will allow anyone to send messages to linked pages. As long as your app is 'In development' only registered Testers, Developers and Administrators will be able to send messages to linked pages.

To prepare your app for requesting the pages_messaging permission you will need to configure some basic details in the Development app. This section explains several different steps that need to be taken before you can request permissions.

Configuring an App Icon

To be able to request the pages_messaging permission and set your app in production you will need to upload an icon to your app. This icon will never be displayed to the end user unless you're utilising opt-in techniques for your pages. We recommend to use a 1024x1024 icon of your own logo. If you prefer to use our icon feel free to do so, you can download it here:

You can upload this icon by navigating to your Facebook developer App. Open up Settings and click on basic. Here you can upload your image and click "Save Changes".

Configuring a Privacy Policy and Terms of Service

Facebook requires you to add a link to your privacy policy and your terms of service. These are required and will need to explain how you handle your customer data and how the customer support centre works. Social25 does not offer ready to use documents about how your service works, so make sure to include your own documents. Navigate to your Facebook developer App. Open up Settings and click on basic. Fill out the URL to the documents and and click "Save Changes".

Configuring Business Use

You need to explain how your business is using the Facebook Messenger app, since this Facebook app you've created will be used for your own customer service centre you need to make sure to mention that in the app. You can do this by navigating to your Facebook developer App. Open up Settings and click on Basic. Here you will find a field that says "Support my own business", click that and click "Save Changes".

Adding additional permissions

Facebook Messenger also requires you to activate the additional permissions to fully set up the integration.

Permissions that need to be enabled are:

Business Asset User Profile Access
public_profile
email

Adding people to your Facebook Developer App

If you want to give other people control over your app you can add them as a Developer or Administrator of your app. If you want to give people access to send and receive messages from the pages connected to the app without having set your app Live or having pages_messages permission, make sure to add them as registered Tester.

Adding people that are not part of the Facebook Business yet.

Navigate to https://business.facebook.com and select the business that owns the development app.
Click on Users → People .
Click on "Add" next to the word People.
Enter the email address of the people you want to add.
Click on "Next".
Click on Apps in the left side bar.
Select your app.
Select the roles you want to assign.
Click on Invite.

Assigning people that are already part of the Facebook Business.

Click on Accounts → Apps.
Select the app you want to add other people to.
Click on "Add People" this button is shown on the right hand side .
Select the person you want to add.
Select the roles you want to assign.
Click on Assign.

Adding people to your app without a Facebook Business

If you don't have a Facebook Business or want to manage people's access to the app directly from the app that is possible as well.

Navigate to https://developers.facebook.com and click on the app you want to add people to.
Click on Roles → Roles
Click on the corresponding button for which role you would like to add someone to.
Click on "Add <Role>"
If you're friends with the person you want to add on Facebook search for their name, if you're not friends ask that person to provide you with the canonical id. They can find their id by navigating to https://whatsmyfbid.com/ and entering their profile URL.
Enter the canonical ID or name of the person you want to add
Click on Submit (you are promoted to enter your password).

Get your Page ID

Go to your Facebook page
Click More and then About
Scroll down until the More Info section
Copy the Page ID

2. Verify your business (This section comes from the Facebook Documentation).

To be able to take your app Live, you will need to request business verification. This is only needed if the app has not been linked to an existing business that was not verified yet. The header includes a link to the most up to date version of the Facebook Documentation on how to request Business Verification. But we've also included the instructions in this section.

How to request Business Verification

You can start the business verification process and check the status in Business Manager. You may also see a "Start Verification" option in other places such as the app dashboard for app review. Although not every business needs to be verified on Facebook, you must be a verified business to access certain Facebook products and developer features. Learn more about business verification.

Note: Business verification is different from Page verification, individual verification and the verified badge on Instagram because it verifies your business, not you as a person. You won't receive a badge for business verification.

How it works
First, we'll try to auto-verify your business via our trusted third-party data sources. If we can locate your business, along with the business legal name, business address and business phone number or business email domain, we will ask you to confirm your association with the business. We'll send an automated message with a verification code to your phone number or email address. Then, enter the verification code as the last step in the auto-verification process.

If we're unable to auto-verify, we'll ask you to submit documentation proving your legal business name and business address or phone number.

If you use monthly invoicing to pay for ads on Facebook, you don't have to submit documentation for business verification. When you start the business verification process, you can fill in the form with your line of credit information and submit it. If you don't see that option, make sure that the Business Manager you are attempting to verify is linked to a line of credit that you own (not one that is shared with another business).

To start the verification process:

Go to Business settings.
Click Security Centre.
Find the Verification section and below Business verification, click Start Verification.
NOTE: The Start Verification button will be greyed out unless your business needs access to certain features. Learn more about business verification. Learn more about business verification.
Once you've started the verification process, you can check your verification status in this section.
Enter your business details and click Next.
Select the correct business from the list of suggestions or select None of these match if your business is not displayed.
Follow the prompts on your screen to confirm your business details. If you select None of these, you'll need to verify by submitting additional documentation. Learn how to submit additional documentation below.
Decide how you'd like to receive your verification code and choose Call Me Now or Send Email. Depending on your location, you may not have the option for verification via phone. You'll need to use the email option.
Enter your verification code.

Once you receive confirmation that your business is verified, you're ready to go!

Verification of legal business name

Upload documents that prove that your business is a legally registered business with official authorities.

Acceptable document examples	Unacceptable document examples
Business licence and permits from local, state or federal government Certificate of formation or incorporation Business Tax or VAT registration certificate EIN confirmation letter from the IRS (US only) Official tax notices from the IRS (US only) Business bank account statements Business credit report from one of the reporting agencies	Utility bill, e.g. phone or electricity bill (not acceptable for legal name; acceptable for address or phone) Invoices Purchase orders Self-filled applications for the company Tax returns filed by you or your company Personal bank statement Website print Other documents such as company flyers, letterhead etc.

Note: All examples are documents that are issued to your business proving that your business has been officially registered with the authorities in your country and/or state.

Verification of business address or phone number

Upload documentation that shows your legal business name and either the address or phone number.

Acceptable document examples	Unacceptable document examples
Utility bill, e.g. a phone or electricity bill Bank statement Business licences and permits from any level of government Certificate of formation or incorporation Business Tax or VAT registration certificate EIN confirmation letter from the IRS (US only) Federal tax returns to the IRS by company (US only) Business bank account statements Business credit report from one of the reporting agencies	Invoices Purchase orders Self-filled applications for the company Tax returns filed by you or your company Website print Other documents such as company flyers, letterhead etc.

To upload documents

Go to Business settings.
Click Security Centre.
Find the Verification section, and below Business verification, click Continue.
Follow the prompts on your screen to select your business.
Select None of these match.
Upload a standard official document that matches the legal business name that you previously entered and click Next.
Upload a document showing the legal name of your business along with the mailing address or phone number that you entered and click Next.
Decide how you'd like to receive your verification code and choose Call Me Now or Send Email. Depending on your location, you may not have the option for verification via phone. You'll need to use the email option.
Enter your verification code.
Monitor your business verification status in Security Centre.

If you receive confirmation of your submission, monitor your verification status in Business info. Businesses will typically hear back from us within five working days and in many cases, much sooner. Please note that this turnaround time doesn't necessarily mean approval. It means we will get back to you with the result of your submission, which could be approved or require more information.

3. Requesting pages_messaging permissions

One of the most important permissions you will need is the pages_messaging permission. Without this permission even if your app status is Live anyone who isn't a developer, tester or admin of your developer app their messages won't be submitted through the webhook.

Go to https://developers.facebook.com and navigate to your development app. This is the app that you created in step 2 of section 1 of this article.
Navigate to the Messenger > Settings.
Scroll down to the App Review for Messenger section.
Add the pages_messaging permission to your submission. This is done by the "Add to Submission" button.
Now scroll down to the "Current Submission" section. This will now tell you that details are missing from your app.
To complete the details needed for the pages_messaging permission click on "Add Details"
Check "I agree to Facebook's permission and feature usage guidelines."
Tell about the use case on how you will use Social25. If you are just adding servicing through service agents make sure to check "Involved business integration to support live chat by humans."
Select the page you want to connect.
Fill out in detail how a Facebook Employee might use the integration. This could be something like:
1. Go to our Facebook Page and send us a message
2. The message will be synced to our Salesforce Service Cloud where a case is created and assigned to a service agent.
3. As soon as a service agent is available they will answer your question. This will always be answered by a human agent. There are no bots anywhere in our process.
Now you need to show how the integration works. The best thing to do is to records your own video on how Social25 works in your Salesforce service cloud with the page you're trying to connect. Alternatively, you can use our video that shows how the product works:
Now click on save
Make sure there are no other requirements left for you to submit your request. If this is the case make sure to complete those steps first.
Now click on "Submit For Review"
Important: The Facebook Messenger review team will send you a message. It is very important to reply to this message as soon as possible from your Salesforce Service Cloud. Otherwise they will not approve your review.

Facebook

A lot of the information comes from the Facebook App Review guide (https://developers.facebook.com/docs/apps/review/). If you encounter any issues with the guide not matching the steps please refer to this guide and send us an email via info@social25.chat.