Filter a conversation list

Conversation list filters let you control which conversations appear in an inbox or conversation list, based on properties such as unread status, creation time, subject, or custom fields.

This guide shows how to set and combine conversation list filters in an Inbox using the feedFilter method in the classic JavaScript SDK. You can also use feedFilter with the Conversation list in one of the mobile SDKs. You can use the same filters with the REST API to control which conversations you return. See also the following feedFilter reference docs:

Set up a conversation list filter

To filter conversations, use the InboxOptions.feedFilter object. For example, {hasUnreadMessages: true} selects conversations with the hasUnreadMessages property set to true.

You can apply a filter when creating or updating an Inbox instance. To add a filter when creating an Inbox, pass it to the Session.createInbox method. For example:

1// Show only conversations with unread messages
2const inbox = session.createInbox({ hasUnreadMessages: true });

To add a filter when updating an Inbox, pass it to the Inbox.setFeedFilter method. For example:

1// Show only conversations with unread messages
2inbox.setFeedFilter({ hasUnreadMessages: true });

Filter types

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

Unread message filter

Use this filter to select only conversations with unread messages:

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

Time filters

These filters let you select conversations where the following properties occur before, after, within, or outside a given time range:

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

For example, to show only conversations that were created between two timestamps (in Unix milliseconds):

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

Or to show only conversations with a last message sent after the given timestamp:

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

String filters

These filters let you select conversations where the following properties either match or don't 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 isn't "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 includes specific keys, or where keys in the custom property have values that match or don't 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 filters

You can combine multiple conditions to match conversations that meet all or any of your criteria.

Match all conditions

Pass multiple conditions to show conversations that match all of them. For example:

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

Match any condition

Use the any operator to show conversations that match any of the listed filters. For example:

1inbox.setFeedFilter([
2  'any',
3  [{ access: ['==', 'Read'] }, { custom: { accountId: ['==', 'my_account'] } }],
4]);

No filter

To remove all filters and show every conversation, use an empty filter:

1inbox.setFeedFilter({});

This clears any filters currently applied.

REST API conversation filters

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 first express the filter as a JSON object, then URL encode it before including it in the filter parameter. Use double quotes around property names and string values, and make sure the encoded string contains no spaces. 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 1660441820561 and 1760441882143 (in milliseconds):

1?lastMessageAfter=1660441820561&lastMessageBefore=1760441882143

Operator reference

You can use the following operators to define conversation filters:

OperatorDescriptionExample
==Equals{ 'category': ['==','shoes']}
!=Not equal{ 'access': ['!=', 'None'] }
> / <Greater than or less than (for timestamps){ 'createdAt': ['>', 1760441882143] }
betweenBetween two values{ 'createdAt': ['between', [start, end]] }
anyMatches any of several values['any', [{ access: ['==', 'Read'] }, { createdAt: ['>', 1760441882143] }]]
oneOfMatches one of several values{ 'custom': { topic: ['oneOf', ['inquiry', 'reservation']] } }