Calls / JavaScript
Home
/
Calls
/
JavaScript

Make your first call

Sendbird Calls for JavaScript enables real-time voice and video calls for 1-to-1 calls or group calls among users within your Sendbird-integrated app. Our development kit can initialize, configure, and build voice and video calling functionality to your web apps.

Sendbird Calls supports both Direct call and Group call. Follow the guide below to make your 1-to-1 call or start a group call from scratch.


Requirements

The minimum requirements for Calls SDK for JavaScript are:

  • Node
  • npm or yarn
  • WebRTC API supported browsers

Get started

You can start making a 1-to-1 call with Direct call or create a room to start a group call with Group call by installing Sendbird Calls for JavaScript.

Step 1 Install the SDK

You can install Calls for JavaScript through either npm or yarn.

  1. Install sendbird-calls dependency to the package.json file in your project.
Light Color Skin
Copy
# npm
npm install sendbird-calls

#yarn
yarn add sendbird-calls

Import the Calls SDK in ES6 module as shown below:

Light Color Skin
Copy
import SendBirdCall from "sendbird-calls";

SendBirdCall.init(APP_ID)
...

Note: If you are using TypeScript, set --esModuleInterop option to true for default imports or use import * as SendBirdCall from "sendbird-calls".

Or add the following code in the header to install and initialize the Calls SDK.

Light Color Skin
Copy
<script type="text/javascript" src="SendBirdCall.min.js"></script>
<script type="text/javascript">
    SendBirdCall.init(APP_ID)
</script>

Step 2 Request to access media device

The Calls SDK requires access permissions. To allow the Calls SDK to access microphone and camera, call the SendBirdCall.useMedia() function. This will allow the user to retrieve a list of available media devices or to retrieve any actual media streams.

Note: If the SendBirdCall.useMedia() function is not called before making or receiving the first call using your JavaScript application in a browser, the browser might prompt the user to grant microphone and camera access permissions.

Step 3 Initialize with APP_ID

To integrate and run Sendbird Calls in your application, you need to initialize first. Initialize the SendBirdCall instance by using the APP_ID of your Sendbird application, which can be found on the Sendbird Dashboard after creating an application. If the instance is initialized with a different APP_ID, all existing call-related data in a client app will be cleared and the SendBirdCall instance will be initialized again with the new APP_ID.

Note: Each Sendbird application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web.

Light Color Skin
Copy
// Initialize SendBirdCall instance to use APIs in your app.
SendBirdCall.init(APP_ID);

Step 4 Authenticate a user

To make and receive a 1-to-1 call or start a group call, authenticate a user to Sendbird server by using their user ID through the authenticate() method. To receive calls, the SendBirdCall instance should be connected with Sendbird server. Connect socket by using the SendBirdCall.connectWebSocket() method after a user’s authentication has been completed.

Light Color Skin
Copy
// The USER_ID below should be unique to your Sendbird application.
const authOption = { userId: USER_ID, accessToken: ACCESS_TOKEN };

SendBirdCall.authenticate(authOption, (result, error) => {
    if (error) {
        // Handle authentication failure.
    } else {
        // The user has been successfully authenticated and is connected to Sendbird server.
        ...
    }
});

// Establishing websocket connection.
SendBirdCall.connectWebSocket()
    .then(/* Succeeded to connect */)
    .catch(/* Failed to connect */);

After authenticating a user, you can continue to either make a 1-to-1 call with Direct call or start a group call with Group call. Skip to Step 8 if you wish to start a group call.

Note: You can implement both the Chat and Calls SDKs to your app. Two SDKs can work on the same Sendbird application for them to share users. In this case, you can allow Calls to retrieve a list of users in the client app by using the Chat SDK’s method or Chat API.


Make 1-to-1 call

Step 5 Add an event handler

Sendbird Calls provides SendBirdCallListener event handler for events related to Direct call. It is used to manage device specific events such as incoming calls.

  1. Add SendBirdCallListener by using the SendBirdCall.addListener() method.
Light Color Skin
Copy
// The UNIQUE_HANDLER_ID below is a unique user-defined ID for a specific event handler.
SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
    onRinging: (call) => {
        ...
    }
});

Note: If a SendBirdCallListener event handler isn’t registered, a user can't receive an onRinging callback event. Thus, this handler should be added at the initialization of the app. Also, a SendBirdCallListener event handler is automatically removed when the app closes by default.

Step 6 Make a call

You are now ready to make your first 1-to-1 call. To make a call, provide the callee’s user ID into the SendBirdCall.dial() method. To choose initial call configuration such as audio or video capabilities, video settings, and mute settings, use the CallOption object.

After making a call, add the call-specific DirectCallListener event handler to the call object. It allows the callee's app to respond to events happening during the call through its callback methods.

Light Color Skin
Copy
const dialParams = {
    userId: CALLEE_ID,
    isVideoCall: true,
    callOption: {
        localMediaView: document.getElementById('local_video_element_id'),
        remoteMediaView: document.getElementById('remote_video_element_id'),
        audioEnabled: true,
        videoEnabled: true
    }
};


const call = SendBirdCall.dial(dialParams, (call, error) => {
    if (error) {
        // Dialing failed.
    }

    // Dialing succeeded.
});

call.onEstablished = (call) => {
    ...
};

call.onConnected = (call) => {
    ...
};

call.onEnded = (call) => {
    ...
};

call.onRemoteAudioSettingsChanged = (call) => {
    ...
};

call.onRemoteVideoSettingsChanged = (call) => {
    ...
};

Note: A media viewer includes a HTMLMediaElement such as <audio> and <video> to display media stream. The remoteMediaView is required for the remote media stream to be displayed. It is also recommended to set a media viewer's autoplay property to true.

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

Note: Media viewers can also be set using the call.setLocalMediaView() or call.setRemoteMediaView() method.

Light Color Skin
Copy
// Setting media viewers lazily.
call.setLocalMediaView(document.getElementById('local_video_element_id'));
call.setRemoteMediaView(document.getElementById('remote_video_element_id'));

Step 7 Receive a call

You can accept or decline an incoming call. To accept an incoming call, use the directCall.accept(). To decline the call, use the directCall.end() method. When you accept the call, a media session will automatically be established by the Calls SDK.

Before accepting the call, add the call-specific DirectCallListener event handler to the call object. It allows the callee's app to react to events happening during the call through its callback methods.

Light Color Skin
Copy
SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
    onRinging: (call) => {
        call.onEstablished = (call) => {
            ...
        };

        call.onConnected = (call) => {
            ...
        };

        call.onEnded = (call) => {
            ...
        };

        call.onRemoteAudioSettingsChanged = (call) => {
            ...
        };

        call.onRemoteVideoSettingsChanged = (call) => {
            ...
        };

        const acceptParams = {
            callOption: {
                localMediaView: document.getElementById('local_video_element_id'),
                remoteMediaView: document.getElementById('remote_video_element_id'),
                audioEnabled: true,
                videoEnabled: true
            }
        };

        call.accept(acceptParams);
    }
});

Note: If media viewer elements have been set by the call.setLocalMediaView() and call.setRemoteMediaView() methods, make sure that the same media viewers are set in the acceptParam’s callOption. If not, they will be overridden during executing the call.accept() method.

The callee’s app receives an incoming call through the connection with Sendbird server established by the SendBirdCall.connectWebSocket() method.


Start a group call

Step 8 Create a room

When creating your first room for a group call, you can choose either a room that supports up to 6 participants with video or a room that supports up to 25 participants with audio. When the room is created, a ROOM_ID is generated.

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.

Step 9 Enter a room

You can now enter a room and start your first group call. When you enter 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.