---
url: https://talkjs.com/docs/Data_APIs/JavaScript/Filters
title: 'Filters'
minidoc-source: js
minidoc-lib: data-api
---

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

## 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.
A simple conversation filter that only includes conversations with the subject "cats!"
```json
{ subject: ["==", "cats!"] }
```
A compound conversation filter that includes conversations with messages, and empty conversations with the subject "cats!" ```json ["any", [ { hasMessages: true }, { subject: ["==", "cats!"] } ]] */
export type ConversationFilter = SimpleConversationFilter|CompoundFilter<SimpleConversationFilter>;

## 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.
Only include conversations with unread messages
```ts
session.subscribeConversations(onSnapshot, {
filter: { isUnread: true }
});
``` */
export interface SimpleConversationFilter  {
/** 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).
Hide conversations that the user cannot send messages to
```json
{ access: ["!=", "ReadWrite"] }
``` */
access?: StringFilter<"ReadWrite"|"Read">;
/** 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).
Only show conversations that were created after the UNIX timestamp 1679298371586
```json
{ createdAt: [">", 1679298371586] }
``` */
createdAt?: NumberFilter;
/** 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"`.
Only show messages that have no custom `category` set
```json
{ custom: { category: "!exists" } }
```
Only show messages of that have the custom category "shoes"
```json
{ custom: { category: ["==", "shoes"] } }
```
Only show messages that have a 'topic' of either "inquiry" or "reservation"
```json
{
custom: {
topic: ["oneOf", ["inquiry", "reservation"]]
}
}
```
Only show messages about shoes that are marked visible
```json
{
custom: {
category: ["==", "shoes"],
visibility: ["==", "visible"]
}
}
``` */
custom?: CustomFilter;
/** Only select conversations that have, or do not have messages.
Only show conversations that have at least one message
```json
{ hasMessages: true }
```
Only show empty conversations
```json
{ hasMessages: false }
``` */
hasMessages?: boolean;
/** Set this field to only select conversations that have, or don't have any, unread messages. */
isUnread?: boolean;
/** 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).
Only show conversations joined after the UNIX timestamp 1679298371586
```json
{ joinedAt: [">", 1679298371586] }
``` */
joinedAt?: 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).
Only show conversations that had messages sent after the UNIX timestamp 1679298371586
```json
{ lastMessageTs: [">", 1679298371586] }
``` */
lastActivityAt?: NumberFilter;
/** 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).
Only show conversations with "Black leather boots" or "Hair Wax 5 Gallons" as the subject
```json
{ subject: ["oneOf", ["Black leather boots", "Hair Wax 5 Gallons"]] }
``` */
subject?: StringFilter<string|null>;
}

## 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"]]` */
export type StringFilter<T = string>= ["=="|"!=", T]|["oneOf"|"!oneOf", T[]];

## 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. */
export type NumberFilter = [">"|"<"|">="|"<=", number]|["between"|"!between", [number, number]];

## 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"` */
export type CustomFilter = Record<string, StringFilter|"exists"|"!exists">;

## 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.
Only show conversations with messages, and empty conversations with the subject "cats!"
```json
["any", [
{ hasMessages: true },
{ subject: ["==", "cats!"] }
]]
``` */
export type CompoundFilter<T>= ["any", T[]];