Guide to Channel State – getstream.io

Chances are, if you’ve been creating / querying channels using our API, you’ve come across channel state. If not, you can execute the following code:

client.queryChannels({cid: 'messaging:example-id'}, {}, {}).then((res) => {
 const state = res[0].state;
 console.log(state);
});

Channel state contains valuable information about (you guessed it!) the current state of a particular channel. It can be quite a lot to digest but let’s dive in and start off with the response to executing the code above.

ChannelState {
 _channel: Channel {
  _client: StreamChat {
   _user: [Object],
   activeChannels: [Object],
   anonymous: false,
   axiosInstance: [Function],
   baseURL: 'https://chat-us-east-1.stream-io-api.com',
   browser: false,
   cleaningIntervalRef: Timeout {
    _idleTimeout: 500,
    _idlePrev: [TimersList],
    _idleNext: [TimersList],
    _idleStart: 607,
    _onTimeout: [Function],
    _timerArgs: undefined,
    _repeat: 500,
    _destroyed: false,
    [Symbol(refed)]: true,
    [Symbol(asyncId)]: 6,
    [Symbol(triggerId)]: 1
   },
   clientID: 'Lan--cdundefinedV78eYq9undefinedUur6agzbvZ',
   configs: [Object],
   connecting: true,
   connectionID: undefined,
   failures: 0,
   key: 'uj7u2u3qzj74',
   listeners: {},
   logger: [Function],
   recoverStateOnReconnect: true,
   mutedChannels: [],
   mutedUsers: [],
   node: true,
   options: [Object],
   secret: '9b77cfjx44ns4q6942f6apuh2pygymquvwt6ytsyeh67hwnrrjqz4kbpq7gyaeg8',
   setUserPromise: [Promise],
   state: [ClientState],
   tokenManager: [TokenManager],
   user: [Object],
   userAgent: undefined,
   userID: 'Lan',
   wsBaseURL: 'wss://chat-us-east-1.stream-io-api.com',
   wsConnection: [StableWSConnection],
   wsPromise: [Promise],
   _hasConnectionID: [Function],
   connectUser: [Function],
   setUser: [Function],
   _setToken: [Function],
   closeConnection: [Function],
   openConnection: [Function],
   _setupConnection: [Function],
   disconnectUser: [Function],
   disconnect: [Function],
   connectAnonymousUser: [Function],
   setAnonymousUser: [Function],
   doAxiosRequest: [Function],
   dispatchEvent: [Function],
   handleEvent: [Function],
   _callClientListeners: [Function],
   recoverState: [Function],
   getChannelByMembers: [Function],
   getChannelById: [Function],
   updateUsers: [Function: upsertUsers],
   updateUser: [Function: upsertUser],
   _isUsingServerAuth: [Function]
  },
  type: 'messaging',
  id: 'example-id',
  data: {
   id: 'example-id',
   type: 'messaging',
   cid: 'messaging:example-id',
   created_at: '2021-03-29T16:53:19.552723Z',
   updated_at: '2021-03-29T16:53:19.552723Z',
   created_by: [Object],
   frozen: false,
   config: [Object]
  },
  _data: {},
  cid: 'messaging:example-id',
  listeners: {},
  state: [Circular],
  initialized: true,
  lastKeyStroke: undefined,
  lastTypingEvent: null,
  isTyping: false,
  disconnected: false,
  create: [Function],
  _callChannelListeners: [Function],
  _channelURL: [Function]
 },
 watcher_count: 0,
 typing: {},
 read: {},
 messages: [],
 pinnedMessages: [],
 watchers: {},
 members: {},
 unreadCount: 0,
 membership: {},
 last_message_at: null
}

As you can see, channel state is quite extensive and contains a lot of useful information that you’ll most likely want to utilize at some point in your Stream integration. I’ll be breaking down all of the most relevant information associated with channel state so that you are fully aware of each individual property and what they are best used for. For expectation purposes, I’ll largely be ignoring most of the response above to focus specifically on the most commonly used properties unique to state which include:

{
 watcher_count: 0,
 read: {},
 messages: [],
 pinnedMessages: [],
 mutedUsers: [],
 watchers: {},
 members: {},
 unreadCount: 0,
 membership: {},
 last_message_at: null,
}

watcher_count

