Engagement Custom Audiences

Build audiences based on people who engaged with your content on Facebook or Instagram. Currently supported audience types include Page, Instagram business profile, Lead ad, and Canvas ad. This describes the API by using Page engagement audiences as an example.

Facebook updates your custom audience for page engagements by continuously adding people that engage with your page. When you first create this audience, Facebook prefills it with a list of people who already engaged with your page in the given retention period. You need advertiser permissions for a Page to create an Engagement audience.

Create an Audience

To create an Engagement Custom Audience your ad account must accept the Terms of Service for Custom Audiences, in Ads Manager.

Note: You don't need to specify the subtype to be 'ENGAGEMENT'; Facebook can infer it from the rule parameter.

To create an audience listing people who engaged with your page based on the page_engaged event:

curl -X POST \ -F 'name=My Test Engagement Custom Audience' \ -F 'rule={"inclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<PAGE_ID>","type":"page"}],"retention_seconds":31536000,"filter":{"operator":"and","filters":[{"field":"event","operator":"eq","value":"page_engaged"}]}}]}}' \ -F 'prefill=1' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/act_<AD_ACCOUNT_ID>/customaudiences
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdAccount = adsSdk.AdAccount; const CustomAudience = adsSdk.CustomAudience; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My Test Engagement Custom Audience', 'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, 'prefill' : '1', }; let customaudiences = (new AdAccount(id)).createCustomAudience( fields, params ); logApiCallResult('customaudiences api call complete.', customaudiences);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\CustomAudience; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My Test Engagement Custom Audience', 'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<pageID>','type' => 'page')),'retention_seconds' => 31536000,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'page_engaged'))))))), 'prefill' => '1', ); echo json_encode((new AdAccount($id))->createCustomAudience( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount from facebookads.adobjects.customaudience import CustomAudience from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My Test Engagement Custom Audience', 'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, 'prefill': '1', } print AdAccount(id).create_custom_audience( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCustomAudience() .setName(\"My Test Engagement Custom Audience\") .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<pageID>\\",\\"type\\":\\"page\\"}],\\"retention_seconds\\":31536000,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"page_engaged\\"}]}}]}}\") .setPrefill(true) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) customaudiences = ad_account.customaudiences.create({ name: 'My Test Engagement Custom Audience', rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, prefill: '1', })

Use these parameters for page engagement custom audiences:

NameTypeDescriptionRequired

name

String

Custom Audience name.

Yes

rule

JSON Object

Rules to define the audience. It follows the same syntax as website custom audience.

Yes

Page Engagement Custom Audiences are types of Custom Audiences; for all available fields, see Custom Audience Reference.

Each ad account can create a maximum of 500 engagement custom audiences.

Engagement Rules

You can determine if Facebook adds someone to the Custom Audience or not. Specify the type and id fields the inside event_sources field in the rule to indicate the type and id of the engagement object. The id field takes a single object id, or an array of ids of the same type. For more information, see Audience Rules.

These are supported event sources and corresponding engagement object ids:

  • page: Facebook page ID

  • lead: Lead form ID

  • ig_lead_generation: Lead form ID

  • canvas: Canvas ID

  • ig_business: Instagram business profile ID

Each rule consists of an object_id, which is your page ID, and an event_name, which is one of the following engagement events:

  • page_engaged: People who visited your page or engaged with any of your page's content or ads, on Facebook or Messenger. This is the most inclusive engagement type and includes all other types of engagement.

  • page_visited: People who have visited your page.

  • page_messaged: People who sent a message to your page.

  • page_cta_clicked: People who have clicked any call-to-action buttons on your page; for example, "Contact Us" or "Shop Now".

  • page_or_post_save: People who have saved your page or any of your page posts.

  • page_post_interaction: People who have interacted with any of your page posts. Interactions include reactions (Like, Love, Haha, Wow, Sad, Angry), shares, comments, link clicks or carousel swipes.

For Lead Ads, you should set object_id to FORM_ID and set the rule to track one of the following Lead Ads Events:

  • lead_generation_submitted: All users who completed the form and submitted it.
  • lead_generation_dropoff: All people who close the form without submitting it. They may or may not have filled in any of the fields.
  • lead_generation_opened: All people who opened the Lead Gen form regardless of whether or not they submitted the form.

For Canvas, object_id should be the "CANVAS_ID", and the rule to track one of the following Canvas events:

  • instant_shopping_document_open
  • instant_shopping_document_pause
  • instant_shopping_document_resume
  • instant_shopping_document_close
  • instant_shopping_did_scroll
  • instant_shopping_element_click
  • instant_shopping_element_impression

