Watching a Channel

LAST EDIT Mar 18 2024

The call to channel.watch does a few different things in one API call:

  • It creates the channel if it doesn't exist yet (if this user has the right permissions to create a channel)

  • It queries the channel state and returns members, watchers and messages

  • It watches the channel state and tells the server that you want to receive events when anything in this channel changes

To start watching a channel

Copied!

The examples below show how to watch a channel. Note that you need to be connected as a user before you can watch a channel.

Response Schema

Name

Type

Description

config

object

The configuration for the channel type.

channel

object

The Channel object.

online

integer

Number of online members.

watchers

object

Users that are watching this channel. Represented as a mapping from the user id to the user object.

members

object

Channel members. Represented as a mapping from the user id to the user object.

read

object

Read messages grouped by user id. Represented as a mapping from the user id to the message object.

Watching a channel only works if you have connected as a user to the chat API

Watchers vs Members

Copied!

The concepts of watchers vs members can require a bit of clarification:

  • members: a permanent association between a user and a channel. If the user is online and not watching the channel they will receive a notification event, if they are offline they will receive a push notification.

  • watchers: the list of watchers is temporary. It's anyone who is currently watching the channel.

Being able to send messages, and otherwise engage with a channel as a non-member requires certain permissions. For example, we have pre-configured permissions on our livestream channel type to allow non-members to interact, but in the messaging channel type, only members of the channel can interact.

Watching Multiple Channels

Copied!

The default queryChannels API returns channels and starts watching them. There is no need to also use channel.watch on the channels returned from queryChannels

Stop Watching a Channel

Copied!

To stop receiving channel events:

Watcher Count

Copied!

To get the watcher count of a channel:

Paginating Channel Watchers with channel.query

Copied!

The maximum limit that can be used is 300, and the maximum offset that can be used is 10 000.

Listening to Changes in Watchers

Copied!

A user already watching the channel can listen to users starting and stopping watching the channel with the realtime events: