Connected audience object

A connected audience is a dynamic audience filter you define inline within your API request, so you can target the right users at send time without creating or managing segments in the Braze dashboard.

Instead of pre-building a segment for every possible audience combination, you pass filter criteria directly in the audience parameter of your API call. Braze evaluates each user against those criteria in real time and delivers the message only to users who match. This means a single campaign, Canvas, or API-only message definition can serve an unlimited number of audience variations, driven entirely by your business logic.

How it works

1. Define your message by either creating an API-triggered campaign or Canvas in the Braze dashboard, or define message content entirely inline using the messaging objects in your API request. Use trigger properties or Canvas context for dynamic personalization.
2. Call a supported endpoint and include the audience parameter with your filter criteria. You can filter on custom attributes, push subscription status, email subscription status, and last-used-app time.
3. Braze evaluates the filters at send time, delivering the message only to users who match your criteria.

Because the audience is defined per request, your backend systems can trigger contextually relevant messages in response to any business event (a price change, a weather alert, a live score update) without dashboard intervention.

Compatible endpoints

You can use the connected audience object with the audience parameter on these endpoints:

• /messages/send
• /campaigns/trigger/send
• /canvas/trigger/send
• /messages/schedule/create
• /campaigns/trigger/schedule/create
• /canvas/trigger/schedule/create

Use cases

Use connected audiences for scenarios where your back-end systems detect an event and need to notify a dynamically determined set of users:

In each case, a single campaign or API-only message definition handles all variations. Your backend determines the filter values and passes them in the API request, so you don’t need to create a separate segment or campaign for each product, show, team, or location.

Example request

The following example uses the /campaigns/trigger/send endpoint to target users who have favorited a specific show and are opted in to push notifications:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "audience": {
    "AND": [
      {
        "custom_attribute": {
          "custom_attribute_name": "favorite_shows",
          "comparison": "includes_value",
          "value": "Example Show"
        }
      },
      {
        "push_subscription_status": {
          "comparison": "is",
          "value": "opted_in"
        }
      }
    ]
  },
  "trigger_properties": {
    "show_title": "Example Show",
    "episode_title": "Season 3, Episode 1",
    "deep_link": "https://example.com/shows/example-show/s3e1"
  },
  "broadcast": false
}

Object body

The connected audience object is composed of either a single connected audience filter or several connected audience filters combined with AND and OR operators.

Multiple filter example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "AND":
    [
      Connected Audience Filter,
      {
        "OR" :
          [
            Connected Audience Filter,
            Connected Audience Filter
          ]
      },
      Connected Audience Filter
    ]
}

Connected audience filters

Combine multiple filters with AND and OR operators to create a connected audience filter.

Custom attribute filter

This filter allows you to segment based on a user’s custom attribute. These filters contain up to three fields:

1
2
3
4
5
6
7
8
{
  "custom_attribute":
    {
      "custom_attribute_name": (String) the name of the custom attribute to filter on,
      "comparison": (String) one of the allowed comparisons to make against the provided value,
      "value": (String, Numeric, Boolean) the value to be compared using the provided comparison
    }
}

Allowed comparisons by data type

The custom attribute’s data type determines the comparisons that are valid for a given filter.

Attribute comparison caveats

Custom attribute example

1
2
3
4
5
6
7
8
{
  "custom_attribute":
    {
      "custom_attribute_name": "eye_color",
      "comparison": "equals",
      "value": "blue"
    }
}

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "favorite_foods",
    "comparison": "includes_value",
    "value": "pizza"
  }
}

1
2
3
4
5
6
7
8
{
  "custom_attribute":
  {
    "custom_attribute_name": "last_purchase_time",
    "comparison": "less_than_x_days_ago",
    "value": 2
  }
}

Push subscription filter

This filter allows you to segment based on a user’s push subscription status.

Filter body

1
2
3
4
5
6
7
{
  "push_subscription_status":
  {
    "comparison": (String) one of the following allowed comparisons,
    "value": (String) one of the following allowed values
  }
}

• Allowed comparisons: is, is_not
• Allowed values: opted_in, subscribed, unsubscribed

Email subscription filter

This filter allows you to segment based on a user’s email subscription status.

Filter body

1
2
3
4
5
6
7
{
  "email_subscription_status":
  {
    "comparison": (String) one of the following allowed comparisons,
    "value": (String) one of the following allowed values
  }
}

• Allowed comparisons: is, is_not
• Allowed values: opted_in, subscribed, unsubscribed

Last used app filter

This filter allows you to segment based on when the user last used the app. These filters contain two fields:

Filter body

1
2
3
4
5
6
7
{
  "last_used_app":
  {
    "comparison": (String) one of the allowed comparisons listed,
    "value": (String) the value to be compared using the provided comparison
  }
}

• Allowed comparisons: after, before
• Allowed values: datetime (ISO 8601 string)

Considerations

Connected audiences cannot filter users by default attributes, custom events, segments, or message engagement events. To use these filters, we recommend incorporating them into an audience segment and then specifying that segment in the segment_id parameter for the /messages/send endpoint. When using other endpoints, you’ll need to add the segment to the API-triggered campaign or Canvas in the Braze dashboard first.