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 ads, Instant Experience ads, and Shopping.

This guide 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.

Since September 2018, we do not support subtype for custom audiences for websites, apps, engagement custom audiences, and audiences from offline conversion data. The exception is that subtype is supported for engagement custom audiences for video.
If you are creating audiences from Europe or targeting people in Europe, see our Dec 2, 2020 non-versioned change.

Create an Audience

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

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/v9.0/act_<AD_ACCOUNT_ID>/customaudiences


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.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',
};
const 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 = '<AD_ACCOUNT_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
)->exportAllData(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_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 = \"<AD_ACCOUNT_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 = '<AD_ACCOUNT_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 engagement custom audiences:

Name Description

Name	Description
`name` type: String	Required. Custom Audience name.
`rule` type: JSON Object	Required. Rules to define the audience. It follows the same syntax as website custom audience.

name

type: String

Required.

Custom Audience name.

rule

type: JSON Object

Required.

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

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. You do that with Audience Rules.

Specify the type and id fields inside event_sources 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.

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
shopping_page: your Facebook Shop Page ID
shopping_ig: Your Instagram Shop ID

Each rule consists of an object_id and an event_name.

Lead Ads

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.

Instant Experiences

Set object_id to "CANVAS_ID". The rule should track one of the following 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

Instagram Business Profile

object_id should be the "INSTAGRAM_BUSINESS_PROFILE_ID", and the rule should 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

Instagram Media Creator type is currently not supported for video engagement custom audience creation.

Shopping

A shopping engagement rule should track one of the following events:

VIEW_CONTENT: People who have viewed your product detail page. This option is available globally.
ADD_TO_CART: People who have added your product to their shopping cart. This is available only to checkout enabled businesses, and only to consumers in the United States.
PURCHASE: People who have purchased your products. This is available only to checkout enabled business, and only to consumers in the United States.

To create a rule that adds people who have viewed your product:

curl -i -X POST
-F 'name="test_api"'\
-F 'rule= {
  "inclusions": {
    "operator": "or",
    "rules": [
      {
        "event_sources": [
          {
            "id": "<ID>",
            "type": "shopping_ig"
          }
        ]
        "retention_seconds": <RETENTION_SECONDS>,
        "filter": {
          "operator": "and",
          "filters": [
            {
            "field":"event",
            "operator":"eq",
            "value": "VIEW_CONTENT"
            }
          ]
        }
      }
    ]
  }
}
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

page_messaged and ig_user_messaged_business may not be available in Europe due to new privacy rules.

Max Retention Days

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

Lead Generation Ads: 90 days
Instagram business profile: 730 days
Page: 730 days
Instant Experiences, formerly known as Canvas: 730 days
Shopping: 365 days. The data is available since April 2020

Engagement Rules with Exclusion Section

Engagement audience rules are compatible with website custom audience rules. Therefore, they can have multiple inclusion and exclusion rules. Users that match at least one of the rules will be added to the audience.

In the following example, we create an audience that includes users that visited your page or engaged with your page, but excludes 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/v9.0/act_<AD_ACCOUNT_ID>/customaudiences


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.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',
};
const 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 = '<AD_ACCOUNT_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
)->exportAllData(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_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 = \"<AD_ACCOUNT_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 = '<AD_ACCOUNT_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 includes 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/v9.0/act_<AD_ACCOUNT_ID>/customaudiences


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.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',
};
const 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 = '<AD_ACCOUNT_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
)->exportAllData(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_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 = \"<AD_ACCOUNT_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 = '<AD_ACCOUNT_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.

The following is 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/v9.0/act_<AD_ACCOUNT_ID>/customaudiences


'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.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',
};
const 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 = '<AD_ACCOUNT_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
)->exportAllData(), JSON_PRETTY_PRINT);


from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_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 = \"<AD_ACCOUNT_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 = '<AD_ACCOUNT_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',
})

For details on Custom Audiences see the Custom Audience Reference.