Connectors / Service / Facebook
Overview
The Facebook connector allows you to view adverts, list generated leads from ads as well as create and update custom audiences.
Authentication
PLEASE NOTE: The Authentication process mentioned below can be used for Facebook connectorand Facebook Trigger Version 2.0. For the authentication process of Facebook Trigger version 1.0 ,refer to the Trigger Authentication section below.
Within the workflow builder, highlight the Facebook connector.
In the Facebook connector properties panel to the right of the builder, click on the Authenticate tab and the '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').
The next page asks you for your 'Client ID' and 'Client secret' credentials.
To get these credentials, you need to be registered as a Facebook developer and add Tray as an application in the Facebook developer portal.
To start the registration process while logged into your Facebook account, go to the Facebook for Developers website and click Get Started.
Click 'Next' to agree to Facebook's Platform Terms and Developer Policies.
Enter your phone number and verify your account using text message or phone call.
Select an occupation that most closely describes what you do for a living.
Now that you are registered, you can use the App Dashboard to create your first app.
To create the app, go to the Apps panel and click 'Create App'.
From the pop-up choose an app type that suits your application.
Enter the name of your app and an email address where you wish to receive important developer notifications. The email address can be different from the email address associated with your Facebook account. Once done click 'Create App'.
Re-enter your Facebook password to continue.
The next step is to add your app. Click the 'Set Up' button from the product with the name 'Facebook Login'.
You will be redirected to the 'Quickstart' page. From the left panel, click on the 'Facebook Login' link to expand the sub-menu. Click 'Settings' from the sub-menu.
The next step is to enter Tray.io's OAuth 2 settings URI. You can find this URI on Tray.io's platform by navigating to Services > Add service > OAuth 2 settings.
Add this URI https://auth.tray.io/oauth2/token in the 'Valid OAuth redirect URIs' field and click 'Save changes'.
Now you have successfully added Tray.io as an application. To get the Client Id and Secret for this newly created app, click Settings > Basic from the left panel.
On this page, you can get your credentials.
Copy and paste these credentials to your Tray.io authentication pop-up window.
You can optionally select the service permissions of your choice and then click the 'Create authentication' button.
You will then be redirected to a Facebook login page. Login with your Facebook account credentials and continue.
Facebook will then ask you to grant permissions for the scopes selected in the previous screen. Press the 'Continue as Connector' button to grant the permissions.
The authentication has been successfully created and the Facebook connector can now be used.
Select the recently added authentication from the dropdown options now available.
Your connector authentication setup should now be complete.
Refreshing 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.
Click on the URL and it will take you to this page:
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
Version 1.0
Within the workflow builder, highlight the Facebook trigger.
In the trigger properties panel to the right of the builder, click on the Authenticate tab and the 'New authentication' button. This will result in a Tray.io authentication pop-up modal.
Name the authentication. When choosing between the type of authentication you wish to create ('Personal' or 'Organisational'), consider who and how many people will need access to it.
As you can see, the next page asks you to select which scopes you would like to enable for your created authentication.
Once you have selected the desired scopes in the Tray.io authentication popup window, click on the 'Create authentication' button. Upon clicking 'Create authentication', you will be prompted to sign in to your Facebook account.
After you have logged in with your Facebook account, go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the dropdown options now available.
Your connector authentication setup should now be complete.
Version 2.0
The Authentication process for Facebook Trigger version 2.0 is the same as the Facebook connector Facebook Connector Authentication.
Facebook leads ad trigger
The Facebook leads ad trigger allows a user to receive a notification whenever a lead has been generated on a page. The trigger uses it's own authentication and has a different process than that of the connector. To create authentication for Facebook trigger, refer to the Trigger Authentication section above.
Below is a guide on how to use this trigger:
Select the Facebook leads ad trigger from the selection when creating a workflow.
Authenticate the trigger and select the operation as 'Subscribe to Lead Gen Ads'.
Select a Facebook page of your choice from the available drop-down options, for which you wish to fire this trigger.
Once the page has been selected, 'Enable' the trigger
Notifications sent by Facebook contain only the ID of the lead that was created. To get all associated data about the new Lead, you can use a core connector in the nest step with operation set to Get Lead. This operation retrieves all information about a Lead from a given ID.
Notes on using Facebook
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.
An ad account then needs to be selected, this dictates what ads are listed.
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:
The input for the List leads from ad operation now looks like the following:
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.
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.
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.
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.
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.
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.
