JavaScript
Calls Quick Start

Quick Start

Sendbird Calls enables real-time voice and video calls between users within your Sendbird-integrated app. The Calls SDK for JavaScript is used to initialize, configure, and build voice and video calling functionality into your JavaScript application. This quick start shows a brief overview of the Calls SDK’s structure and features, then goes through the preliminary steps of implementing the Calls SDK into your own project.


Try the sample app

Our sample app demonstrates an implementation of the core features of Sendbird Calls SDK. Download the app from our GitHub repository to get an idea of what you can do with the actual SDK and to get started building your own project.

Download Sample App

Note: The fastest way to see our Calls SDK in action is to build your app on top of our sample app. Make sure to change the application ID with your own when initializing the Calls SDK. Go to Create a Sendbird application from your dashboard section to learn more.


How Sendbird Calls SDK works with your app

Sendbird Calls can only be used by your Sendbird application users. When a user logs in, the user can send and receive direct calls with other users on the same Sendbird application.

Direct call in the Calls SDK refers to a one-to-one call. To make a direct call, the caller first initializes a call request to the callee. The callee will receive incoming call notifications to all logged in devices. When the callee accepts the call on any of these devices, a media connection is established between the caller and callee which marks the start of a direct call.

Call-related events are delivered through call event handlers. The event handlers include onRinging(), onConnected(), onEnded(), and other event callbacks. By using event callbacks of the handlers, your app can implement appropriate responses and actions accordingly such as updating call status on the UI level.


Requirements

The requirements for Calls SDK for JavaScript are:

  • Node
  • npm (or yarn)
  • Modern browser, supporting WebRTC APIs.

Install and configure the Calls SDK

If you are ready to integrate Calls to your app, follow the step-by-step instructions below.

Step 1: Create a Sendbird application from your dashboard

A Sendbird application comprises everything required in a Calls service including users, message, and channels. To create an application:

  1. Go to the Sendbird Dashboard and enter your email and password, and create a new account. You can also sign up with a Google account.
  2. When prompted by the setup wizard, enter your organization information to manage Sendbird applications.
  3. Lastly, when your dashboard home appears after completing setup, click Create App at the top-right corner.

Only one Sendbird application can be integrated per app for your service regardless of the platform. All users within your Sendbird application can communicate with each other across all platforms. This means that your iOS, Android, and web client app users can all make and receive calls with one another without any further setup. It should be noted that all data are limited to the scope of a single application, and users in different Sendbird applications can't make and receive calls to each other.

Note: For application administrators, the Sendbird Dashboard provides call logs to keep track of all calls made on the application.

Step 2: Download and install the Calls SDK using npm or yarn

Installing the Calls SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. You can install the Calls SDK with npm or yarn by entering the command below on the command line.

Note: For npm, you can automatically download our Calls SDK with just an npm install command by adding sendbird-calls dependency to the package.json file of your project. For yarn, a similar method can be applied to download the Calls SDK.

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 3: Acquire media device permissions

The Calls SDK requires access permissions to microphone and camera to communicate with Sendbird server. To grant these permissions, 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: When a user makes or receives a call for the first time by your JavaScript application running in a browser, the browser might prompt the user to grant microphone and camera access permissions.


Make your first call

The Calls SDK adds call features to your client app with a few simple steps. To make your first call, do the following steps:

Step 1: Initialize the Calls SDK in your app

First, the SendBirdCall instance must be initialized when a client app is launched. Initialization is done by using the APP_ID of your Sendbird application in the dashboard. 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.

Light Color Skin
Copy
SendBirdCall.init(APP_ID);

Step 2: Authenticate a user

Note: You can implement both the Chat and Calls SDKs to your client 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.

To make and receive calls, 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
// Authentication
const authOption = { userId: USER_ID, accessToken: ACCESS_TOKEN };

SendBirdCall.authenticate(authOption, (res, error) => {
    if (error) {
        // Authentication failed
    } else {
        // Authentication succeeded
    }
});

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

Step 3: Add an event handler

Add a device-specific SendBirdCallListener event handler using the SendBirdCall.addListener() method. Once the event handler is added, responding to device events such as incoming calls can be managed as shown below:

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 recommended to add this handler at the initialization of the app. Also, a SendBirdCallListener event handler is automatically removed when the app closes by default.

Step 4: Make a call

Initiate a call by providing the callee’s user id into the SendBirdCall.dial() method. Use the CallOption object to choose initial call configuration, such as audio or video capabilities, video settings, and mute settings.

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 is 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 5: Receive a call

To receive an incoming call, a SendBirdCallListener event handler should already be registered in the callee’s client app. Accept or decline the call using the directCall.accept() or the directCall.end() method. If the call is accepted, a media session will automatically be established by the Calls SDK.

Before accepting the call, the call-specific DirectCallListener event handler must be added to the call object. It enables 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 client app receives an incoming call through the connection with Sendbird server established by the SendBirdCall.connectWebSocket() method.