Events

Use the reactive state store for most cases. For advanced use cases, subscribe to WebSocket events directly.

Best Practices

• Use state hooks when possible - events are for advanced cases.
• Always unsubscribe when components unmount to prevent memory leaks.
• Watch calls with watch: true or call.get() to receive call events.
• Use the on method's return value for cleanup.

List of events

Client events

Client events are always delivered if a user is connected to the client using the connectUser method.

The list of client events:

Call events

These events are related to a specific call. Some of these events are only delivered to clients that are watching the specific call. There are 3 ways to watch a call:

1. Call the queryCalls method with the watch option set to true:

import { StreamVideoClient } from "@stream-io/video-react-sdk";

let client: StreamVideoClient;

await client.queryCalls({
  // ...
  watch: true,
});

2. Join a call:

import { StreamVideoClient } from "@stream-io/video-react-sdk";

let client: StreamVideoClient;

await client.call("default", "test-call").join();

3. Watch a call:

import { StreamVideoClient } from "@stream-io/video-react-sdk";

let client: StreamVideoClient;

await client.call("default", "test-call").getOrCreate();
// or
await client.call("default", "test-call").get();

The list of call events:

Listening to client and call events

You can use the on method of the StreamVideoClient instance to subscribe to client and call WebSocket events.

The on method takes the type of the event you want to subscribe to or the 'all' keyword indicating that you want to be notified about all events.

The event handler will receive an object with type StreamVideoEvent that has a type attribute that tells the type of the event. The available event types are described by the EventTypes type.

The on method returns a method that can be called to unsubscribe from WebSocket events.

Subscribing to all events:

import {
  StreamVideoClient,
  StreamVideoEvent,
} from "@stream-io/video-react-sdk";

let client: StreamVideoClient;

// Subscribe to all events
const unsubscribe = client.on("all", (event: StreamVideoEvent) => {
  console.log(event);
});

// Unsubscribe
unsubscribe();

Subscribing to call.created events:

import {
  StreamVideoClient,
  StreamVideoEvent,
} from "@stream-io/video-react-sdk";

let client: StreamVideoClient;

// Subscribe to all events
const unsubscribe = client.on("call.created", (event: StreamVideoEvent) => {
  if (event.type === "call.created") {
    console.log(`Call created: ${event.call_cid}`);
  }
});

// Unsubscribe
unsubscribe();

Listening to call events

You can use the on method of the call instance to subscribe to WebSocket events belonging to a specific call.

The call.on method takes the type of the event you want to subscribe to. The event handler will receive an object with type StreamCallEvent that has a type attribute that tells the type of the event. The available event types are described by the CallEventTypes type. The call.on method returns a method that can be called to unsubscribe from WebSocket events.

Example: Subscribing to call.reaction_new event:

import { Call, StreamVideoEvent } from "@stream-io/video-react-sdk";

let call: Call;

// Subscribe to new reactions event
const unsubscribe = call.on("call.reaction_new", (event: StreamVideoEvent) => {
  if (event.type === "call.reaction_new") {
    console.log(`New reaction: ${event.reaction}`);
  }
});

// Unsubscribe
unsubscribe();

Custom events

You can send custom events between the call participants using the sendCustomEvent method of the call instance. Note that the payload for these events is limited to 5KB in size.

import {
  Call,
  CustomVideoEvent,
  StreamVideoEvent,
} from "@stream-io/video-react-sdk";

let call: Call;

// sending a custom event
await call.sendCustomEvent({
  type: "my-event-type",
  payload: {
    foo: "bar",
  },
});

// receiving a custom event
call.on("custom", (event: StreamVideoEvent) => {
  const customEvent = event as CustomVideoEvent;
  const payload = customEvent.custom;
  if (payload.type === "my-event-type") {
    console.log(payload.foo);
  }
});