---
id: watching_channels
sidebar_position: 8
title: Watching Channels
---

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

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.

```dart
final state = await channel.watch();
```

### Watchers vs Members

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

* <b>Members</b>: 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.
* <b>Watchers</b>: 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

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

```dart
// first let’s create a filter to make messaging channels that include a specific user
final filter = Filter.in_('members', [user_id]);

// we can also define a sort order of most recent messages first
final sort = [SortOption("last_message_at", direction: SortOption.DESC)];

// finally, we can query for those channels, automatically watching them for the
// currently connected user
final channels = await client.queryChannels(
  filter: filter,
  sort: sort,
  options: {
    "watch": true,
    "state": true,
  },
);
```

### Stop Watching a Channel

To stop receiving channel events:

```dart
// we can also stop watching a channel
final stopWatching = await channel.stopWatching();
```

### Watcher Count

To get the watcher count of a channel:

```dart
// create a new channel of type “livestream” with name “watch-this-channel”
final channel = client.channel("livestream", id: "watch-this-channel");

// retrieve our channels
channel.query();

// each channel object has a state collection with a watcher_count property
 return channel.state.watcherCount;
```

### Paginating Channel Watchers with channel.query

```dart
// create a new channel of type “livestream” with name “watch-this-channel”
final channel = client.channel("livestream", id: "watch-this-channel");

// now query the newly created channel for watchers, retrieving the first 5
final result = await channel.query(
    watchersPagination: PaginationParams(
      limit: 5,
      offset: 0,
    ),
  );

 return result.watchers;
```

### Listening to Changes in Watchers

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

```dart
final channel = client.channel("livestream", id: "watch-this-channel");

await channel.watch();

// handle watch started event
channel
      .on("user.watching.start")
      .listen((event) => print('${event.user.id} started watching'));

// handle watch stopped event
channel
      .on("user.watching.stop")
      .listen((event) => print('${event.user.id} stopped watching'));
```