Filter messages

Message filters let you control which messages appear in a chat, based on properties such as the sender, message type, or creation time.

This guide shows how to set and combine message filters in a chatbox using the setMessageFilter method in the classic JavaScript SDK. You can also use setMessageFilter with the Inbox and Popup UIs. For other SDKs, check out their messageFilter reference docs:

Set up a message filter

Use setMessageFilter to control which messages the chatbox displays. For example, to show only messages from a user with the ID sample_user_alice:

1chatbox.setMessageFilter({ sender: { id: ['==', 'sample_user_alice'] } });

You can pass one or more filter conditions to match messages by sender, timestamp, message type, or other properties.

Filter types

The following examples show how to use different filters.

Time created filter

Use the createdAt filter to show all messages created before, after, or between timestamps (in Unix milliseconds). For example:

1// Messages created after the specified timestamp
2chatbox.setMessageFilter({ createdAt: ['>', 1719298371586] });
3

4// Messages created between two timestamps
5chatbox.setMessageFilter({
6  createdAt: ['between', [1619298371586, 172298371586]],
7});

Sender filter

Use the sender filter to match messages from specific users or roles. For example:

1// Messages from a single sender
2chatbox.setMessageFilter({
3  sender: { id: ['==', 'sample_user_alice'] },
4});
5

6// Messages where the sender has both a role and email
7chatbox.setMessageFilter({
8  sender: { role: ['==', 'admin'], email: ['==', '[email protected]'] },
9});

Custom property filter

Use the custom filter to match messages that include specific custom fields. For example:

1// Messages with a custom category of 'shoes'
2chatbox.setMessageFilter({ custom: { category: ['==', 'shoes'] } });
3

4// Messages with a topic of 'inquiry' or 'reservation'
5chatbox.setMessageFilter({
6  custom: { topic: ['oneOf', ['inquiry', 'reservation']] },
7});

Origin filter

Filter messages by their creation source:

  • web: messages sent in the chat UI
  • rest: message created with the REST API
  • import: messages imported with the REST API
  • email: messages created by replying via email

For example:

1// Exclude imported messages
2chatbox.setMessageFilter({ origin: ['!=', 'import'] });

Message type filter

Use the type filter to choose whether a message is user-generated or system-generated. For example:

1// Show only system messages
2chatbox.setMessageFilter({ type: ['==', 'SystemMessage'] });

Combine message filters

You can combine multiple filters to match complex conditions. You can filter for messages that match all conditions or any of them.

Match all conditions

Pass an array of filters to show messages that match all conditions. For example:

1// Show system messages created after a set timestamp
2chatbox.setMessageFilter([
3  { type: ['==', 'SystemMessage'] },
4  { createdAt: ['>', 1719298371586] },
5]);

Match any condition

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

1// Show messages that are system messages or created
2// after a specified timestamp, or both
3chatbox.setMessageFilter([
4  'any',
5  [{ type: ['==', 'SystemMessage'] }, { createdAt: ['>', 1719298371586] }],
6]);

No filter

To turn off filtering and show all messages, use an empty filter:

1chatbox.setMessageFilter({});

Operator reference

The following operators are available when defining message filters.

OperatorDescriptionExample
==Equals{ type: ['==', 'SystemMessage'] }
!=Not equal{ origin: ['!=', 'import'] }
> / <Greater than or less than (for timestamps){ createdAt: ['>', 1719298371586] }
betweenBetween two values{ createdAt: ['between', [start, end]] }
oneOfMatches one of several values{ custom: { topic: ['oneOf', ['inquiry', 'reservation']] } }