For Instagram business profile, object_id should be the "INSTAGRAM_BUSINESS_PROFILE_ID", and the rule to track one of the following Instagram business profile events:

  • ig_business_profile_all: People who visited your Instagram business profile or engaged with any of your Instagram business profile's content or ads. This is the most inclusive engagement type and includes all other types of engagement. It's a union of ig_business_profile_engaged, ig_user_messaged_business, and ig_user_messaged_business.
  • ig_business_profile_engaged: People who engagement with Instagram business profile or engaged with any of your Instagram business profile's content or ads.
  • ig_user_messaged_business: People who messaged your Instagram business profile.
  • ig_business_profile_visit: People who visited your Instagram business profile.
  • ig_business_profile_ad_saved: People who saved either organic content or ad from your Instagram business profile.
  • ig_ad_like
  • ig_ad_comment
  • ig_ad_share
  • ig_ad_save
  • ig_ad_cta_click
  • ig_ad_carousel_swipe
  • ig_organic_like
  • ig_organic_comment
  • ig_organic_share
  • ig_organic_save
  • ig_organic_swipe
  • ig_organic_carousel_swipe

Max Retention Days

For legal/privacy requirements, we allow different maximum retention days for each event source type:

  • Lead gen: 90 days
  • IG business profile: 730 days
  • Page: 730 days
  • Canvas: 730 days

Engagement Rules with Exclusion Section

Engagement audience rule is compatible with website custom audience rules. Therefore, it can have multiple inclusion/exclusion rules, and users that match at least one of the rules will be added to the audience. An example of creating an audience that will include users that visited your page or engaged with your page, but exclude people who clicked the call-to-action:

curl -X POST \ -F 'name=My Test Engagement Custom Audience' \ -F 'rule={"inclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<PAGE_ID>","type":"page"}],"retention_seconds":31536000,"filter":{"operator":"and","filters":[{"field":"event","operator":"eq","value":"page_engaged"}]}}]},"exclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<PAGE_ID>","type":"page"}],"retention_seconds":31536000,"filter":{"operator":"and","filters":[{"field":"event","operator":"eq","value":"page_cta_clicked"}]}}]}}' \ -F 'prefill=1' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/act_<AD_ACCOUNT_ID>/customaudiences
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdAccount = adsSdk.AdAccount; const CustomAudience = adsSdk.CustomAudience; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My Test Engagement Custom Audience', 'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]},'exclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_cta_clicked'}]}}]}}, 'prefill' : '1', }; let customaudiences = (new AdAccount(id)).createCustomAudience( fields, params ); logApiCallResult('customaudiences api call complete.', customaudiences);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\CustomAudience; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My Test Engagement Custom Audience', 'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<pageID>','type' => 'page')),'retention_seconds' => 31536000,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'page_engaged')))))),'exclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<pageID>','type' => 'page')),'retention_seconds' => 31536000,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'page_cta_clicked'))))))), 'prefill' => '1', ); echo json_encode((new AdAccount($id))->createCustomAudience( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount from facebookads.adobjects.customaudience import CustomAudience from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My Test Engagement Custom Audience', 'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]},'exclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_cta_clicked'}]}}]}}, 'prefill': '1', } print AdAccount(id).create_custom_audience( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCustomAudience() .setName(\"My Test Engagement Custom Audience\") .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<pageID>\\",\\"type\\":\\"page\\"}],\\"retention_seconds\\":31536000,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"page_engaged\\"}]}}]},\\"exclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<pageID>\\",\\"type\\":\\"page\\"}],\\"retention_seconds\\":31536000,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"page_cta_clicked\\"}]}}]}}\") .setPrefill(true) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) customaudiences = ad_account.customaudiences.create({ name: 'My Test Engagement Custom Audience', rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]},'exclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_cta_clicked'}]}}]}}, prefill: '1', })

For more information, see Custom Audiences from Your Website.

Multiple Rules

Engagement audiences can have multiple rules, and users that match at least one of the rules will be added to the audience. An example of creating an audience that will include users that messaged your page or clicked the call-to-action:

