Home
/
Calls
/
JavaScript

Make your first call

The Calls SDK adds call features to your 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
// Initialize SendBirdCall instance to use APIs in your app.
SendBirdCall.init(APP_ID);

Step 2: Authenticate a user

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

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.


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.