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:

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:

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