curl -X POST \ -F 'name=My Test Engagement Custom Audience' \ -F 'rule={"inclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<PAGE_ID>","type":"page"}],"retention_seconds":31536000,"filter":{"operator":"and","filters":[{"field":"event","operator":"eq","value":"page_engaged"},{"field":"event","operator":"eq","value":"page_engaged"}]}}]}}' \ -F 'prefill=1' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/act_<AD_ACCOUNT_ID>/customaudiences
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdAccount = adsSdk.AdAccount; const CustomAudience = adsSdk.CustomAudience; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My Test Engagement Custom Audience', 'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'},{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, 'prefill' : '1', }; let customaudiences = (new AdAccount(id)).createCustomAudience( fields, params ); logApiCallResult('customaudiences api call complete.', customaudiences);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\CustomAudience; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My Test Engagement Custom Audience', 'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<pageID>','type' => 'page')),'retention_seconds' => 31536000,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'page_engaged'),array('field' => 'event','operator' => 'eq','value' => 'page_engaged'))))))), 'prefill' => '1', ); echo json_encode((new AdAccount($id))->createCustomAudience( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount from facebookads.adobjects.customaudience import CustomAudience from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My Test Engagement Custom Audience', 'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'},{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, 'prefill': '1', } print AdAccount(id).create_custom_audience( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCustomAudience() .setName(\"My Test Engagement Custom Audience\") .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<pageID>\\",\\"type\\":\\"page\\"}],\\"retention_seconds\\":31536000,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"page_engaged\\"},{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"page_engaged\\"}]}}]}}\") .setPrefill(true) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) customaudiences = ad_account.customaudiences.create({ name: 'My Test Engagement Custom Audience', rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'},{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, prefill: '1', })

Multiple Pages

Rules are not limited to a single page. You can have a different page for each rule, and people who engaged with at least one of the pages and we include them in the audience. An example of an audience that includes all people that visited at least one of three pages:

curl -X POST \ -F 'name=My Test Engagement Custom Audience' \ -F 'rule={"inclusions":{"operator":"or","rules":[{"event_sources":[{"id":"<PAGE_ID>","type":"page"},{"id":"<PAGE_ID>","type":"page"}],"retention_seconds":31536000,"filter":{"operator":"and","filters":[{"field":"event","operator":"eq","value":"page_engaged"}]}}]}}' \ -F 'prefill=1' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/act_<AD_ACCOUNT_ID>/customaudiences
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdAccount = adsSdk.AdAccount; const CustomAudience = adsSdk.CustomAudience; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My Test Engagement Custom Audience', 'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'},{'id':'<pageID2>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, 'prefill' : '1', }; let customaudiences = (new AdAccount(id)).createCustomAudience( fields, params ); logApiCallResult('customaudiences api call complete.', customaudiences);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\CustomAudience; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My Test Engagement Custom Audience', 'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<pageID>','type' => 'page'),array('id' => '<pageID2>','type' => 'page')),'retention_seconds' => 31536000,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'page_engaged'))))))), 'prefill' => '1', ); echo json_encode((new AdAccount($id))->createCustomAudience( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount from facebookads.adobjects.customaudience import CustomAudience from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My Test Engagement Custom Audience', 'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'},{'id':'<pageID2>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, 'prefill': '1', } print AdAccount(id).create_custom_audience( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCustomAudience() .setName(\"My Test Engagement Custom Audience\") .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<pageID>\\",\\"type\\":\\"page\\"},{\\"id\\":\\"<pageID2>\\",\\"type\\":\\"page\\"}],\\"retention_seconds\\":31536000,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"page_engaged\\"}]}}]}}\") .setPrefill(true) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) customaudiences = ad_account.customaudiences.create({ name: 'My Test Engagement Custom Audience', rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pageID>','type':'page'},{'id':'<pageID2>','type':'page'}],'retention_seconds':31536000,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'page_engaged'}]}}]}}, prefill: '1', })

Engagement Rules, deprecated

Use this section for engagement rules prior to v3.0.

You can determine if Facebook adds someone to the Custom Audience or not.

You need to specify the type and id fields the inside event_sources field in the rule to indicate the type and id of the engagement object. The id field takes a single object id, or an array of ids of the same type. For more information, see Audience Rules.

Following are the supported event source types and corresponding engagement object id types:

  • page: Facebook page ID

  • lead: Lead form ID

  • ig_lead_generation: Lead form ID

  • canvas: Canvas ID

  • ig_business: Instagram business profile ID

Each rule consists of an object_id, which is your page ID, and an event_name, which is one of the following engagement events:

  • page_engaged: People who visited your page or engaged with any of your page's content or ads, on Facebook or Messenger. This is the most inclusive engagement type and includes all other types of engagement.

  • page_visited: People who have visited your page.

  • page_messaged: People who sent a message to your page.

  • page_cta_clicked: People who have clicked any call-to-action buttons on your page; for example, "Contact Us" or "Shop Now".

  • page_or_post_save: People who have saved your page or any of your page posts.

  • page_post_interaction: People who have interacted with any of your page posts. Interactions include reactions (Like, Love, Haha, Wow, Sad, Angry), shares, comments, link clicks or carousel swipes.

