Connectors / Service / Facebook

The largest social network in the world. (updated: 1674203361374)

Facebook

Connect to Facebook and utilize marketing tools they provide.

Overview

The Facebook connector allows you to view adverts, list generated leads from ads as well as create and update custom audiences.

API Information

The Base URL used for the Facebook connector is https://graph.facebook.com/v15.0. More information can be found on their main API documentation (v15) site.

IMPORTANT!: The Facebook Marketing API is only available until the 25th of January 2023.

Users will need to upgrade to the latest connector version otherwise operations that deal with Adverts will fail.

Authentication

Within the builder, click on the Facebook connector to display the connector properties panel. Select the Auth tab and click on the New authentication button.

auth-sample

In the Tray.io authentication pop-up modal name your authentication in a way that will quickly identify it within a potentially large list. For example whether it is a Sandbox or Production auth, etc.

Consider who/ how many people will need access to this authentication when choosing where to create this authentication ('Personal' vs 'Organisational').

The next page asks you for your Client ID and Client secret credentials.

facebook-popup

Pre-requisites

PLEASE NOTE: When creating your Facebook Application you must first check if a webhook can be added before trying to sync it with Tray.io.

This is because the app type determines if a webhook can be added. Consumer, Business and Instant Games application types can all have webhooks.

For more information please see Facebooks App Types page.

IMPORTANT!: You must have a Facebook developer account before continuing your setup. More information can be found on the Facebook for Developers page.

IMPORTANT!: You need to either know how to create or already have an application setup within the Facebook developer portal before continuing.

Once you have confirmed the above points please make sure your application is setup correctly before continuing. This will mean it should have the following:

Setup

Select the Facebook trigger. This can be done at the create new workflow stage or updated within the workflow builder itself.

Highlight the Facebook trigger. In theFacebook trigger properties panel to the right of the builder click on the Authenticate tab and the Add new authentication button.

Once logged in head to the main Facebook App Dashboard. Either create a new application or select one.

Either way make sure that you have a Facebook Login product already added to your application. You have to click on this feature in order to navigate to the correct Settings option.

fb-settings

It is through this section that you will find the Valid OAuth Redirect URIs field. You will need to fill this in with Tray.io's OAuth 2 settings URI before continuing.

fb-redirects

To get the Tray.io's OAuth 2 settings URI head to Tray.io's app platform. Navigate through (within your Personal workspace) Services -> Add service -> OAuth 2 settings.

Tray.io OAuth 2 URI: https://auth.tray.io/oauth2/token

fb-tray-uri

Head back to your Facebook application's dashboard. In the left hand menu select the Add products option. Choose Webhooks.

Change your object type to Page - it will be set to User by default.

Once you are in the main Webhooks section click on the Subscribe to this object button.

fb-wbhk-2

Note that the Callback URL and the Verify Token has been setup for you on the Webhooks proxy repository already. So please use the following:

  • Callback URL: https://webhooks.tray.io/production/webhooks/facebook/2

  • Verify Token: facebook-trayio-test

fb-urls

After the subscription is verified your dashboard page should look similar to this:

fb-webhook-3

Next you will need to make sure you have subscribed to the leadgen option.

Do this by scrolling down and clicking Subscribe:

fb-leadgen

You will now need a Facebook page and lead generation form for your application.

Please follow the steps below for more details on how to do this if you don't already have one to use.

Head back to the application you are working on and select Settings from the left hand navigation bar. Choose Basic from the available options. You should be able to view your App ID and App Secret. Copy them.

fb-ap-id-etc

Head back to your Tray.io builder. Paste the application details into the authentication model within the Client ID (i.e. App ID) and Client Secret (i.e. App Secret) fields. Select the Scopes required.

facebook-popup

Once you have added these fields to your Tray.io authentication pop-up window click the Create authentication button. 

Your connector setup should now be complete.

Refresh Authentication

It's important to note that due to Facebook's authentication system Tray.io has to ask users who have created an authentication on the platform to re-authenticate regularly.

Tray.io will send an email to the owner of the authentication warning that the authentication will expire soon. To re-authenticate, a link will be provided that will take you to the authentication page.

facebook-email

Click on the URL and it will take you to this page:

back-to-facebook

From here, follow the same steps that were discussed in the Authenticating with Facebook section.

It is important to note that if re-authentication does not occur, the connector will fail after the authentication expires and workflows will be affected by this.

Facebook Trigger

The Facebook trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Trigger Operations available:

  • Subscribe to Lead Gen Ads

Webhook Setup

Select the Facebook trigger. This can be done at the create new workflow stage or updated within the workflow builder itself.

Highlight the Facebook trigger. In the Facebook trigger properties panel to the right of the builder, click on the Authenticate tab and the Add new authentication button.

This will result in a Tray.io authentication pop-up modal. The first page will ask you to name your authentication and select the type of authentication you wish to create ('Personal' or 'Organisational').

Follow the instructions above in the Authentication section to complete the first part of authenticating your trigger.

PLEASE NOTE: Once you have clicked the Create authentication button return here for the rest of your instructions.

Now that your authentication is complete set your operation to Subscribe to Lead Gen Ads.

