Message filters

Message filters allow you to select which messages you see in your chatbox, inbox or popup based on properties like the sender ID, message type or the time the message was created.

To filter messages with the JavaScript SDK, use the setMessageFilter method. This link is to the chatbox, but you can also use setMessageFilter on the Inbox or Popup.

For example, to display only messages from a user with an ID of sample_user_alice in your chatbox, use:

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

The same filters are available in our other SDKs. See the following reference docs for more details:

Message list filter types

This section gives an overview of message filter types. In the following examples, we'll filter a chatbox with the JavaScript SDK, but these filters also apply to an inbox or popup, and to other SDKs.

No filter

To show all messages, use an empty message filter:

1chatbox.setMessageFilter({});

Use this filter to disable any existing filters.

Time created filter

To select all messages created within within or outside a given time interval, use the createdAt filter.

For example, the following filter selects messages created after the Unix timestamp 1679298371586:

1chatbox.setMessageFilter({ createdAt: ['>', 1719298371586] });

The following filter selects messages created between the timestamps 1619298371586 and 172298371586:

1chatbox.setMessageFilter({
2  createdAt: ['between', [1619298371586, 172298371586]],
3});

Sender filter

To select all messages where the sender matches given properties, use the sender filter.

For example, the following filter displays all messages where the sender has a role of admin and an email of [email protected]:

1chatbox.setMessageFilter({
2  sender: { role: ['==', 'admin'], email: ['==', '[email protected]'] },
3});

Custom message property filter

To select all messages with given custom fields, use the custom filter.

For example, the following filter displays all messages with a category of shoes:

1chatbox.setMessageFilter({ custom: { category: ['==', 'shoes'] } });

The following filter displays all messages with a topic of either inquiry or reservation:

1chatbox.setMessageFilter({
2  custom: { topic: ['oneOf', ['inquiry', 'reservation']] },
3});

Origin filter

To select messages by the method that they were created (by users in the web app, by the REST API, by the import REST API, or by replying to email), use the origin filter.

For example, to exclude messages that were sent by the REST API, use:

1chatbox.setMessageFilter({ origin: ['!=', 'rest'] });

Message type filter

To select messages by type (user message or system message), use the type filter.

For example, to show only system messages, use:

1chatbox.setMessageFilter({ type: ['==', 'SystemMessage'] });

Combine message filters

You can combine multiple conditions in a message filter. You can either filter for messages that match all of the conditions, or for messages that match any one of the conditions.

Match all conditions

To show messages that match multiple conditions, pass an array of filters. For example, to show messages that have a type of SystemMessage and a creation time of after 172298371586, use:

1chatbox.setMessageFilter([
2  { type: ['==', 'SystemMessage'] },
3  { createdAt: ['>', 1719298371586] },
4]);

Match any condition

To show messages that match one or more of multiple conditions, use the any operator on an array of filters. For example, to show messages that have a type of SystemMessage or a creation time of after 172298371586 (or both), use:

1chatbox.setMessageFilter([
2  'any',
3  [{ type: ['==', 'SystemMessage'] }, { createdAt: ['>', 1719298371586] }],
4]);