Skip to main content

Group call

Call SDK supports group calling through NCCallType.MULTI. This page explains the main group call flows, including how to start a group call and how to expand a 1-to-1 call into a group call.

tip

The group call flow in Call SDK for Web is similar to the 1-to-1 flow. This page focuses on the parts that differ. Build the full 1-to-1 call flow first, then add the group-call-specific steps described here.

Prerequisites​

  • Audio and video calling is enabled for your App Key.
  • You have initialized the Call SDK and obtained the NCCallEngine instance. In this document, ncCallEngine refers to that initialized object.

Start a group call​

tip

The startCall method accepts optional pushConfig and extra parameters. pushConfig carries mobile push settings through INCCallPushConfig, including pushTitle, pushContent, and platform-specific push attributes. extra carries custom data that is passed through to the callee.

To start a multi-party call directly, pass multiple remote user IDs to startCall and set the call type to NCCallType.MULTI. The media type can be audio or video. A multi-party video call supports up to 16 participants, and a multi-party audio call supports up to 32 participants. The method returns a Promise that includes a numeric code and, on success, a callId. Callees receive the incoming call through onCallReceived(session: NCCallSession) in INCCallEventsListener.

typescript
const { code, callId } = await ncCallEngine.startCall(['<userId1>', '<userId2>'], NCCallType.MULTI, NCCallMediaType.VIDEO);
caution

Billing starts as soon as the group call is created successfully.

Answer a group call​

tip

The callee must register INCCallEventsListener and implement onCallReceived(session: NCCallSession). Incoming call notifications are delivered through the user's IM connection to Nexconn.

After the callee receives the incoming call, the app can answer or reject it. Use getCallId() on NCCallSession to get the call ID. Use getCallType() to confirm that the call type is group.

  • To answer a ringing invitation, call acceptCall on the NCCallEngine instance.
  • To join or rejoin an ongoing multi-party call when you already have its callId, call joinCall.
  • To reject, call endCall on the NCCallEngine instance.

These APIs run asynchronously inside the SDK and return a Promise with a numeric code. A code of 0 means success.

Invite other users during a call​

You can invite additional users into a group call. Invited users can accept or reject the invitation.

caution

Call does not currently support canceling an invitation after it is sent.

Invite users​

tip

The inviteToCall method accepts optional pushConfig and extra parameters. pushConfig carries mobile push settings through INCCallPushConfig, including pushTitle, pushContent, and platform-specific push attributes. extra carries custom data that is passed through to the invited users.

The local user must already be in a group call or a 1-to-1 call. To invite other users, call inviteToCall and pass the target user IDs. The returned Promise includes the result and busyUsers, which lists invitees who are currently busy. Each item has userId and userState (see NCCallUserState).

typescript
/**
 * Invite users during a call.
 * Inviting another user during a 1-to-1 call changes the call type.
 * @param calleeIds User ID list for the invited users
 * @returns busyUsers Users who are currently busy. Each entry has `userId` and `userState` ({@link NCCallUserState}).
 */
async inviteToCall(calleeIds: string[], pushConfig?: INCCallPushConfig, extra?: string): Promise<{ code: number; busyUsers?: { userId: string; userState: NCCallUserState }[] }>

After the invitation succeeds, the invited users receive an incoming call notification through onCallReceived(session: NCCallSession) in INCCallEventsListener.

Get invitation details​

After an invitation is sent during a call, the invited user, the users who are still in the call, and even users who already left the group call receive onRemoteUserInvited in INCCallEventsListener. The callback carries the call ID, the inviter user ID, and the IDs of all invited users.

typescript
/**
 * Fired when remote users are invited to join a group call.
 * For example, if A and B are in a call and A invites C, B receives this callback.
 * @param inviteeUserList Invited user ID list
 * @param inviterUserId Inviter user ID
 * @param callId Call ID
 */
onRemoteUserInvited(inviteeUserList: string[], inviterUserId: string, callId: string): void

Accept or reject an invitation​

When an invited user accepts or rejects the invitation, the inviter receives the related state change. You can update your UI so the inviter can see whether invited users joined or declined.

  • To accept a ringing invitation, the invited user can call acceptCall.
  • To rejoin the ongoing group call later, the invited user can call joinCall with the callId.
  • To reject, the invited user can call endCall on the NCCallEngine instance.

These APIs run asynchronously inside the SDK and return a numeric code. A code of 0 means success.

After the invited user joins, both the inviter and the invitee can watch each other's media streams.

If the original call was 1-to-1, the call type changes to NCCallType.MULTI after the invited user joins.

Get unfinished group calls​

A user might reject a group call invitation or leave a group call. As long as the call itself has not ended, the user can rejoin later.

First, call getOngoingCallLogs to query the server for group calls that the local user previously joined or was invited to and that are still in progress.

typescript
/**
 * Get unfinished call logs from the server.
 * @returns records Ongoing call log list
 */
async getOngoingCallLogs(): Promise<{ code: number; records?: INCCallLog[] }>

This method returns a Promise that includes the result code and a list of INCCallLog objects. After you get the records, read callId from INCCallLog and pass it to joinCall to rejoin the ongoing group call.

Last updated on