Events

All changes to the chat state are exposed as events. When a new message is sent, a reaction is added, or any other action occurs, the client receives an event in real-time. You can also send custom events, enabling you to build your own pub/sub functionality on top of a channel.

Listening for Events

The code sample below shows how to listen to events:

channel.on("message.new", (event) => {
  console.log("received a new message", event.message.text);
});

channel.on("message.deleted", (event) => {
  console.log("message was deleted", event.message.id);
});

You can also listen to all events at once:

channel.on((event) => {
  console.log("event", event);
  console.log("channel.state", channel.state);
});

Event Types

There are different type of events

• User level/connection level events. You always receive these events.
• Notification events you receive if you are a member of the channel
• Channel level events you receive if you are watching the channel
• User presence events are sent when you specify presence=true
• Custom events. Your own pub/sub on top of the chat channel.

The example below shows how to watch a channel and enable user presence events. You can also watch channels and enable user presence when using query channels. See these links for more details on user presence, watching and query channels.

// Watch a channel with presence enabled to receive user presence events
const channel = client.channel("messaging", "my-conversation-123", {
  members: ["john", "jack"],
});

const state = await channel.watch({ presence: true });

// Listen for user presence changes
channel.on("user.presence.changed", (event) => {
  console.log(
    `${event.user.name} is now ${event.user.online ? "online" : "offline"}`,
  );
});

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.

client.on("connection.changed", (e) => {
  if (e.online) {
    console.log("the connection is up!");
  } else {
    console.log("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)

// remove the handler from all client events
// const myClientEventListener = client.on('connection.changed', myClientEventHandler)
myClientEventListener.unsubscribe();

// remove the handler from all events on a channel
// const myChannelEventListener = channel.on('connection.changed', myChannelEventHandler)
myChannelEventListener.unsubscribe();

Custom Events

Custom events allow you to build your own pub/sub functionality on top of a channel. You can send any event with custom data and have it delivered to all users watching the channel.

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.

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

// custom events can also be sent server-side, in that case a user must be included in the event payload
await channel.sendEvent({
  type: "friendship_request",
  text: "Hey there, long time no see!",
  user: user,
});

Permissions

Like every client-side API request, sending a custom event includes a permission check. By default users that can read messages on a channel can also send custom events. Check the Auth & Permission section to find out more about how permissions can be customized for your application.

To a user

This allows you to send custom events to a connected user. The event is delivered to all connected clients for that user.

It is only available with server-side authentication. A copy of the event is sent via web-hooks if it is enabled.

await client.sendUserCustomEvent(targetUserID, {
  type: "friendship_request",
  text: "Tommaso wants to be your friend",
});

If the user doesn't exist, a 404 Not Found error is returned.

The type of the event shouldn't contain any . character otherwise a 400 Bad Request error is returned. This is a character used for built-in events, see the Built-in Events section below for more details.

Event Object

Built-in Events

The table below shows an overview of all built-in events: