Calls / JavaScript
Home
/
Calls
/
JavaScript

Group call

This page explains the key functions of group call consisting of how to create a room and how a user can participate in a group call by entering and exiting a room from your app.


Create a room

You can choose to create a room that supports up to 6 participants with video or a room that supports up to 25 participants with audio. When a user creates a room in your app, the room’s status becomes OPEN and a ROOM_ID is generated.

You can create a room through the Calls API as shown below using the createRoom() method.

Light Color Skin
Copy
const roomParams = {
    roomType: SendBirdCall.RoomType.SMALL_ROOM_FOR_VIDEO
};

SendBirdCall.createRoom(roomParams)
    .then(room => {
        // Room has been created successfully.
    }).catch(e => {
        // Failed to create a room.
    });

If you want to create a room with the LARGE_ROOM_FOR_AUDIO_ONLY room type, you need to set the HTMLAudioElement for the room.

Light Color Skin
Copy
const roomParams = {
    roomType: SendBirdCall.RoomType.LARGE_ROOM_FOR_AUDIO_ONLY
};

SendBirdCall.createRoom(roomParams)
    .then(room => {
        // Set HTMLAudioElement to set audio for a large room.
        room.setAudioForLargeRoom(AUDIO_VIEW);
        // Room has been created successfully.
    }).catch(e => {
        // Failed to create a room.
    });

List of properties

Property nameDescription

type

Type: RoomType
Specifies the type of the room. Valid values are limited to the following:
- SMALL_ROOM_FOR_VIDEO: type of a room that supports audio and video, can have up to 6 participants.
- LARGE_ROOM_FOR_AUDIO_ONLY: type of a room that only supports audio, can have up to 25 participants.

List of methods

MethodDescription

setAudioForLargeRoom()

Sets audio when creating a large room.


Enter a room

A user can search a room with a specific room ID to participate in a group call at any time. When a user enters a room, a participant is created with a unique participant ID to represent the user in the room.

To enter a room, you must first acquire the room instance from Sendbird server with the room ID. To fetch the most up-to-date room instance from Sendbird server, use the SendBirdCall.fetchRoomById() method. Also, you can use the SendBirdCall.getCachedRoomById() method that returns the most recently cached room instance from Sendbird Calls SDK.

Light Color Skin
Copy
SendBirdCall.fetchRoomById(ROOM_ID)
    .then(room => {
        // `room` with the identifier `ROOM_ID` is fetched from Sendbird Server.
    })
    .catch(e => {
        // Handle error
    });

// Returns the most recently cached ‘room’ with the identifier `ROOM_ID` from the SDK.
// If there is no such room with the given identifier, `undefined` is returned.

Note: A user can enter the room using multiple devices or browser tabs. Entering from each device or browser tab will create a new participant.

Once the room is retrieved, call the enter() method to enter the room.

Light Color Skin
Copy
const enterParams = {
    videoEnabled: true,
    audioEnabled: true
}

room.enter(enterParams)
    .then(() => {
        // User has successfully entered `room`.
    })
    .catch(e => {
        // Handle error.
    });

Note: Share the room ID with other users for them to enter the room from the client app.


Exit a room

To leave a room, call Room.exit(). On the room event listeners of the remaining participants, the remoteParticipantExited event listener will be called.

Light Color Skin
Copy
try {
    room.exit() // Participant has exited the room successfully.
} catch (error) {
    // Error is thrown because the participant has not entered the room.
}

Retrieve a list of rooms

You can retrieve a list of the rooms by using RoomListQuery and the following table shows all supported filters for RoomListQuery to search for specific rooms you want to retrieve.

List of filters

NameFilters...

roomIds

Query results to include rooms that match the specified room IDs.

type

Query results to include rooms with the specified room type.

state

Query results to include room with the specified room state.

createdAt

Query results to include rooms that were created between the specified range of time.

currentParticipantCount

Query results to include rooms with the specified range of numbers for current participants.

createdByUserIds

Query results to include rooms that were created by specified user IDs.

You can specify the above filters as shown below:

Light Color Skin
Copy
/*
export interface RoomListQueryParams {
  type?: RoomType | 'all'
  limit?: number;
  state?: RoomState;
  currentParticipantCount?: [number | undefined, number | undefined];
  createdByUserIds?: string[]
  roomIds?: string[]
  createdAt?: [number | undefined, number | undefined];
}
*/

let params = {
  type: SendBirdCall.RoomType.SMALL_ROOM_FOR_VIDEO,
  limit: 50,
  state: SendBirdCall.RoomState.OPEN,
  currentParticipantCount: [1, ], // You can leave out the bound of a range.
  createdByUserIds: [USER_ID1],
  createdAt: [, Date.now()], // You can leave out the bound of a range.
};

To retrieve a list of rooms, call the RoomListQuery.next() method.

Light Color Skin
Copy
const query = SendBirdCall.createRoomListQuery(params);

try {
  const rooms = await query.next();
} catch (e) {
  // Error has occurred.
  return;
}

When a list of rooms is retrieved, you can show the list to a user and directly let them enter the room.

Light Color Skin
Copy
const enterParams = {
  audioEnabled: true,
  videoEnabled: true,
};

