Send custom audiences to Meta Ads Manager¶

Note

This topic contains information about configuring a destination that sends query results to Meta Ads Manager using orchestrations. To configure a destination that sends audiences to Meta Ads Manager using campaigns see this topic .

Send custom audiences to Meta Ads Manager to help find people who already know about or have engaged with your brand. Use custom audiences for re-marketing, finding potential repeat customers, and finding lookalike audiences that can be activated from Facebook, Facebook Messenger, Instagram, and WhatsApp.

The Facebook Marketing API , specifically the Replace Users endpoint , is used to send custom audiences.

This endpoint removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets, and then replaces those users with the list of customers that was sent to Meta Ads Manager from Amperity.

Note

Changes to custom audiences are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending audience updates for them to be available.

Get details¶

Review the following details before configuring credentials for Meta Ads Manager and before configuring Amperity to send custom audiences to Meta Ads Manager.

Credential settings

Access token

Required

A refresh token is generated by the OAuth process and authorizes Amperity to send data to Meta Ads Manager. The value for the refresh token is updated automatically.

Meta Ads Manager settings

Account ID

The account ID for your Meta Ads Manager account.

Custom audience name (Required at orchestration)

The name of the custom audience in Meta Ads Manager.

Customer file source

A setting that describes how the information in the custom audience was originally collected. Select one of the following settings:

USER_PROVIDED_ONLY

PARTNER_PROVIDED_ONLY

BOTH_USER_AND_PARTNER_PROVIDED

About Meta Ads Manager¶

Audiences sent to Meta Ads Manager have access to Facebook, Messenger, Instagram and the Meta Audience Network.

	Use Meta Ads Manager to configure a variety of ad placements across Facebook .
	Use Meta Ads Manager to configure objectives that place ads on Instagram .
	Use Meta Ads Manager to configure objectives that place ads on Messenger .
	Use Audience Manager to reach users who are not on Facebook or Instagram, but are on mobile apps that are within the audience network. For example, creating ads that open conversation threads in WhatsApp .

Configure credentials¶

Configure credentials for Meta Ads Manager before adding a destination.

An individual with access to Meta Ads Manager should use SnapPass to securely share “refresh token” details with the individual who will configure Amperity.

To configure credentials for Meta Ads Manager

From the Settings page, select the Credentials tab, and then click the Add credential button.

In the Credentials settings dialog box, do the following:

From the Plugin dropdown, select Meta Ads Manager.

Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.

The settings that are available for a credential are determined by the credential type. For the “facebook” credential type, configure settings, and then click Save.

Access token

Required

A refresh token is generated by the OAuth process and authorizes Amperity to send data to Meta Ads Manager. The value for the refresh token is updated automatically.

Reauthorize Amperity¶

You may need to reauthorize access to Meta Ads Manager. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within Meta Ads Manager. To reauthorize access to Meta Ads Manager, follow the steps to configure OAuth and create a new credential.

Terms of service¶

The custom audience terms of service must be signed by each business user that is associated with your Meta Ads Manager account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Meta Ads Manager.

The permissions error is similar to:

Permissions error: To create or edit an audience with an uploaded
customer list, please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=123.

To resolve this error the terms of service must be signed by a business user who has a role in your Meta Ads Manager account.

Add destination¶

Use a sandbox to configure a destination for Meta Ads Manager. Before promoting your changes, send a test audience, and then verify the the results in Meta Ads Manager. After the end-to-end workflow has been verified, push the destination from the sandbox to production.

To add a destination for Meta Ads Manager

	Open the Destinations page, and then click the Add destination button. To configure a destination for Meta Ads Manager, do one of the following: Click the row in which Meta Ads Manager is located. Destinations are listed alphabetically and you can scroll up and down the list. Search for Meta Ads Manager. Start typing “meta”. The list will filter to show only matching destinations. Select “Facebook”.
	Select the credential for Meta Ads Manager from the Credential dropdown, and then click Continue. Tip Click the “Test connection” link on the “Configure destination” page to verify that Amperity can connect to Meta Ads Manager.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow users with limited access to PII access to this destination. Restricted PII access is enabled when the Restrict PII access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow.
	Configure the following settings, and then click “Save”. Account ID The account ID for your Meta Ads Manager account. Custom audience name (Required at orchestration) The name of the custom audience in Meta Ads Manager. Customer file source A setting that describes how the information in the custom audience was originally collected. Select one of the following settings: USER_PROVIDED_ONLY PARTNER_PROVIDED_ONLY BOTH_USER_AND_PARTNER_PROVIDED
	After this destination is configured: Use orchestrations to send query results Use orchestrations and campaigns to send audiences Use orchestrations and campaigns to send offline events

Workflow actions¶

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

	You may receive a notifications error for a configured Meta Ads Manager destination. This appears as an alert in the notifications pane on the Destinations tab. If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.
	On the Workflows page, review the individual steps to determine which step(s) have errors that require your attention, and then click Show Resolutions to review the list of workflow actions that were generated for this error.
	A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Meta Ads Manager, including: Authorization error Cannot create ads EXTERN_ID is missing Invalid credentials Maximum custom audiences exceeded Must agree to Facebook terms Must belong to business account Security challenge
	Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Authorization error¶

OAuth is an open standard for access delegation, commonly used to grant websites or applications access to information on other websites.

You may need to reauthorize access to Meta Ads Manager. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within Meta Ads Manager. To reauthorize access to Meta Ads Manager, follow the steps to configure OAuth and create a new credential.

Cannot create ads¶

The advertising account that is used by this workflow must have permission to create ads.

To resolve this error, update the user permissions in Meta Ads Manager to ensure that the advertising account can create ads.

