Audience Rules

Updated: Jun 16, 2026

Copy for LLM

Ads in WhatsApp Status are available via the Marketing API. Learn more about ads in WhatsApp Status.

Audience rules determine whether someone is added to your custom audience. The rules are applied on either the referrer URL or specific events and data.

Provide your rules as JSON-encoded strings structured like so:

One audience rule contains two rule sets.

Each rule set can contain an inclusion or exclusion rule.

Each inclusion or exclusion rule can contain filters and aggregation functions.

Each filter contains a filter set.

Use audience rules for different types of custom audiences, including Website Custom Audiences, Mobile App Custom Audiences, and Offline Custom Audiences. For Engagement Audience Rules, see Engagement Custom Audiences.

Limitations

Each audience can specify up to 10 rules in the audience rule. This includes the number of rules in inclusions or exclusions.

Each rule can specify up to 100 filters, known as leaf nodes.

Audience rules syntax

To define an audience rule, use the following structure:

rule: {
   "inclusions": <RULE_SET>,
   "exclusions": <RULE_SET>,
}

Available fields

Name	Description
`inclusions` type: String	Required. Rule Set JSON string that defines the inclusion. See Rule Set Syntax.
`exclusions` type: String	Required. Rule set JSON string that defines the exclusion. See Rule Set Syntax.

Rule set syntax

For each rule set, follow this structure:

{
  "operator" : <BOOLEAN_OPERATOR>,
  "rules" : <JSON_RULE>,
}

Available fields

Name	Description
`operator` type: string	Required. `and` or `or`.
`rules` type: string	Required. JSON string of rules (array of rules). See Inclusion And Exclusion Rule Syntax.

Inclusion and exclusion rule syntax

For each inclusion or exclusion rule, follow this structure:

{
  "event_sources" : <EVENT_SOURCE_DEFINITION>,
  "retention_seconds" : <SECONDS>,
  "filter" : <FILTER>,
  "aggregation" : <AGGREGATION>,
}

aggregation and retention_seconds are editable fields. However, editing aggregation and retention_seconds does not flush the audience. People who only match the old rule/aggregation continue to be in the audience until they expire.

Available fields

Name	Description
`event_sources` type: String	Required. JSON object containing the `id` and `type`. For Website Custom Audiences using Pixel, set `id` to your Pixel’s ID and `type` to `'pixel'`. For Mobile App Custom Audiences, set `id` to your app ID and `type` to `app`. More event sources can be added to `type` using a comma-delimited list `"store_visits,pixel,app"`.
`retention_seconds` type: Integer	Required. Integer (in seconds) for the retention window of the audience, should be less than `retention_days`. Min=1; Max=365 days
`filter` type: String	Required. JSON string of the filter rules. See Filters.
`aggregation` type: Integer	Optional. JSON string of the aggregation functions. See Aggregate Functions.

Filters

Filtration follows this general format:

"filter" : {
  "operator": <BOOLEAN_OPERATOR>,
  "filters": <FILTER_SET>,
  }

Available fields

Name	Description
`operator` type: string	Required. `and` or `or`
`filters` type: string	Required. Array of JSON objects of filter rules. See Filter Set Syntax.

Filter set syntax

{
    "field": <FIELD>,
    "operator": <COMPARISON_OPERATOR>,
    "value": <VALUE>,
}

Available fields

Name	Description
`field` type: String	Required. For Website Custom Audiences, use `'event'` if the filter is to specify an event. Parameters that match events sent by pixel (for example, `'ViewContent'`, `'Purchase'`). For Mobile App Custom Audiences, use `'event'` if the filter is to specify an event. Parameters that match App events sent by app; for example, “_appVersion”, “_value”, and so on.
`operator` type: String	Required. `=` `!=` `>=` `>` `<=` `<` `i_contains` `i_not_contains` `contains` `not_contains` `is_any` `is_not_any` `i_is_any` `i_is_not_any` `i_starts_with` `starts_with` `regex_match` If `field` set to `event`, must use `=`.
`value` type: String	Required. If the `field` attribute is set to `"event"`, the `value` must be set to an event name. Use the App Event API to see app events and parameters reported by the app.

Aggregate functions

Create custom audiences based on the frequency and intensity of behavior using the aggregation in the audience rule field. In the aggregation field, define an aggregate function, for example:

"aggregation" : {
  "type":"count",
  "operator":">",
  "value":1
}

Available fields