try {
  await rooms[index].enter(enterParams);
  // User has entered the room
} catch (e) {
  // Error has occured
  return;
}

Note: The room data returned from the query is not updated unless the user has entered the room. To update the details about a room, call the SendBirdCall.fetchRoom(by:completionHandler:) method.


Interact within a room

Participant’s actions, such as turning on or off their microphone or camera, in a room are handled by the participant objects.

To control the media of the local user, you can use the following methods from the Room.localParticipant object:

Light Color Skin
Copy
// Mutes the local participant's microphone.
room.localParticipant.muteMicrophone()

// Unmutes the local participant's microphone.
room.localParticipant.unmuteMicrophone()

// Stops the local participant's video.
room.localParticipant.stopVideo()

// Starts the local participant's video.
room.localParticipant.startVideo()

Display video view

When there is a participant in the room, a media stream is established between a participant and Sendbird server to support group calls. You can configure the user interface for participants in a room by using the properties in Participant.

Receive media stream

The following is the process of how participants can send and receive media streams in a room:

Step 1: To send a media stream, a participant who would like to send its media stream has to be connected to Sendbird server.

Step 2: To receive a media stream, a participant who would like to receive a media stream from another participant has to be connected to the media server. Once connected, the remoteParticipantStreamStarted event listener will be invoked which notifies that the receiving media stream has started.

Step 3: Add a view to show the received media stream. You can receive a video stream from a participant by using the setMediaView() method as shown below:

Light Color Skin
Copy
(async () => {
    await room.enter();
    const localMediaView = document.getElementById('local_video_element_id');
    room.localParticipant.setMediaView(localMediaView);
    // Called when a remote participant is connected to the media stream and starts sending the media stream.
    room.on('remoteParticipantStreamStarted', (remoteParticipant) => {
        // Create a new HTMLMediaElement to set remote participant's media stream.
        const remoteMediaview = document.createElement('video');
        // It is recommended to set a media view element's 'autoplay' property to true.
        remoteMediaView.autoplay = true;
        remoteParticipant.setMediaView(remoteMediaView);
    });
})();

Note: A media view element is a HTMLMediaElement such as <audio> and <video> to display media stream. The participant.setMediaView() is required for the media stream to be displayed. It is also recommended to set a media view element’s autoplay property to true.

Light Color Skin
Copy
<video id="remote_video_element_id" autoplay>

Show default image for user

If a participant is not connected to the call or has turned off their video, you can set a default image to show on the screen for that participant. Otherwise, it will be shown as black to other participants. To check whether a participant has turned on their video or is connected to the room for a video call, refer to the VideoEnabled and the state properties of a Participant object.

It is recommended to show an image such as the user’s profile image as the default image when the remoteParticipantEntered event listener is invoked.

When the remoteParticipantStreamStarted event listener is invoked, create a new HTMLMediaView and set it to the participant by using the participant.setMediaView() method and remove the default image.


Handle events in a room

A user can receive events such as other participants entering or leaving the room or changing their media settings only about a room that the user currently participates in.

Add event listener

Add an event listener for the user to receive events that occur in a room that the user joins as a participant.

Light Color Skin
Copy
// `addEventListener` can be used to add a listener about a room.
room.addEventListener(EventType, (...args) => {

});

// `on` is an alias for `addEventListener` to add a listener about a room.
room.on(EventType, (...args) => {

});

Receive events on enter and exit

When a participant joins or leaves the room, other participants in the room will receive the following events.

Light Color Skin
Copy
room.on('remoteParticipantEntered', (participant) => {
    // Called when a remote participant has entered the room.
});
room.on('remoteParticipantExited', (participant) => {
    // Called when a remote participant has exited the room.
});

Receive events on media setting

A local participant can change the media settings such as muting their microphone or turning off their camera by using muteMicrophone() or stopVideo(). Other participants will receive event listeners that notify them of the corresponding media setting changes.

Light Color Skin
Copy
room.on('remoteAudioSettingsChanged', (participant) => {
    // Called when audio settings of a remote participant have been changed.
});
room.on('remoteVideosettingsChanged', (participant) => {
    // Called when video settings of a remote participant have been changed.
});

Remove event listener

To stop receiving events about a room, remove the registered listeners as shown below:

Light Color Skin
Copy
// Removes a registered event listener about a room.
const unsubscribe = room.on(EVENT_TYPE, EVENT_LISTENER);
unsubscribe();

// `removeEventListener` can be used to remove a listener about a room.
room.removeEventListener(EVENT_TYPE, EVENT_LISTENER);

// `off` is an alias for `removeEventListener` to remove a listener about a room.
room.off(EVENT_TYPE, EVENT_LISTENER);

// Removes all registered event listeners about a room.
room.removeAllEventListeners();

Reconnect to media stream

When a participant loses media stream in a room due to connection issues, Sendbird Calls SDK automatically tries to reconnect the participant’s media streaming in the room. If the Calls SDK fails to reconnect for about 40 seconds, an error will be returned.

Light Color Skin
Copy
room.on('error', (error, participant) => {
    // Called when error has occurred.
    // Clear resources and views for group calls.
});

Note: See the Error codes page for more information.