Calls SDKs JavaScript v1
Calls SDKs JavaScript
Calls SDKs
JavaScript
Version 1

Group call

Copy link

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

Copy link

You can choose to create a room that supports up to 6 participants with video or a room that supports up to 100 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.

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

List of properties

Copy link
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 100 participants.


Retrieve a list of rooms

Copy link

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

List of filters

Copy link
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:

/*
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.

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 allow the user to select a room they want to enter.

const enterParams = {
  audioEnabled: true,
  videoEnabled: true,
};

try {
  await rooms[index].enter(enterParams);
  // User has entered the room
} catch (e) {
  // Error has occurred
  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.


Enter a room

Copy link

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.

SendBirdCall.fetchRoomById(ROOM_ID)
    .then(room => {
        // room with the identifier ROOM_ID is fetched from the Sendbird server.
    })
    .catch(e => {
        // Handle error
    });

const room = SendBirdCall.getCachedRoomById(ROOM_ID);
// 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.

const enterParams = {
    videoEnabled: true,
    audioEnabled: true
}

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

Kick out siblings of the user

Copy link

In a room, a single user can enter the same room multiple times as a different participant. However, if you want to prevent the user from entering the room simultaneously using different mobile devices and web browsers, you can kick out siblings of the user by calling room.enter(). It will result the user to be the unique participant remaining in the room.

try {
  await room.enter({ audioEnabled: true, videoEnabled: true, kickSiblings: true });
  // User has successfully entered room and any other participants of the same user will be kicked out.
} catch (e) {
  // failed to enter.
}

Large room for audio only

Copy link

For the LARGE_ROOM_FOR_AUDIO_ONLY room type, call the enter() method to enter and set the HTMLAudioElement for the room to stream audio.

const roomParams = {
    roomType: SendBirdCall.RoomType.LARGE_ROOM_FOR_AUDIO_ONLY
};

const enterParams = {
  videoEnabled: true,
  audioEnabled: true
}

SendBirdCall.createRoom(roomParams)
    .then(room => {
        room.enter(enterParams)
            .then(() => {
                // Set HTMLAudioElement to set audio for a large room.
                room.setAudioForLargeRoom(AUDIO_VIEW);
            })
            .catch(e => {
                // Handle error.
            })
    }).catch(e => {
        // Failed to create a room.
    });

List of methods

Copy link
MethodDescription

setAudioForLargeRoom()

Sets audio for a large room.

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


Exit a room

Copy link

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

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

Delete a room

Copy link

If you would like to delete a room, you can call the delete() method. When this method is called successfully, the room will be permanently deleted, all participants in the room will be exited automatically, and the media connection will be stopped. Any participants in the room can delete the room.

try {
  await room.delete();
} catch (e) {
  // handle error.
}

Handle events in a room

Copy link

A user can receive events of a room that they are currently participating. Users will be notified when other participants enter or leave the room, change their media settings or when the room is deleted.

Add event listener

Copy link

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

// 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

Copy link

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

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

Copy link

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.

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

Receive events on local participant's connection status

Copy link

A local participant may lose their media stream in the room if their network connection is unstable. The localParticipantDisconnected event listener will be sent to the local participant when they are disconnected. Once the media stream is reconnected, the localParticipantReconnected event listener will be sent.

You can use the received events to alert the local participants to switch to a more stable network or take other appropriate actions to stay connected to the room. Implement the code below to receive events on local participant's connection status.

room.on('localParticipantReconnected', (localParticipant) => {
  // Called when local participant's network is interrupted and the local participant is disconnected from the server.
});
room.on('localParticipantDisconnected', (localParticipant) => {
  // Called when local participant's network connection is restored and the local participant is reconnected to the server.
})

Receive events on deleted room

Copy link

To delete a room through Calls Platform API, see Delete a room in the Calls API documentation. When a room is deleted, participants in the room will receive the following event.

room.on('deleted', () => {
  // Called when the room has been deleted.
});

Remove event listener

Copy link

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

// 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();

Invite users

Copy link

You can let users into a room by sharing the room ID or by sending invitation to certain users as an event. You can also cancel your invitations and invitees can either accept or decline them.

Invite a user

Copy link

First, you need to be in the room to which you would like to invite other users. Follow the steps in Create a room and Enter the room to invite other users.

You can send an invitation to users to join the room by providing the invitee's user ID and the room ID. When the invitation is sent successfully, the invited user will receive an event on their device notifying them that you've invited them to join a room.

/*
class RoomInvitation {
  room: Room;
  inviter: User;
  invitee: User;

  accept(): Promise<void>;
  decline(): Promise<void>;
  cancel(): Promise<void>;
}
*/

try {
  const invitation = await room.sendInvitation(INVITEE_ID);
} catch (e) {
  // handle an error.
}

Show the invitation to the invitee

Copy link

When a user is invited, they will receive an event that shows information about who invited them to which room. When the invitation event is passed to the Calls SDK, the onInvitationReceived event listener will be called automatically and you can add UI to show the invitee to accept or decline the invitation.

SendbirdCall.addListener({
  onInvitationReceived: (invitation) => {
    // show UI to accept or decline the invitation.
  }
});

Cancel an invitation

Copy link