Name	Description
`type` type: String	Required. The aggregation function type. For Website Custom Audiences, the following functions are available: `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`, `'time_spent'`, and `'last_event_time_field'`. For Mobile App Custom Audiences, the following functions are available: `"count"`,`"sum"`, `"avg"`, `"min"`, and `"max"`.
`config`	Required by certain types of aggregation functions.
`method` type: String	Optional. `"absolute"`, meaning add people that logged events in specified range, or `"percentile"`, meaning add people from a specified percentile range. If you select `percentile`, the operator should only be `in_range` and `not_in_range`.
`field` type: String	Required. Unless type is `count`. The parameter on which the aggregation function is applied.
`operator` type: String	Required. `=`, `!=`, `>=`, `>`, `<=`, `<`, `in_range`, `not_in_range`
`value` type: String	Required. Expected value of the parameter.

Comparison operators

Operator	Description
`>` or `gt`	True if event’s parameter value greater than specified value.
`>=` or `gte`	True if event’s parameter value greater than or equal to specified value.
`<` or `lt`	True if event’s parameter value less than specified value.
`<=` or `lte`	True if event’s parameter value less than or equal to specified value.
`=` or `eq`	True if event’s parameter value equal to specified value. Note: This is equivalent to not specifying an operator at all; that is, “‘x’ : { ‘eq’ : ‘y’ }” is the same as “‘x’ : ‘y’ }.
`!=` or `neq`	True if event’s parameter value not equal to specified value.
`contains`	True if event’s parameter value, as string, contains specified string. Value of “shoe12345” fulfills ‘contains’ if specified value ‘shoe’.
`not_contains`	True if event’s parameter value, as string, does not contain specified string. Value “shoe12345” fulfills `not_contains` if specified value is ‘purse’.
`i_contains`	Contains, case-insensitive
`i_not_contains`	Not contains, case-insensitive
`is_any`	True if event’s parameter value matches any strings in given array.
`is_not_any`	True if event’s parameter value matches no strings in specified array.
`i_is_any`	`is_any`, case-insensitive.
`i_is_not_any`	`is_not_any`, case-insensitive
`starts_with`	True if the event’s parameter value starts with the given string
`i_starts_with`	`starts_with`, case-insensitive
`regex_match`	Matches a regular expression such as "example\.com.*purchase$". The full PCRE grammar is supported

Examples

Website Custom Audiences

Match all referring URLs containing the string shoes in the last 30 days:

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "pixel",
                        "id": "<PIXEL_ID>",
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "url",
                            "operator": "i_contains",
                            "value": "shoes"
                        }
                    ]
                },
            }
        ]
    }
}

Match ViewContent events where item price is greater than or equal to USD 100 in the last 30 days. Consider using this rule for the following event:

_fbq.push([ 'track', 'ViewContent', { productId: 1234, category: 'Men > Shoes', price: 199 } ]);

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "pixel",
                        "id": "<PIXEL_ID>"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "ViewContent"
                        },
                        {
                            "operator": "or",
                            "filters": [
                                {
                                    "field": "price",
                                    "operator": ">=",
                                    "value": "100"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Mobile App Custom Audiences

See Mobile App Custom Audiences, Example Custom Audience Rules.

Operators and data or events

Rules have the following operators and data or events:

Operators	The type of filter
`i_contains`	Contains substring, case insensitive
`i_not_contains`	Does not contain substring, case insensitive
`contains`	Contains substring, case sensitive
`not_contains`	Does not contain substring, case sensitive
`eq`	Equal to, case sensitive
`neq`	Not equal to, case sensitive
`lt`	Less than, numeric fields only
`lte`	Less than or equal to, numeric fields only
`gt`	Greater than, numeric fields only
`gte`	Greater than or equal to, numeric fields only
`regex_match`	Matches a regular expression such as `\"example\\.com.*purchase$\"`. The full PCRE grammar is supported

Data	Data being filtered
`url`	Fully escaped URL of the site visited
`domain`	Domain of site visited
`path`	Path of site visited, excluding domain
`event`	Name of pixel `event`, such as `'ViewContent'`
`device_type`	Device that accessed site: `desktop` `mobile_android_phone` `mobile_android_tablet` `mobile_ipad` `mobile_ipod` `mobile_iphone` `mobile_tablet` `mobile_windows_phone`
any `customData` field	Any field added to `customData` for pixel fires, such as `productId`, `category`, `price`

Provide each rule as a JSON-encoded string.