Log into Meta Ads Manager and verify the user permissions for the account.
Update the user permissions to ensure that the Create and edit ads permission is assigned to the advertising account used by this workflow.
Return to the workflow action, and then click Resolve to retry this workflow.

EXTERN_ID is missing¶

An EXTERN_ID is a unique ID used within Meta Ads Manager, such as a loyalty ID, a customer ID, an external ID, or the Amperity ID.

Amperity will be unable to send orchestrations or campaigns when EXTERN_ID is not included within an audience that is sent to Meta Ads Manager.

For campaigns

To resolve this error, verify that EXTERN_ID is included in the list of attributes that are being sent to Meta Ads Manager.

Open the Campaigns page, and then open the segment used with this workflow.
Verify that EXTERN_ID is included in the list of attributes for each treatment group that sends audiences to Meta Ads Manager. Update the list of attributes for each treatment group if required.
Return to the workflow action, and then click Resolve to retry this workflow.

For orchestrations

To resolve this error, verify that EXTERN_ID is included in the query results.

Open the Queries page, and then open the query used with this workflow.
Verify that EXTERN_ID is included in the query results. Update the query if required.
Return to the workflow action, and then click Resolve to retry this workflow.

Invalid credentials¶

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Meta Ads Manager if required.
Return to the workflow action, and then click Resolve to retry this workflow.

Maximum custom audiences exceeded¶

Meta Ads Manager supports having up to 500 custom audiences in your account at any given time. Amperity will be unable to create custom audiences when this limit is exceeded.

To resolve this error, verify the number of custom-audiences associated with your Meta Ads Manager account.

Log into Meta Ads Manager and verify the number of custom audiences that are associated with your Meta Ads Manager account.
Remove custom audiences that are not in active use.
Return to the workflow action, and then click Resolve to retry this workflow.

Must agree to Facebook terms¶

The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Facebook Ads.

When the business user has not agreed to Facebook terms, an error similar to the following is shown:

Permissions error: To create or edit an audience with an uploaded customer list,
please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=1234567890123456.

To resolve this error, log into Meta Ads Manager as the business user associated with this workflow and agree to the terms of service.

Follow the instructions in the error message, and then open the provided link in a new tab.
Log in as the business user associated with this workflow, and then agree to the Facebook terms of service.
Return to the workflow action, and then click Resolve to retry this workflow.

Must belong to business account¶

The advertising account used to enable workflows to be sent to Meta Ads Manager from Amperity requires the advertising account to also belong to a business account. When an advertising account does not also belong to a business account, Amperity workflows will be unable to create or edit a custom audience.

To resolve this error, verify that the advertising account also belongs to a business account.

Log into Meta Ads Manager and verify the configuration for the advertising account to ensure that it also belongs to a business account.
Return to the workflow action, and then click Resolve to retry this workflow.

Security challenge¶

Sometimes Meta Ads Manager will issue a security challenge to the advertising account and/or business account associated with this workflow.

To resolve this error, complete the steps that are required to resolve the security challenge.

Log into Meta Ads Manager using the link provided in the workflow action, and then follow the instructions to resolve the security challenge.
Return to the workflow action, and then click Resolve to retry this workflow.

Facebook Marketing API keys¶

The following Amperity columns should be mapped to the corresponding Facebook Marketing API keys when they are present in query data:

Amperity Column	Facebook API Key	Description
Amperity ID	EXTERN_ID	This value is a unique ID used by the advertiser, such as a loyalty ID, a customer ID, an external cookie ID, or the Amperity ID. For this key, the connector trims leading and trailing whitespace. Tip A query can alias the Amperity ID directly in a query: SELECT amperity_id AS EXTERN_ID from custom_table. This approach can be helpful for queries that are dedicated to returning data to be sent only to Facebook Ads.
Email Addresses	EMAIL	For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Hashes data as SHA-256
Phone Numbers	PHONE	Converts each phone number to E.164 format which represents a phone number as a number up to fifteen digits in length (without spaces) that starts with a + symbol. For example: +12061234567. For this key, the connector: Trims leading and trailing whitespace Removes symbols, letters, and any leading zeros Hashes data as SHA-256
Gender	GEN	For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Converts to m and f Hashes data as SHA-256
Birth Date	BIRTH	The birth date in Amperity date format. For this key, the connector splits this value into three fields: birth year (DOBY), birth month (DOBM), and birth day (DOBD).
Birth Year	DOBY	Warning Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBY with a format of YYYY and a range from 1900 to the current year.
Birth Month	DOBM	Warning Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBM with a format of 01 to 12.
Birth Day	DOBD	Warning Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBD with a format of 01 to 31.
Last Name	LN	This key supports special characters and non-Roman alphabet characters. For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Removes punctuation Updates special characters to UTF-8 format Hashes data as SHA-256
First Name	FN	This key supports special characters and non-Roman alphabet characters. For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Removes punctuation Updates special characters to UTF-8 format Hashes data as SHA-256
First Initial	FI	Warning Do not pass this column. The connector will use the first character of the normalized first name.
US States	ST	A two-character ANSI abbreviation code for US states. For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Normalizes states located outside of the United States Removes punctuation, special characters, and whitespace Hashes data as SHA-256
City	CT	For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Removes punctuation, special characters, and whitespace Hashes data as SHA-256
Zip Code	ZIP	Use only the first five digits for the United States. Use Use postcodes (area, district, sector) format for United Kingdom. For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Removes whitespace from lower-case for United Kingdom Trims to five digits for United States Hashes data as SHA-256
Country Code	COUNTRY	A two-letter country code in ISO 3166-1 alpha-2 format. For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Hashes data as SHA-256
Mobile Advertiser ID	MADID	For this key, the connector: Trims leading and trailing whitespace Converts to lower-case Keeps hyphens Hashes data as SHA-256