Connected audience object

A connected audience object identifies the audience of your message. For example, if you use custom attribute arrays to track every category and TV show that a user has favorited, you can use connected audiences to automatically send a push notification or email to anyone who has favorited a show whenever a new episode is released—without needing to set up a segment for each show.

This object is composed of either a single connected audience filter or several connected audience filters in a logical expression using either AND or 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

Combining multiple custom attribute filters with AND and OR operators creates 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
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "custom_attribute":
    {
      "custom_attribute_name": "eye_color",
      "comparison": "equals",
      "value": "blue"
    }
}

{
  "custom_attribute":
  {
    "custom_attribute_name": "favorite_foods",
    "comparison": "includes_value",
    "value": "pizza"
  }
}

{
  "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.