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 data.custom and ignores the rest of data.
• A stored channel that was disposed is replaced by a new instance.
• Without an id, data.members creates a distinct channel between those members, or returns a loaded distinct channel with the same members. A new one is 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:

With offline support, a channel loaded from the local database has offlineMode: true and initialized: false until the server answers. Check both to tell whether a channel has any data: initialized || offlineMode.

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

In a component, read the same fields with useStateStore(channel.state, selector) from stream-chat-react-native, with the selector defined outside the component.

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. Editing a field of channel.data in place doesn't reach the store at all.

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.

The Channel component does this for the channel it renders, and activates the channel until it unmounts. When it mounts, it sets messagePaginator.pageSize to 25 unless a page size is registered in client.config, then calls Channel.watch() unless the channel is initialized, its message list shows the newest messages, and its watchStatus isn't "notWatching". A "wasWatching" channel is left to the connection recovery. With initializeOnMount={false} it doesn't watch. When the watch fails, it sets offlineMode to true. See Channel.

Outside Channel, for example on a channel details screen of your own, this keeps a channel loaded while the 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

Channel.addMembers(), Channel.removeMembers() and Channel.inviteMembers() each take one request object. Apart from the members, it can hold message, a system message to send with the change, and any other field of Channel.update(), such as hide_history:

This adds two members without showing them the history from before they joined:

await channel.addMembers({ members: ["bob", "cara"], hide_history: true });

Channel data

Read state

Typing, events and AI

The message composer calls Channel.keystroke() as the user types while its text.publishTypingEvents setting is on. Channel.stopTyping() runs before each send, and about a second after the last keystroke. An app that uses the SDK's composer doesn't call them.

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 and, with offline support, queues the request while the device is offline.
• Channel.getPinnedMessages(request), Channel.getMessagesById(ids), Channel.queryChannelBans(request) and Channel.getDraft(request).
• Channel.createDraft(request) and Channel.deleteDraft(request). With offline support, they're queued as pending tasks when the device is offline. The message composer calls them when drafts are on.
• Channel.uploadFile(request), Channel.uploadImage(request), Channel.deleteFile({ url }) and Channel.deleteImage({ url }).
• Channel.sendAction(messageId, formData), which runs a message action such as the buttons of a Giphy preview.
• Channel.vote(...) and Channel.removeVote(...) for polls, and Channel.sendSharedLocation(location) and Channel.stopLiveLocationSharing(location) for locations. With offline support, Channel.sendSharedLocation() with a message_id is queued like a message.

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.