Events

In most cases, you can simply use the reactive state store to be notified about state changes. However, for some advanced use cases, you might need to subscribe to the underlying WebSocket events.

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:

Name	Description
`connection.ok`	Fired when the authentication process finished successfully
`connection.error`	Fired when the WS connections fails

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:

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

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

let client: StreamVideoClient;

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

Join a call:

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

let client: StreamVideoClient;

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

Watch a call:

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

let client: StreamVideoClient;

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

The list of call events:

Name	Description	Delivered to
`call.accepted`	A user accepts a notification to join a call	All call members
`call.blocked_user`	A user is blocked from the call	Call watchers
`call.created`	The call was created	All call members
`call.ended`	The call was ended	All call members
`call.hls_broadcasting_failed`	The call failed to broadcast	Call watchers
`call.hls_broadcasting_started`	The call started to broadcast	Call watchers
`call.hls_broadcasting_stopped`	The call stopped broadcasting	Call watchers
`call.live_started`	The call left backstage mode	Call watchers
`call.member_added`	One or more members were added to the call	All call members
`call.member_removed`	One or more members were removed from the call	All call members
`call.member_updated`	One or more members were updated	All call members
`call.member_updated_permission`	One or more members’ role was updated	All call members
`call.notification`	A user is calling all call members	All call members
`call.permission_request`	A user is requesting permissions	Call watchers
`call.permissions_updated`	A member’s permissions were updated	Call watchers
`call.reaction_new`	A new reaction was sent	Call watchers
`call.recording_failed`	A recording failed	Call watchers
`call.recording_ready`	A recording is ready	Call watchers
`call.recording_started`	A recording has been started	Call watchers
`call.recording_stopped`	The recording was stopped	Call watchers
`call.rejected`	A user declined to join the call	All call members
`call.ring`	A user is calling all call members	All call members
`call.session_ended`	A call session ended (all participants have left the call)	Call watchers
`call.session_participant_joined`	A participant joined to the call sessions	Call watchers
`call.session_participant_left`	A participant left a call session	Call watchers
`call.session_started`	A call session started (the first participant joined the call)	Call watchers
`call.unblocked_user`	A user is unblocked	Call watchers
`call.updated`	The call was updated	Call watchers
`custom`	Custom event	All call members

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-client";

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-client";

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-client";

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-client";

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);
  }
});

Chat Integration

Recording