Watching a Channel

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

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

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.

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

To stop receiving channel events:

To get the watcher count of a channel:

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

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