If you would like to cancel an invitation that you sent, follow the code below. When you cancel the invitation, the invited user won't be able to enter the room when they open the notification.

try {
  const invitation = await room.sendInvitation(INVITEE_ID);
  // ...
  await invitation.cancel();
} catch (e) {
  // handle error;
}

Accept or decline the invitation

Copy link

When the invited user accepts or declines the invitation, the user who invited them will be notified. You can add UI updates to let the inviter know whether the user they invited accepted or declined the invitation.

SendbirdCall.addListener({
  onInvitationReceived: async (invitation) => {
    // Accept an invitation.
    try {
      await invitation.accept();
    } catch (e) {
      // handle error.
    }

    // Decline an invitation.
    try {
      await invitation.decline();
    } catch (e) {
      // handle error.
    }
  }
});

Call room.enter() to let the invitee enter the room once the invitee accepts the invitation. After the invitee enters and gets connected to the room, the inviter and invitee will be able to view each other's media stream.

List of event listeners

Copy link
Event DelegateDescription

invitationAccepted

Invoked when the invitee accepts the invitation to enter the room.

invitationDeclined

Invoked when the invitee declines the invitation to enter the room.


Manage custom items

Copy link

With custom items for group calls, you can store additional information as key-value pairs to a room in the Room object. Custom key-value items are saved as an object and can be updated or deleted as long as the room status is OPEN. Information related to customer service, refund, or inquiry can be added as custom items for better user experience.

When a room is created, users can add custom items in RoomParams as an object. By default, the customItems is an empty object.

const customItems = { 'key1': 'value1', 'key2': 'value2' };
const params = {
  roomType: SendBirdCall.RoomType.SMALL_ROOM_FOR_VIDEO,
  customItems: customItems
};
SendBirdCall.createRoom(params)
  .then(room => {
    // A room has been created successfully.
  })
  .catch(err => {
    // Failed to create a room.
  });

Update and delete

Copy link

Custom items can be updated or deleted as long as the room status is OPEN. If a new custom item has the same key as the existing custom item, the new item will update the value of the existing item. A new item with a new key will be added to the list of custom items. You can update existing custom items by calling the room.updateCustomItems(customItems).

You can delete custom items by calling the room.deleteCustomItems(customItemKeys) with the list of keys that you want to delete from the existing custom items.

const customItems = { 'key1': 'value3' };
room.updateCustomItems(customItems)
  .then(res => {
    const { customItems, affectedKeys } = res;
    // Custom items with matching keys in affectedKeys have been updated in the customItems.
  })
  .catch(err => {});

const keys = [ 'key1' ];
room.deleteCustomItems(customItemKeys)
  .then(res => {
    const { customItems, affectedKeys } = res;
    // Custom items with matching keys in affectedKeys have been deleted from customItems.
  })
  .catch(err => {});

Receive events

Copy link

A participant in a room can receive events from Sendbird server when other participants update or delete custom items in the room. Implement room.on('customItemsUpdated', handler) and room.on('customItemsDeleted', handler) to receive events from other participants. Each event contains the list of keys of the updated or deleted custom items in the affectedKeys.

Custom items can be modified and the events are delivered to the event handlers only when the room's status is OPEN and there are participants in the room. To check the custom items that had been changed for ended or ongoing calls in a room, you can use the Calls API or the room.fetchCustomItems().

room.on('customItemsUpdated', (customItems, affectedKeys) => {
  // Custom items with affectedKeys have been updated in the target room.
});
room.on('customItemsDeleted', (customItems, affectedKeys) => {
  // Custom items with affectedKeys have been deleted in the target room.
});

Interact within a room

Copy link

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:

// 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

Copy link

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

Copy link

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:

(async () => {
    const enterParams = {
      videoEnabled: true,
      audioEnabled: true
    };

    await room.enter(enterParams);
    const localMediaView = document.getElementById('local_video_element_id');
    // Set local media view.
    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);
        document.body.appendChild(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.

<video id="remote_video_element_id" autoplay>

Show default image for user

Copy link

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.


Reconnect to media stream

Copy link

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.

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.


Cloud recording

Copy link

Cloud recording is a feature that allows you to record participants' audio and video in rooms and download the recorded files from Sendbird Dashboard. When the feature is turned on in a Sendbird application, audio of LARGE_ROOM_FOR_AUDIO_ONLY and audio and video of SMALL_ROOM_FOR_VIDEO are recorded.

To use the cloud recording feature, contact our support team. You can go to Settings > Calls > General on the dashboard to see if the feature is available for your Sendbird application.

Recording starts in Open rooms when there are more than two participants in the room, and ends when there are no participants. Recorded files will be numbered in the file name and listed in the order of creation.

Download the recorded file

Copy link

Once the file has been uploaded successfully, you can download it from the dashboard. To download the file, click the room of the recording you would like to download on Group calls. You can download the file immediately or later by using the link, which stays valid for 24 hours and can be reissued.

File spec and retention

Copy link

Audio recordings from LARGE_ROOM_FOR_AUDIO_ONLY are processed to .aac files and audio and video recordings from SMALL_ROOM_FOR_VIDEO are processed to .mp4 files in default resolution of 1280 x 720. Each file can be downloaded for two weeks from the date the recorded file's upload has completed.