const callType = 'default';
const callId = 'test-call';
const call = client.call(callType, callId);
await call.getOrCreate();
// or create it with options:
await call.getOrCreate({
data: {
/* call creation options */
},
});
Joining & Creating Calls
This guide shows how to create, join, leave, and end calls and ring calls.
Call
Call
represents the main building block of our SDK. This object abstracts away the user actions, join flows and exposes the call state.
Create call
You can create a call by specifying its callType
and callId
:
The Call Type controls which features are enabled, and sets up permissions. You can reuse the same call multiple times. As an example, if you’re building a telemedicine app calls will be connected to an appointment. Using your own appointment id as the call id makes it easy to find the call later.
See all possible options at the Call creation options section.
Join call
const callType = 'default';
const callId = 'test-call';
const call = client.call(callType, callId);
await call.join();
Create and join a call
For convenience, you can create and join a call in a single operation. One of the flags you can provide there is create
.
Set this to true
if you want to enable creating new call. Set it to false
if you only want to join an existing call.
See all possible options at the Call creation options section.
await call.join({
create: true,
data: {
/* call creation options */
},
});
Leave call
To leave a call, you can use the leave
method:
await call.leave();
End call
Ending a call requires a special permission. This action terminates the call for everyone.
await call.endCall();
Only users with a special permission (OwnCapability.JOIN_ENDED_CALL
) can join an ended call.
Load call
Existing calls can be loaded through the following API:
const call = client.call(type, id);
await call.get(); // just load
await call.getOrCreate(); // create if not present and load it
These operations initialize the call.state
and create a subscription for call updates to our backend.
This means that this call
instance will receive real-time updates in case it is modified somewhere else.
Read more about call state here: Call & Participant State.
Update call
After creating a call, you can update some of its properties:
import { RecordSettingsRequestModeEnum } from '@stream-io/video-react-sdk';
await call.update({
custom: { color: 'green' },
settings_override: {
recording: {
mode: RecordSettingsRequestModeEnum.DISABLED,
},
},
});
Call creation options
The following options are supported when creating a call:
Option | Description | Default |
---|---|---|
members | A list of members to add to this call. You can specify the role and custom data on these members | - |
custom | Any custom data you want to store | - |
settings | You can overwrite certain call settings for this specific call. This overwrites the call type standard settings | - |
startsAt | When the call will start. Used for calls scheduled in the future, livestreams, audio rooms etc | - |
team | Restrict the access to this call to a specific team | - |
ring | If you want the call to ring for each member | false |
notify | If you want the call to notify each member by sending push notification | false |
Set call members
const call = client.call(type, id);
await call.getOrCreate({
data: {
members: [{ user_id: 'alice', role: 'admin' }, { user_id: 'bob' }],
},
});
Update call members
await call.updateCallMembers({
update_members: [{ user_id: 'charlie', role: 'admin' }],
remove_members: ['alice'],
});
Custom call data
await call.getOrCreate({
data: {
custom: { color: 'blue' },
},
});
Settings override
By default, the call
instances inherit the settings defined in the call type.
In some cases, you might want to override call settings on the instance itself:
// at creation time
await call.getOrCreate({
data: {
settings_override: {
audio: { mic_default_on: false },
video: { camera_default_on: false },
},
},
});
// or later
await call.update({
settings_override: {
video: { camera_default_on: true },
},
});
Backstage setup
The backstage feature makes it easy to build a use-case where you and your co-hosts can set up your camera before going live.
Only after you call call.goLive()
the regular users will be allowed to join the livestream.
However, you can also specify a join_ahead_time_seconds
,
which will allow regular users to join the livestream before the call is live, in the specified join time before the stream starts.
Here’s an example of how to do that:
await call.getOrCreate({
data: {
starts_at: new Date(Date.now() + 500 * 1000), // 500 seconds from now
settings_override: {
backstage: {
enabled: true,
join_ahead_time_seconds: 300,
},
},
},
});
In the code snippet above, we are creating a call that starts 500 seconds from now.
We are also enabling backstage mode, with a join_ahead_time_seconds
of 300 seconds.
That means that regular users will be able to join the call 200 seconds from now.