What channels and threads hold

A channel and a thread hold their conversations the same way. Each has its own state store, message paginator, composer, message operations and read state. A thread still belongs to a channel: it's identified by a message in that channel, and a few things, such as members, capabilities and settings, exist only on the channel.

This page lists what they share, then what belongs only to a channel or only to a thread. Getting a channel or a thread, and loading it, is on Shared entities.

What channels and threads share

A thread belongs to its channel, thread.channel. thread.state has no typing field: who's typing in a thread is in the typing field of channel.state, which maps each typing user's id to their typing event. Keep the entries whose parent_id is the thread's id.

Each state is one store. Read a field once with getLatestValue(), or subscribe and select the fields you need:

const ownUserId = client.userId;

const unsubscribe = channel.state.subscribeWithSelector(
  ({ memberCount, read }) => ({
    memberCount,
    unread: ownUserId ? (read[ownUserId]?.unread_messages ?? 0) : 0,
  }),
  ({ memberCount, unread }) => {
    console.log(`${memberCount} members, ${unread} unread`);
  },
);

Where each part is explained

• The message paginator: Message paginators.
• The composer: Message composer.
• Message operations: Message operations.
• Read state: Read state and unread counts.
• Typing: Typing indicators.
• What keeps a channel or a thread in memory: Entity lifecycle.

Channel

Data and members

channel.state holds these fields:

channel.data, channel.state.members and the other getters on channel and channel.state return the value at the moment you read them. They don't tell you when it changes. To follow a change, subscribe to channel.state and select the field. Reactive state explains why.

Membership

membership is the current user's membership in the channel: their role, when they joined, and two dates the user sets for themselves:

• archived_at is set while the user has archived the channel;
• pinned_at is set while the user has pinned it.

Channel.archive(), Channel.unarchive(), Channel.pin() and Channel.unpin() change them. The change shows when the server's member.updated event arrives, not when the call returns. Channel paginators filtered on archived or pinned move the channel at the same moment.

const unsubscribe = channel.state.subscribeWithSelector(
  ({ membership }) => ({
    archived: !!membership.archived_at,
    pinned: !!membership.pinned_at,
  }),
  ({ archived, pinned }) => {
    console.log({ archived, pinned });
  },
);

await channel.archive(); // the handler runs again when member.updated arrives

Capabilities

Capabilities say what the current user may do in this channel, such as send-message, upload-file, send-reaction or skip-slow-mode. The server derives them from the user's roles and the channel type's permissions.

They're in the ownCapabilities field of channel.state, and they update when the channel is loaded again or when channel.updated carries new ones. When a query or Channel.updatePartial() returns different capabilities, the client also dispatches capabilities.changed.

const canReact = channel.state
  .getLatestValue()
  .ownCapabilities.includes("send-reaction");

Settings

Settings say which features the channel has, such as typing events, read events and replies. There are two views of them:

• channel.config is what's in effect: the channel type's settings combined with what the app registered in client.config. channel.configState is the same value as a store.
• channel.serverConfig is the channel type's settings as the server sent them: typing_events, read_events, replies, uploads and the others. It's undefined until the channel has been loaded.

Check channel.config, not channel.serverConfig. Either side can turn a feature off, and only config includes both:

const { readEvents, replies, typingEvents } = channel.config;

console.log({
  readEvents: readEvents.enabled,
  replies: replies.enabled,
  typingEvents: typingEvents.enabled,
});

Configuration explains which settings the client decides, which the server decides, and which need both.

Mute

The muteStatus field of channel.state says whether the current user muted the channel: { muted, createdAt, expiresAt }, with the dates in nanoseconds or null.

Channel.mute() and Channel.unmute() change it. Channel.mute({ expiration }) mutes for that many milliseconds. Like membership, the field changes when the server's event arrives, notification.channel_mutes_updated. A muted channel's new messages don't count as unread.

Slow mode

In slow mode, a user waits a number of seconds between messages. The channel's data.cooldown holds the number of seconds, and Channel.enableSlowMode(seconds) and Channel.disableSlowMode() change it.

Each channel has a cooldown timer, channel.cooldownTimer. Its state counts down for the current user:

const unsubscribe = channel.cooldownTimer.state.subscribeWithSelector(
  ({ cooldownRemaining }) => ({ cooldownRemaining }),
  ({ cooldownRemaining }) => {
    console.log(
      cooldownRemaining > 0 ? `Wait ${cooldownRemaining}s` : "You can send",
    );
  },
);

Slow mode shows how the composer uses it.

Thread

Parent message and replies

A thread is identified by its parent message: thread.id is the parent message's id. thread.state holds:

The parent message is the same message object the channel's message paginator holds. An edit or a reaction on it shows in both places, and parentMessage and replyCount follow it.

The replies are in thread.messagePaginator. A reply also sent to the channel, with show_in_channel, is in the channel's message paginator too.

client.threads.ensure({ channel, parentMessage }) returns the thread for a message, creating it if the client doesn't have it yet, without a request. A thread created this way knows only its parent message. When it may have replies the client doesn't hold, it loads them the first time it's activated, which the UI does when it opens the thread:

const thread = client.threads.ensure({ channel, parentMessage: message });

// The user opened the thread. Call release() when they close it.
const release = thread.activate();

While a thread is active:

• a new reply doesn't count as unread for the current user, and the thread marks itself read;
• when its state is stale, it loads again.

These happen only while the thread manager, client.threads, listens to events: after ThreadManager.registerSubscriptions(). The React SDK calls it for you.

The user's threads

The thread manager, client.threads, keeps the user's threads. Its paginator, client.threads.paginator, loads the threads, and client.threads.state holds what applies to all of them:

ThreadManager.reload() loads the thread paginator again when it hasn't loaded yet, when there are unseen threads, or when the order is stale, and clears both once the load succeeds. ThreadManager.reload({ force: true }) loads it in any case.

const unsubscribe = client.threads.state.subscribeWithSelector(
  ({ unreadThreadCount, unseenThreadIds }) => ({
    unreadThreadCount,
    unseenThreadIds,
  }),
  ({ unreadThreadCount, unseenThreadIds }) => {
    console.log(
      `${unreadThreadCount} unread threads, ${unseenThreadIds.length} new`,
    );
  },
);

The thread list itself is on Replies and threads, and its API on Thread and thread manager.

Used in

• Channel details and members
• Replies and threads
• Slow mode
• Flagging, muting, blocking and bans