History visibility for new members

When someone is added to a channel, the app decides how much of the earlier conversation they see: all of it, none of it, or what was sent after a date. This page covers the options that decide it. The Hide history for new members recipe builds a dialog that lets the user choose.

What users get

The user adds Bob to the "Design" channel. Depending on how they add him, Bob opens the channel and sees:

• every message, as with any member;
• only the messages sent after he joined;
• only the messages sent after a date the user picked, for example the last seven days.

The choice is made once, when Bob is added. Messages sent after he joins are visible to him either way.

How it works across the layers

State: the options on Channel.addMembers()

Channel.addMembers({ members, ...options }) adds members. Next to members, the request takes two history options:

• hide_history: true hides every message sent before the member joined.
• hide_history_before hides the messages sent before a Date. The date must be in the past. When both are given, hide_history_before applies.

Without either option, the new member sees the whole history.

// Bob sees nothing sent before he joined.
await channel.addMembers({ members: ["bob"], hide_history: true });

// Carol sees the last seven days.
const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
await channel.addMembers({
  members: ["carol"],
  hide_history_before: sevenDaysAgo,
});

hide_history_before is typed as a Date. Pass the Date itself, not a string.

The second argument is an optional message that announces the change in the channel, such as { text: "Bob joined the design team" }. Pass undefined to add members without one.

The server applies the options. From then on, the channel's messages that the server returns to the new member start at the cutoff, so the client has nothing to filter. The existing members' view doesn't change.

UI: no built-in control

The SDK has no control for these options. The Add view in channel details calls Channel.addMembers(userIds) without them, so members added there see the whole history. To let users choose, call addMembers from your own UI, as the recipe does.

Turning it on or off

There's nothing to configure. Each Channel.addMembers() call decides for the members it adds.

Adding members needs the update-channel-members capability. Permissions reference explains how the server grants it.

Customizing

Letting the user choose

The Hide history for new members recipe builds a dialog with four choices: no history, from today, from the beginning, or from a custom date. It maps each choice to the options above.

Hiding history for every member your app adds

To apply one rule everywhere, add members through one function of your own:

import type { Channel } from "stream-chat";

// Every member this app adds sees the last 30 days of history.
export const addMembersWithRecentHistory = (
  channel: Channel,
  userIds: string[],
) => {
  const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
  return channel.addMembers({
    members: userIds,
    hide_history_before: cutoff,
  });
};

Reference

• Channel and channel state: addMembers and the other member methods.
• Hide history in the Chat API docs: the server's rules for both options.