The watcher_count is the number of users actively watching a particular channel. Watching a channel can be done in a couple different ways. For instance, `channel.watch()` is a common approach. Also, when calling `queryChannels()` client-side, the channels returned are watched by default (keep in mind, you can specify otherwise). An important thing to note is that connect events will need to be enabled in order to receive an accurate watcher count. You can enable / disable these on a channel type basis from your dashboard.

Watching a Channel

read

An object containing the members of the channel along with their respective read statuses (i.e. last_read, unread_messages).

{
 example-id: {
  user: {
   id: 'example-id',
   role: 'user',
   created_at: '2021-03-09T18:26:47.113535Z',
   updated_at: '2021-04-09T21:35:00.779703Z',
   last_active: '2021-04-27T20:08:40.553919048Z',
   banned: false,
   online: true,
   name: 'cool guy Lan'
  },
  last_read: 2021-03-30T20:31:40.695Z,
  unread_messages: 0
 }
}

messages

An array of the 25 most recent messages sent in a particular channel.

[
 {
  id: 'example-id',
  text: 'wow, neat!',
  html: '<p>wow, neat!</p>\n',
  type: 'regular',
  user: {
   id: 'example-id',
   role: 'user',
   created_at: '2021-03-09T18:26:47.113535Z',
   updated_at: '2021-03-29T20:44:09.795212Z',
   last_active: '2021-03-29T20:44:09.795212Z',
   banned: false,
   online: false
  },
  attachments: [],
  latest_reactions: [],
  own_reactions: [],
  reaction_counts: {},
  reaction_scores: {},
  reply_count: 0,
  cid: 'messaging:example-id',
  created_at: 2021-03-18T15:20:50.594Z,
  updated_at: 2021-03-18T15:20:50.594Z,
  shadowed: false,
  mentioned_users: [],
  silent: false,
  pinned: false,
  pinned_at: null,
  pinned_by: null,
  pin_expires: null,
  __html: '<p>wow, neat!</p>\n',
  status: 'received'
 }
]

pinnedMessages

An array of the pinned messages in a particular channel:

[
 {
  id: 'example-id',
  text: '',
  html: '',
  type: 'regular',
   user: {
   id: 'example-id',
   role: 'user',
   created_at: '2021-03-09T18:26:47.113535Z',
   updated_at: '2021-03-30T19:59:48.086874Z',
   last_active: '2021-03-30T19:47:56.723441Z',
   banned: false,
   online: true
  },
  attachments: [],
  latest_reactions: [],
  own_reactions: [],
  reaction_counts: null,
  reaction_scores: null,
  reply_count: 0,
  cid: 'messaging:example-id',
  created_at: 2021-03-30T19:55:41.251Z,
  updated_at: 2021-03-30T19:59:19.845Z,
  shadowed: false,
  mentioned_users: [],
  silent: false,
  pinned: true,
  pinned_at: 2021-03-30T19:59:19.844Z,
  pinned_by: {
  id: 'Lan',
   role: 'user',
   created_at: '2021-03-09T18:26:47.113535Z',
   updated_at: '2021-03-30T19:59:48.086874Z',
   last_active: '2021-03-30T19:47:56.723441Z',
   banned: false,
   online: true
  },
  pin_expires: null,
  __html: '',
  status: 'received'
 }
]

watchers

An object filled with the users who are actively watching this channel. This is done via the `channel.watch()` method. Calling `client.queryChannels()` with an active web socket connection also defaults to watching the channels returned in the response.

Watching a Channel

{
 example-id: {
  id: 'example-id',
  role: 'user',
  created_at: '2021-03-09T18:26:47.113535Z',
  updated_at: '2021-03-30T21:09:01.407981Z',
  last_active: '2021-03-30T21:04:16.336586Z',
  banned: false,
  online: true
 }
}

members

An object containing the members of the channel.

unreadCount

The number of unread messages in a channel that pertains to the “active” user. Our concept of unread implies that it is unread to someone. Additionally, the “active” user needs to be a member of the channel.

membership

Depending on whether or not the “active“ user is a member of the channel, this object will either be empty (not a member) or contain the user object (a member of the channel).

last_message_at

A timestamp of when the last message was sent to this channel. If no messages have been sent, this will be null. Otherwise, it will be formatted like so: `2021-03-24T21:21:21.184Z`.