You will need to make sure you also select your Facebook page (the one you just created / want to reference) from the drop down options available.

PLEASE NOTE: The list of available page options for you to choose from will come from your account as a whole.

This means if you have built other applications - which also have pages connected to them - they will display as well. The application specific credentials you originally used to authenticate with will not limit the number of pages you will be able to choose from.

This is because pages are tied to accounts and are not application specific.

fb-trigger

In order to verify your webhook is working Facebook have a dummy test page you can trigger.

Head to https://developers.facebook.com/tools/lead-ads-testing and make a test call.

fb-test-trigger

Your trigger authentication setup should now be complete.

If you still have issues with the trigger check the Alerts Inbox on the Facebook application dashboard incase Facebook has restricted the app call.  

Notes on using Facebook

Finding your Page ID

Many of the operations require a Page ID to reference before completing their call.

You can find this by heading to the Facebook Page you wish to use.

Go through to the Meta Business page and add the ID from the URL at the top.

fb-page-id-1

The ID you need will be located in the URL of the Meta Business page after /latest/home?asset_id=XXXXXXXX. For example:

fb-page-2

Facebook permissions

It is important to note that some operations within the connector are dependant on certain permissions that the signed-in Facebook user has.

For example, to use the List leads from ad operation, you will need to be page admin to access the lead data of an ad: https://www.facebook.com/business/help/766393076839635

If operations are not returning data you're expecting, check using the Facebook documentation that permissions are set up correctly.

Available Operations

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Example usage

List leads from ad

This example will walk through how to list leads from a given ad. The first step is to add the Facebook connector to the workflow.

To list leads from an ad, the id of the ad we want to query needs to be provided. To find this ID, the operation list ads in ad account can be used. This will return data about all ads that belong to an ad account.

To use this operation, select the List ads in ad account operation in the input panel.

select-list-ads

An ad account then needs to be selected, this dictates what ads are listed.

select-ad-account

The ID of the advertisement can the be collected from the result set manually, or JSONPaths can be used to get the data straight from the operation. Below the connector snake is used to retrieve the JSONPath:

snake-case

The input for the List leads from ad operation now looks like the following:

list-leads-input

The workflow is ready to be ran. Below you can see that the workflow ran successfully and leads have been listed from a given ad.

example-output

Creating a custom audience

This example will walk through how to create a custom audience. The first step is to add the Facebook connector to the workflow.

The Create custom audience operation then needs to be selected.

add-facebook

The first steps that will be taken will be to provide some information about the custom audience. This includes the ad account that this audience will belong to, a name for the audience, a useful description about the audience and the customer file source.

meta-data

The next step is to provide a population for this custom audience. This is done by adding audience member objects to the array of audience members.

Below you can see an example of an audience member object.

add-attributes

It is important to understand that if you did not want to include the same fields in every audience member object, you have to provide an empty string in the field you wish to leave out. An example below shows how in the next audience member, the Birth year attribute wants to be left out. Using the tooltip, an empty string can be set. This will prevent any errors from occurring when the workflow is run.

select-empty
empty-string

Now the custom audience has been defined, and the workflow is ready to be run. As can be seen in the image below, the workflow ran successfully and a custom audience has been created in Facebook.

successful-custom

All Operations

Latest version:

9.1

Create custom audience

Create a custom audience in your business account.

Create post

Create a new post.

Delete audience members

Remove members from a given audience.

Delete custom audience

Delete a custom audience.

Get ad

Retrieve an ad using its ID.

Get ad account

Retrieve an ad account using its ID.

Get ad account insights

Retrieve insights from a specific ad account.

Get ad insights

Retrieve insights for a specific ad.

Get adset

Retrieve an adset using its ID.

Get adset insights

Retrieve insights for a specific adset.

Get audience

Retrieve a custom audience.

Get business user

Retrieve a business user detail using ID.

Get campaign

Retrieve a campaign using its ID.

Get campaign insights

Retrieve insights for a specific campaign.

Get lead

Get data about a specific lead using their ID.

Get page insights

Get insights for a specific page.

Get post insights

Get insights for a specifc post.

Get user

Get data about the user signed in.

List ad accounts

List ad accounts associated with current user.

List ad accounts DDL

List ads in ad account

List ads in a given ad account.

List adsets in ad account

List adsets in a given ad account.

List business client ad accounts

List all client-owned ad accounts.

List business users

List all business users associated with this business.

List campaigns in ad account

List ad campaigns found in an ad account.

List custom audience ad accounts DDL

List custom audiences

List custom audience found in an ad account.

List forms in page

List leadgen forms owned by a page.

List leads from ad

List leads from a given ad.

List leads from form

List leads from a given form.

List pages managed

List the pages managed by the current user.

List pending users

List all users invited to access this business, who have not yet accepted their invitation.

List posts on page

Retrieve a list of posts associated with a specific page.

List saved audiences

List all saved audiences.

Raw HTTP request (advanced)

Perform a raw HTTP request with some pre-configuration and processing by the connector, such as authentication.

Targeting search

Retrieve target audiences for your ads that match your search query.

Update custom audience

Update a custom audience with a new population.

Update post

Update a post.