Conversation list filters

If you use the Inbox pre-built chat UI, you can use conversation list filters to select which conversations show up in the conversation list of the user's inbox.

You can filter conversation lists with the JavaScript Chat SDK. You can also use similar filters in the REST API to select which conversations you return.

Filter your conversation list

To filter conversations, use the InboxOptions.feedFilter object.

As an example of a conversation list filter, {hasUnreadMessages: true} selects conversations with the hasUnreadMessages property set to true.

You can add a conversation list filter to your inbox in the following ways:

Pass it to the Inbox.setFeedFilter method. For example, to select only conversations with unread messages, use:
```
1inbox.setFeedFilter({ hasUnreadMessages: true });
```
Pass it to the Session.createInbox method. For example, to again select only conversations with unread messages, use:
```
1const inbox = session.createInbox({ hasUnreadMessages: true });
```

Conversation list filter types

This section gives an overview of conversation list filter types. For more information, see our ConversationPredicate reference docs.

No filter

To show all conversations, use an empty conversation list filter:


1inbox.setFeedFilter({});

Use this filter to disable any existing filters.

Unread message filter

This filter lets you select only conversations with unread messages:


1inbox.setFeedFilter({ hasUnreadMessages: true });

Time interval filters

These filters let you select conversations where the following properties are within or outside a given time interval:

createdAt: the time conversation was created
lastMessageTs: the time the last message in the conversation was created

For example, the following filter selects conversations where the last message was created after the Unix timestamp 1672531200:


1inbox.setFeedFilter({ lastMessageTs: ['>', 1672531200] });

The following filter selects conversations that were created between the Unix timestamps 1672531200 and 1685574000:


1inbox.setFeedFilter({ createdAt: ['between', [1672531200, 1685574000]] });

String filters

These filters let you select conversations where the following properties either match or do not match a given string:

access: the level of access the user has
subject: the subject of the conversation

For example, the following filter selects conversations where the access level is not "None", to remove conversations the user no longer has access to:


1inbox.setFeedFilter({ access: ['!=', 'None'] });

The following filter selects conversations where the subject is one of "Welcome" or "Hello":


1inbox.setFeedFilter({ subject: ['oneOf', ['Welcome', 'Hello']] });

Custom property filter

This filter lets you select conversations where the custom property has given keys, or where keys in the custom property have values that match or do not match a given string.

For example, the following filter selects conversations where the custom category key exists:


1inbox.setFeedFilter({ custom: { category: 'exists' } });

The following filter selects conversations where the category key has a value of shoes or sandals:


1inbox.setFeedFilter({ custom: { category: ['oneOf', ['shoes', 'sandals']] } });

Combine conversation list filters

You can combine multiple conditions in a conversation list filter. Only conversations that match all the conditions will be returned.

For example, the following filter selects all conversations where the last message was received after the timestamp 1672531200, and where there are unread messages:


1inbox.setFeedFilter({
2  lastMessageTs: ['>', 1672531200],
3  hasUnreadMessages: true,
4});

Filter conversations with the REST API

The REST API allows you to select which conversations you return by making a GET request for conversations with the filter query string parameter. You can use the same conversation list filter types as the JavaScript SDK.

You must URL encode the conversation list filter before you use it, with no spaces in the filter and double quotes around properties and strings. For example, a filter that selects conversations where the category key has a value of shoes should be written as


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

and then encoded in the filter parameter as


1?filter=%7B%22custom%22%3A%7B%22category%22%3A%5B%22%3D%3D%22%2C%22shoes%22%5D%7D%7D

You can also filter conversations by when the last message was sent to the conversation with the lastMessageBefore and lastMessageAfter query string parameters.

For example, the following query string parameters get conversations where the last message was sent between the Unix timestamps 1701700000000 and 1702000000000 (in milliseconds):


1?lastMessageAfter=1701700000000&lastMessageBefore=1702000000000