Introduction
When using the Facebook API to retrieve leads directly from Facebook, the app that you use to create this connection needs to be approved by the Facebook team before you can begin activity. This is a compliance requirement from Facebook themselves.
Prerequisites
- Your Facebook Business page being used to create forms must be verified.
- Your app should be created and configured through the process described here.
- You will need a video showcasing how you intend to use the Facebook app. (Previously this was provided by Convertr, but Facebook have adjusted their review to only accept unique videos for your use case, and will reject a video if they find it has been used for another app.) This should include an in platform view of the process.
- You will need to create a test user account in your platform. This is so that Facebook can log in and confirm the app's functionality. We recommend setting up a test campaign within a test advertiser, with a test publisher assigned. You can then create an agency user for Facebook and assign them to this campaign. This will ensure that they don't have access to other data in your platform.
Approving Your Facebook App
1. Go to https://developers.facebook.com/apps, login with your account and select your created app:
2. Click App Review.
3. Select Requests, then select Request Permissions or Features.
4. You will be shown a list of permissions. All permissions have a Action column value of Request advanced access. You will need to click this for the following permissions:
- public_profile
- pages_show_list
- pages_manage_ads
- pages_read_engagement
- leads_retrieval
Once selected, click Continue Request.
5. On the next page, you should already have the first step completed via the app creation process. The review will now have several questions about each of the permissions you are requesting. You will see answers you can provide below.
Click Provide verification details to begin.
6. In the textbox, input the following:
Email: {email used on test account}
Password: {password used on test account}
1) Click Connected Apps on the left sidebar. Click Facebook directly below it.
2) In the top left, click the Add Facebook Connection button
3) In the field labeled Facebook App ID*, input the Facebook App ID.
4) The ‘Log in with Facebook’ window will pop up. Sign into your Facebook account.
5) When it asks you which pages you would like to use, select the page that is hosting the forms you would like to connect.
6) On ‘What is [Facebook App Display Name] allowed to do?’, enable leads_retrieval, pages_manage_ads and pages_read_engagement.
7) Once ‘You've now linked [Facebook App Display Name] to Facebook’ has loaded, select OK. You will be redirected back to the previous browser window.
8) New fields will appear in the Add Facebook Connection; use the following information to complete the window:
Facebook App Secret: [input Facebook App Secret]
Facebook Form: [Select Facebook Form - this is pulled directly from Facebook if the permissions are correct]
Campaign: Select "44040 - Forcepoint Intl. Q1 Content Syndication Integrate Template: Cloud (Test)"
Publisher: Facebook
Form: Select from dropdown
Link:
9) Hit Save to create your connection. Convertr will now retrieve leads from Facebook and process them to deliver to a configured CRM system. You can use the Import all Data button on the right to retrieve all lead data linked to your form.
10) Submit a test lead from Facebook and this will appear in Convertr within 5 minutes.
Then hit save.
7. You will now see options for all requested permissions.
In the textboxes for each, see below. Where a video is required, please use the video you created.
- pages_manage_ads
This level of permissions is a prerequisite to get leads_retrieval, which we require as stated in that section.
With pages_manage_ads, we host ads on their company page to promote their products, which link to a lead gen form. This page access is required in order to retrieve leads that come through from that page's ads.
As shown in the video, when you log into Facebook you are required to give page access. As part of our UX, and to ensure the right form is connected, once Page access is given, our Facebook Form dropdown queries the page that has been given permission via the app connection which allows us to pull all available forms directly from Facebook's API, so our users can easily select the lead gen form they would like to connect.
- pages_show_list
This level of permissions is required as a prerequisite for page_manage_ads, which itself is a prerequisite for leads_retrieval.
As you will see in the video, when connected to Facebook you need to select which pages you would like the app to have access to for us to query the lead gen forms.
- pages_read_engagement
pages_read_engagement is a requirement to retrieve all lead data from Facebook forms as shown here: https://developers.facebook.com/docs/marketing-api/guides/lead-ads/retrieving/
We are requesting this as part of our build to retrieve this data from Facebook. We use this permission to retrieve leads from Facebook.
- leads_retrieval
Convertr is a data management and delivery platform that processes lead data on behalf of a client and submits it to their CRM system.
We use Convertr to collect lead data into our database, where we verify the details provided, apply any rules or criteria for a lead generation campaign and also add any additional metadata required to a lead.
Once this is done, we class a lead as valid or invalid, and submit the lead to our clients if they have been verified.
Sometimes we use Facebook to generate leads - the leads_retrieval permission will allow us to automatically retrieve the lead generated from a lead ads form, and process it through Convertr who have built out an API connection to Facebook to collect data before automatically submitting it to their database, removing the need for people to manually extract the leads and work in spreadsheets, which is not very compliant.
The leads_retrieval permission is crucial to this, as the primary function of the platform is to collect lead data for processing and delivery. We use this permission to retrieve the leads.
This will also enhance the end user's experience, where clients will be able to action leads faster due to the real-time delivery nature of Convertr. In this case, we or our clients will be able to reach out to the user regarding the content they have accessed.
1. The user will submit a lead via the facebook form
2. The Facebook platform will store this data
3. The app will then require access to enable the lead data to transfer to the Convertr
platform
4. Convertr will process the lead data and route to the end client CRM
The video attached in other permissions requests shows how the connection is established in our platform, along with why the permissions are required. This connection, when created, enables API delivery into our platform from Facebook.
8. You will now be able to submit for Review at the bottom of the page. Facebook typically take around 5 days to approve a request. Following the above should not lead to rejection, but you have any questions then please raise to the Convertr Support team.