For Lead Ads, you should set object_id to FORM_ID and set the rule to track one of the following Lead Ads Events:

  • lead_generation_submitted: All users who completed the form and submitted it.
  • lead_generation_dropoff: All people who close the form without submitting it. They may or may not have filled in any of the fields.
  • lead_generation_opened: All people who opened the Lead Gen form regardless of whether or not they submitted the form.

For Canvas, object_id should be the "CANVAS_ID", and the rule to track one of the following Canvas events:

  • instant_shopping_document_open
  • instant_shopping_document_pause
  • instant_shopping_document_resume
  • instant_shopping_document_close
  • instant_shopping_did_scroll
  • instant_shopping_element_click
  • instant_shopping_element_impression

For Instagram business profile, object_id should be the "INSTAGRAM_BUSINESS_PROFILE_ID", and the rule to track one of the following Instagram business profile events:

  • ig_business_profile_all: People who visited your Instagram business profile or engaged with any of your Instagram business profile's content or ads. This is the most inclusive engagement type and includes all other types of engagement. It's a union of ig_business_profile_engaged, ig_user_messaged_business, and ig_user_messaged_business.
  • ig_business_profile_engaged: People who engagement with Instagram business profile or engaged with any of your Instagram business profile's content or ads.
  • ig_user_messaged_business: People who messaged your Instagram business profile.
  • ig_business_profile_visit: People who visited your Instagram business profile.
  • ig_business_profile_ad_saved: People who saved either organic content or ad from your Instagram business profile.
  • ig_ad_like
  • ig_ad_comment
  • ig_ad_share
  • ig_ad_save
  • ig_ad_cta_click
  • ig_ad_carousel_swipe
  • ig_organic_like
  • ig_organic_comment
  • ig_organic_share
  • ig_organic_save
  • ig_organic_swipe
  • ig_organic_carousel_swipe

Max Retention Days

For legal/privacy requirements, we allow different maximum retention days for each event source type:

  • Lead gen: 90 days
  • IG business profile: 730 days
  • Page: 730 days
  • Canvas: 730 days

Engagement Rules with Exclusion Section

Engagement audience rule is compatible with website custom audience rules. Therefore, it can have multiple inclusion/exclusion rules, and users that match at least one of the rules will be added to the audience. An example of creating an audience that will include users that visited your page or engaged with your page, but exclude people who clicked the call-to-action:

curl \
  -F 'name=Messenger Page Engagement Audience' \
  -F 'description=Users who messaged my page or clicked the cta' \
  -F 'rule={
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "page",
                        "id": "1232770146747060"
                    }
                ],
                "retention_seconds": 31536000,
                "filter": {
                    "operator": "or",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "page_visited"
                        },
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "page_engaged"
                        }
                    ]
                }
            }
        ]
    },
    "exclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "page",
                        "id": "1232770146747060"
                    }
                ],
                "retention_seconds": 31536000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "page_cta_clicked"
                        }
                    ]
                }
            }
        ]
    }
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

For more information, see Custom Audiences from Your Website.

Multiple Rules

Engagement audiences can have multiple rules, and users that match at least one of the rules will be added to the audience. An example of creating an audience that will include users that messaged your page or clicked the call-to-action:

curl \
  -F 'name=Messenger Page Engagement Audience' \
  -F 'description=Users who messaged my page or clicked the cta' \
  -F 'rule={
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "page",
                        "id": "1232770146747060"
                    }
                ],
                "retention_seconds": 31536000,
                "filter": {
                    "operator": "or",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "page_messaged"
                        },
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "page_cta_clicked"
                        }
                    ]
                }
            }
        ]
    },
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Multiple Pages

Rules are not limited to a single page. You can have a different page for each rule, and people who engaged with at least one of the pages and we include them in the audience. An example of an audience that includes all people that visited at least one of three pages:

curl \
  -F 'name=Messenger Page Engagement Audience' \
  -F 'description=Users who messaged my page or clicked the cta' \
  -F 'rule={
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "page",
                        "id": "<PAGE_ID_1>",
                    },
                "event_sources": [
                    {
                        "type": "page",
                        "id": "<PAGE_ID_2>",
                    },
                "event_sources": [
                    {
                        "type": "page",
                        "id": "<PAGE_ID_3>",
                    },
                ],
                "retention_seconds": 31536000,
                "filter": {
                    "operator": "or",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "page_visited"
                        }
                    ]
                }
            }
        ]
    },
}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences


For details on Custom Audiences see the Custom Audience Reference.