Channel and channel state

A Channel is the client's object for one channel. Its data, members, read state and typing users are in the store channel.state. Its messages, pinned messages, composer and message operations are objects it owns. This page lists the API of Channel and ChannelState in stream-chat.

What a channel holds, and why, is explained on What channels and threads hold. Getting and loading a channel is explained on Shared entities.

Getting a channel

The client keeps one Channel per cid. Get it from the client instead of constructing it with new Channel():

A few rules apply to client.channel():

• It throws without a user. Call it after client.connectUser(), which doesn't have to finish first.
• For a channel the client already stores, it applies only the custom field of its last argument and ignores the rest.
• A stored channel that was disposed is replaced by a new instance.
• Without an id, members creates a distinct channel between those members. It's provisional until its first query answers. A channel with neither isn't stored.

This opens "general" and watches it, whether or not another part of the app is opening it at the same time:

const general = await client.channel("messaging", "general").watch();

A channel identifies itself with these properties:

The objects a channel owns

A thread has its own message list, composer and message operations. Inside a thread, use the thread's, not the channel's.

channel.state fields

channel.state is a ChannelState, a store of ChannelStateData. Every field below is in that one store, so a subscription selects the fields it needs:

Each entry of read has these fields. The timestamps are in nanoseconds:

Read state and unread counts explains which events change it.

This handler runs whenever the member count or the current user's unread count changes:

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`);
  },
);

Getters

These getters return the value at the moment you read them, and don't tell you when it changes. To follow a change, subscribe to channel.state.

channel.state.pending_messages holds the channel's pending messages from the last query. It isn't in the store.

Some of these have setters. They exist for the SDK: app code changes a channel through the methods below, not by writing its state.

Configuration

A channel has two views of its settings:

• channel.config is the configuration in effect: the channel type's server 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 (ChannelConfigWithInfo): typing_events, read_events, replies, uploads, url_enrichment, polls, max_message_length, commands and the rest. It's undefined until the channel has been queried or watched.

Check channel.config to decide whether a feature is available. Either side can turn a feature off, and only config includes both. channel.config has these fields:

Change these through client.config, under the channel key. A channel has no updateConfig():

client.config.set({
  channel: {
    readEvents: { enabled: false, localUnreadCountEnabled: true },
    typingEvents: { enabled: false },
  },
});

The channel key also holds messagePaginator, pinnedMessagesPaginator and messageOperations, which go to the objects the channel owns. Configuration explains how settings resolve, and Configuration tree lists every key.

Loading and lifecycle methods

options for Channel.watch(), Channel.query() and Channel.create() is a ChannelGetOrCreateRequest: messages, members and watchers pagination, presence, state, watch, data and a few more. Channel.watch() and any query with watch: true wait for the WebSocket to connect. Shared entities explains loading, and Entity lifecycle explains activation and disposal.

This keeps a channel loaded while a screen shows it:

const openScreen = async (id: string) => {
  const opened = await client.channel("messaging", id).watch();
  // Until release() is called, reconnects reload the channel.
  const release = opened.activate();
  return { channel: opened, close: release };
};

Channel actions

Most methods below send a request. Unless the table says otherwise, the change shows when the server's event arrives, not when the call returns. Most of them take an optional requestOptions as their last argument, which carries an abort signal. Channel.banUser(), Channel.unbanUser(), Channel.markReadViaReporter() and Channel.sendSharedLocation() don't. What's optimistic and what isn't lists how each action settles.

The current user's membership

Members

message and options are optional, except that Channel.banUser() needs options, even if it's {}. message is a system message to send with the change.

Channel data

Read state

Typing, events and AI

Requests that change no state

These send the request and return the response. Nothing in the channel's state changes until an event arrives:

• Channel.sendMessage(request), Channel.sendReaction(...) and Channel.deleteReaction(...). Use channel.messageOperations, which also updates the message list.
• Channel.getPinnedMessages(request), Channel.getMessagesById(ids), Channel.queryChannelBans(request) and Channel.getDraft(request).
• Channel.uploadFile(request), Channel.uploadImage(request), Channel.deleteFile({ url }) and Channel.deleteImage({ url }).
• Channel.vote(...) and Channel.removeVote(...) for polls, and Channel.sendSharedLocation(location) and Channel.stopLiveLocationSharing(location) for locations.

Events

Channel.on(type, handler) and Channel.on(handler) subscribe to the channel's events, and return { unsubscribe }. Channel.off(type, handler) removes a handler. The client applies an event to the channel's state before any handler runs, so a handler reads the updated state. A disposed channel's state no longer changes, but its handlers still run.

const { unsubscribe } = channel.on("member.added", (event) => {
  // channel.state already holds the new member
  console.log(`${event.member?.user?.name} joined`, channel.state.members);
});

The channel changes its state on these events:

These are handled by the client, for every channel it stores:

The client also dispatches events of its own. capabilities.changed fires when a query or Channel.updatePartial() returns different capabilities, and channels.queried fires after every query.

See also

• What channels and threads hold explains the channel's state.
• Shared entities and Entity lifecycle explain getting, loading and releasing channels.
• Thread and thread manager lists the API of threads.