Facebook Custom Audiences

Empower your marketing team to run highly granular retargeting and lookalike campaigns on Facebook

Overview

Deliver even more relevant ads by combining data from various sources within your data warehouse to build custom audiences for Facebook Ads. By keeping your custom audiences updated automatically, never show an ad to someone after they purchase the item you were promoting.

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Connect to Facebook Custom Audiences

Go to the Destinations overview page and click the Add destination button. Select Facebook Custom Audiences and click Continue. You can then authenticate Hightouch to Facebook Custom Audiences either with a system user token or with OAuth.

Since the OAuth flow requires you to manually refresh this connection every 60 days, we strongly recommend using a system user token for indefinite access.

Authenticate with a system user token

When authenticating with a system user token you can choose to either use an existing one or create a new one for the Hightouch integration. To use an existing system user token, you must meet the following prerequisites:

• The system user whose token you'd like to use has Admin access.
• You've created an app to add as an assigned asset to the system user. For detailed instructions, see steps 1 - 3 from creating a new system user token.
• You've assigned the ad account that you want to create audiences for to the system user. For detailed instructions, see step 5 from creating a new system user token.

If you haven't met these prerequisites, follow the instructions for creating a new system user token.

Create a new system user token

To create a new token, you first need to add a new app.

1. Open your Facebook Business account and navigate to Business Settings > Accounts > Apps.

2. Use type None, name your app, then click Create app.

3. Make sure the app has Ads Management Standard Access permissions. You can find this setting in App Review > Permissions and Features.

4. Navigate to Business Settings > Users > System users and add a new system user with Admin access.

5. Use the Add assets button to assign both the app you created and the ad account that you want to create audiences for to the system user. Be sure to give both the app and the ad account Full Control, not Partial Access.

6. Once a new system user account is created, select Generate new token. When prompted, select the relevant app and the ads_management permission, then click Generate token.

7. Copy the generated token. Since this token won't be stored in Facebook, you may want to consider storing it in a secure password vault as well.

8. Back in Hightouch, select Use system user token as the Authentication method, then paste the token you generated as the System User Token, select the relevant Ads Account, and click Continue.

Use an existing system user token

If you already have a Facebook app and system user setup, open your Facebook Business account and navigate to Business Settings > Users > System users.

1. Select the system user you'd like to generate a new token for.

2. Select Generate new token. When prompted, select the relevant app and the ads_management permission, then click Generate token.

3. Copy the generated token. Since this token won't be stored in Facebook, you may want to consider storing it in a secure password vault as well.

4. Back in Hightouch, select Use system user token as the Authentication method, then paste the token you generated as the System User Token, select the relevant Ads Account, and click Continue.

Authenticate with OAuth

For the Authentication method, select Log in to Facebook and log into your Facebook account.

Once successful, you will be redirected back to Hightouch to enter a descriptive name for your destination and complete setup.

Sync configuration

Once you've set up your Facebook Custom Audiences destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Facebook Custom Audiences destination you want to sync to.

Syncing custom audiences

Hightouch lets you create and maintain custom audiences via the Facebook Custom Audience API. Each sync adds new users and updates existing users' identifiers you include in record matching. You can remove users that leave your model's query result by selecting this option in the sync's delete behavior.

Select an existing audience or create a new one

You can create a new audience or use an existing one. When creating a new audience, you can optionally enter a name; otherwise, Hightouch defaults to the name of the associated model. To use an existing audience, select the desired audience from the dropdown.

User identifiers

To identify which users to add or update in an audience, select model columns and the corresponding Facebook Custom Audience fields. You can match on default, custom, and Facebook-specific fields.

Facebook-specific fields include:

• External ID: a custom identifier that you send to Facebook via its APIs or tracking pixels
• Page-scoped ID: an ID used for Facebook messenger apps and Facebook pages

To increase the match rate for your records, include as many fields as possible.

Value-based audiences

If you're creating a new Facebook Audience, you can create a value-based audience by mapping a numerical model column containing lifetime values to the Lookalike Value field.

You can then create a lookalike audience in Facebook that finds the people most similar to your highest value customers. For more information refer to Facebook's docs.

Handling PII and hashing

By default, Hightouch automatically hashes the following fields before sending requests to Facebook:

• Email
• Phone
• Gender
• First Name
• Last Name
• First Initial
• State
• City
• Zip Code
• Country

You can disable this behavior in the sync configuration. If disabled, the data from the model should be appropriately normalized and hashed according to Facebook's hashing requirements.

Share your audience

Optionally share this audience with another Facebook advertising account.

Delete behavior

You can choose how to handle user records in Facebook when the corresponding rows are deleted in your source.

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

Custom Audience Terms not yet accepted

The full error message is:

An error occurred when creating the audience. Facebook Custom Audiences API returned error with code 400: Custom Audience Terms not yet accepted: You'll need to agree to the Custom Audience terms before you can create or edit an audience or an ad set. See Facebook, Custom Audience Terms.

To resolve this error, go to Audiences in your Facebook Ads Manger account and click Create a Custom Audience to create a list a manually. This prompts the Terms of Service to appear so you can agree to them.

You can also go to https://business.facebook.com/ads/manage/customaudiences/tos/?{ACCOUNT_ID} to accept the Terms of Service for each ad account that you want to use. Replace {ACCOUNT_ID} with the ad account ID in act_xxxx format.

Once you've accepted the Terms of Service, rerun your sync with the error.

Error Code 400: Missing schema attribute in payloads

By default, Hightouch automatically hashes certain fields before sending them to Facebook. The error occurs when Hightouch attemps to hash a null value or null values are being sent to Facebook.

To resolve this, remove rows containing null values from your model's query results or enable the Don't sync null values option in the advanced mapper.

Unsupported post request. Object with ID 'undefined' does not exist

This error occurs if you don't select an Ad Account on the destination configuration page. Make sure to follow the destination setup procedure outlined in the Connect to Facebook Custom Audiences section.

401 - Error validating access token

As explained in the Connect to Facebook Custom Audiences section, authenticating with OAuth requires you to reauthorize your destination every 60 days. Otherwise, your syncs fail with this error message.

400 - (#100) unsupported get request

The full error may look like: 400 - {"error":("message":"(#100) Unsupported get request. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api {...}.

This error usually happens when one or multiple Facebook pages that were granted access to the system user have age restrictions or country restrictions enabled. To resolve the error, edit your system user to remove all pages that have these age or country restrictions. Otherwise, you can edit the page settings to remove the restrictions from these pages.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.