Writing filter criteria

Twilio Cohorts uses the Common Expression Language (CEL) to define filter criteria for audience targeting. Each criterion evaluates to true or false for every profile in your connected store. Profiles for which the criterion evaluates to true are added to the resulting cohort snapshot.

Filter criteria can reference two profile properties: traits and addresses.

Traits describe attributes attached to a profile, such as account tier, lifetime value, or sign-up date. Reference a trait by using profile.trait.{traitGroup}.{traitName}.

profile.trait.Account.status == "active"

Traits are typed as string, integer, float, boolean, timestamp, or duration. Array-typed traits aren't supported.

Addresses represent contact channels attached to a profile, such as email addresses or phone numbers. Reference an address as profile.address.{channel}, where channel is email, phone, whatsapp, or chat.

Unlike traits, an address always returns a list of strings because a profile can have more than one address on the same channel (for example, two email addresses). You can't compare an address directly to a string. Instead, check for presence with has(), membership with in, or use list operations such as .exists().

"jane@example.com" in profile.address.email

Combine multiple conditions with logical operators:

profile.trait.Account.status == "active" && profile.trait.Account.country == "US"

For details on how operators are evaluated, see Operators and precedence.

Trait group and field names that contain periods, dashes, double underscores, or that start with a digit must be escaped before you reference them in filter criteria. See Escaping special characters for the complete list of escape sequences.

If a trait is absent on a profile, any comparison against it evaluates to false, which excludes the profile rather than raising an error. Use has() to check explicitly whether a trait is present. See Null handling for more information.

Both sides of a comparison must be the same data type. For example, comparing a string-typed trait to an integer literal triggers a validation error when you create or update a cohort. See Type matching for the full rules and available type-conversion functions.

Twilio Cohorts enforces the following limits on CEL expressions:

Expressions that exceed these limits are rejected with an HTTP 422 Unprocessable Content error.

• Learn about operators and precedence.
• Browse the available functions.
• Review example criteria for common filtering patterns.