Filters

Filter list subscriptions to show only matching data.

Filters allow you to only show specific data inside of a list subscription. For example, only showing specific conversations you are in.

type ConversationFilter

Passed to Session.subscribeConversations, specifying which conversations should be returned in the subscription.

Either a SimpleConversationFilter or a CompoundFilter OR-ing multiple simple filters together.

Example 1

A simple conversation filter that only includes conversations with the subject "cats!"


1{ subject: ["==", "cats!"] }

Example 2

A compound conversation filter that includes conversations with messages, and empty conversations with the subject "cats!" ```json ["any", [ { hasMessages: true }, { subject: ["==", "cats!"] } ]]

interface SimpleConversationFilter

Allows you to filter conversations in a subscription, only showing those that match this filter.

Multiple conversation filters can be OR-ed together using CompoundFilter.

Example

Only include conversations with unread messages


1session.subscribeConversations(onSnapshot, {
2  filter: { isUnread: true }
3});

Properties

access (optional)

: StringFilter<"ReadWrite" | "Read">

Only select conversations that the current user as specific access to.

Must be an 2-element array of [operator, operand] structure. Valid operators are: "==", "!=", "oneOf", and "!oneOf".

The operand must be either a string (one of "ReadWrite" or "Read") or an array of strings (for the oneOf operators).

Example

Hide conversations that the user cannot send messages to


1{ access: ["!=", "ReadWrite"] }

createdAt (optional)

: NumberFilter

Only select conversations that have been created in a particular time interval.

Must be an 2-element array of [operator, operand] structure. Valid operators are: ">", "<", ">=", "<=", "between", and "!between".

The operand must be either a number or a 2-element array of numbers (for the between operators).

Example

Only show conversations that were created after the UNIX timestamp 1679298371586


1{ createdAt: [">", 1679298371586] }

custom (optional)

: CustomFilter

Only select conversations that have particular custom fields set to particular values.

Every key must correspond to a key in the custom conversation data that you set (by passing custom to ConversationBuilder.setAttributes). It is not necessary for all conversations to have these keys.

Each value must be one of the following:

A string, equal to "exists" or "!exists"

A 2-element array of [operator, operand] structure. The operand must be either a string or an array of strings (for the oneOf operators). Valid operators are: "==", "!=", "oneOf", and "!oneOf".

Example 1

Only show messages that have no custom category set


1{ custom: { category: "!exists" } }

Example 2

Only show messages of that have the custom category "shoes"


1{ custom: { category: ["==", "shoes"] } }

Example 3

Only show messages that have a 'topic' of either "inquiry" or "reservation"


1{
2  custom: {
3    topic: ["oneOf", ["inquiry", "reservation"]]
4  }
5}

Example 4

Only show messages about shoes that are marked visible


1{
2  custom: {
3    category: ["==", "shoes"],
4    visibility: ["==", "visible"]
5  }
6}

hasMessages (optional)

: boolean

Only select conversations that have, or do not have messages.

Example 1

Only show conversations that have at least one message


1{ hasMessages: true }

Example 2

Only show empty conversations


1{ hasMessages: false }

isUnread (optional)

: boolean

Set this field to only select conversations that have, or don't have any, unread messages.

joinedAt (optional)

: NumberFilter

Only select conversations that the current user joined in a particular time interval.

Must be an 2-element array of [operator, operand] structure. Valid operators are: ">", "<", ">=", "<=", "between", and "!between".

The operand must be either a number or a 2-element array of numbers (for the between operators).

Example

Only show conversations joined after the UNIX timestamp 1679298371586


1{ joinedAt: [">", 1679298371586] }

lastActivityAt (optional)

: NumberFilter

Only select conversations that have the last message sent in a particular time interval.

If the conversation has no messages, this falls back to using joinedAt instead. This matches the default sort order for conversations in a conversation list.

Must be an 2-element array of [operator, operand] structure. Valid operators are: ">", "<", ">=", "<=", "between", and "!between".

The operand must be either a number or a 2-element array of numbers (for the between operators).

Example

Only show conversations that had messages sent after the UNIX timestamp 1679298371586


1{ lastActivityAt: [">", 1679298371586] }

subject (optional)

: StringFilter<string | null>

Only select conversations that have the subject set to particular values.

Must be an 2-element array of [operator, operand] structure. Valid operators are: "==", "!=", "oneOf", and "!oneOf".

The operand must be either a string or an array of strings (for the oneOf operators).

Example

Only show conversations with "Black leather boots" or "Hair Wax 5 Gallons" as the subject


1{ subject: ["oneOf", ["Black leather boots", "Hair Wax 5 Gallons"]] }

type StringFilter

A two-element array that forms a predicate about a field.

Used in MessagePredicate and ConversationPredicate. Possible forms:

- ["==", "someValue"]

- ["!=", "someValue"]

- ["oneOf", ["someValue", "someOtherValue"]]

- ["!oneOf", ["someValue", "someOtherValue"]]

type NumberFilter

A two-element array that forms a predicate about a numeric field.

Used in ConversationPredicate. Possible forms:

- [">", someNumber]

- ["<", someNumber]

- [">=", someNumber]

- ["<=", someNumber]

- ["between", [lowerBound, upperBound]]

- ["!between", [lowerBound, upperBound]]

The lower bound is inclusive, the upper bound is exclusive.

type CustomFilter

A string or a two-element array that forms a predicate about a string field in a custom field.

Used in MessagePredicate and ConversationPredicate. Allows all forms in StringFilter plus the following:

- "exists"

- "!exists"

type CompoundFilter

Combines multiple simple filters into one, matching whenever any of the simple filters match (OR).

The first element must be the string "any", and the second element a list of simple filter objects.

See SimpleConversationFilter for all available options in simple conversation filters.

Example

Only show conversations with messages, and empty conversations with the subject "cats!"


1["any", [
2  { hasMessages: true },
3  { subject: ["==", "cats!"] }
4]]