---
id: events
sidebar_position: 25
title: Events
---

Understand Low Level Messaging Events

Events allow the client to stay up to date with changes to the chat. Examples are a new message, a user's image that updated, a reaction, or a member joining the channel. There are a 4 different type of events. These first 2 types of events you receive if you're connected to Stream, no further action is needed to receive these events:

Client events: You always receive these events.
Examples are `connection.recovered`, `health.check` and `connection.changed`
Notification events: Notification events notify you when something changed on a channel you are a member of even if you're not explicitly watching that channel.
One example is someone starting a new channel to message you while you are currently in the app.

User presence events: `queryUsers`, `queryChannels` and `channel.watch()` allow you to specify `presence=True`,
if you specify this option you'll opt in to receiving updates about the users on these channels.
You'll receive events when they go online/offline or their data is updated
Channel events: if you call `queryChannels` with `watch=true`, or you call `channel.watch()` you'll opt-in to receiving events for the given channels.
Examples are new messages, people joining the chat etc.

### Listening To Events

As soon as you call watch on a Channel or queryChannels you’ll start to listen to these events. You can hook into specific events:

```dart
channel.on("message.deleted").listen((Event event) {
  print("message ${event.message.id} was deleted");
});
```

You can also listen to all events at once:

```dart
channel.on().listen((Event event) {
  print("received a new event of type ${event.type}");
});
```

### Connection Events

The official SDKs make sure that a connection to Stream is kept alive at all times and that chat state
is recovered when the user's internet connection comes back online.
Your application can subscribe to changes to the connection using client events.

```dart
client.on('connection.changed', (e) => {
    if (e.online) {
        print('the connection is up!');
    } else {
        print('the connection is down!');
    }
});
```

### Stop Listening for Events

It is a good practice to unregister event handlers once they are not in use anymore. Doing so will save you from performance degradations coming from memory leaks or even from errors and exceptions (i.e. null pointer exceptions)

```dart
final subscription = channel.on().listen((Event event) {
  print("received a new event of type ${event.type}");
});

subscription.cancel();
```

### Custom Events

Custom events allow you to build more complex interactions within a channel or with a user.

#### To a channel

Users connected to a channel, either as a watcher or member, can send custom events and have them delivered to all users watching the channel.

```dart
// sends an event for the current user to all connect clients on the channel
await channel.sendEvent(
    Event(
      type: 'friendship_request',
      extraData: {
        'text': 'Hey there, long time no see!',
      },
    ),
);
```