Calls / JavaScript
Home
/
Calls
/
JavaScript

Direct call

This page explains key functions of direct call consisting of how to make, receive, handle, and end a call from your app.


Call object

Direct call in the Calls SDK refers to a 1-to-1 call. A connection for a direct call is established through the following steps:

  1. When a caller initiates the call, the dial event will be sent to the callee and invoke onRinging.
  2. When the callee accepts the call, WebRTC attempts to establish a media stream to connect the users. During another round of handshake between the caller and callee, information related to WebRTC will be transferred.
  3. After the handshake, a WebRTC connection is established between the caller and callee. Also, the media stream will start for the call.

For the caller, the dial() method will return a promise resolved as the call object. For the callee, the call object will be delivered through the onRinging() method as an argument to a parameter. And for both the caller and callee, the call object will be returned by the SendBirdCall.getCall(callId) method.


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

Note: Media viewers can be set using the directCall.setLocalMediaView() or directCall.setRemoteMediaView() method as well.

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

Receive a call

To receive an incoming call, a device-specific 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 event handler must be added to the call object. It enables the callee’s app to react to events during the call through its callback methods.

Light Color Skin
Copy
const acceptCall = (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);
}

SendBirdCall.addListener(UNIQUE_HANDLER_ID, {
    onRinging: (call) => {
        acceptCall(call)
    }
});

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

Incoming calls are received via the application's persistent internal server connection, which is established by the SendBirdCall.connectWebSocket(). In the event of accidental disconnection, the application will attempt to reconnect every 2 seconds.


Handle a current call

Audio

During a current call, both the caller and callee’s audio can be muted or unmuted by the directCall.muteMicrophone() or directCall.unmuteMicrophone() method. If one party changes audio settings, the other party receives an event callback through the directCall.onRemoteAudioSettingsChanged() listener.

Light Color Skin
Copy
// Mute my microphone.
call.muteMicrophone();
// Unmute my microphone.
call.unmuteMicrophone();

// Receive the event
call.onRemoteAudioSettingsChanged(call) {
    if (call.isRemoteAudioEnabled) {
        // The remote user has been unmuted.
        // Display an unmuted icon.
    } else {
        // The remote user has been muted.
        // Display and toggles a muted icon.
    }
};

Video

During a current call, both the caller and callee’s video can be enabled or disabled by the directCall.startVideo() or directCall.stopVideo() method. If one party changes audio settings, the other party receives an event callback through the directCall.onRemoteVideoSettingsChange() listener.

Light Color Skin
Copy
// Start my local video.
call.startVideo();
// Stop my local video.
call.stopVideo();

// Receive the event.
call.onRemoteVideoSettingsChanged(call) {
    if (call.isRemoteVideoEnabled) {
        // The remote user has started video.
    } else {
        // The remote user has stopped video.
    }
};

End a call

The directCall.end() method ends a current call of either the caller or callee’s side. If one party ends a current call, the other party receives an event callback through the directCall.onEnded() listener.

Light Color Skin
Copy
// End a call.
call.end();

// Receive the event.
call.onEnded = (call) => {
  // Release or destroy call-related views from here.
};

Manage custom items

With custom items, you can store additional information to a call in addition to default values in the DirectCall object. These key-value custom items are delivered as a Dictionary of String and String and can be updated during the call. Examples of items that could be included in the call are customer service, refund, or inquiry for better user experience.

Add

Custom items can be added to a call either by a caller or a callee. When dialing, the caller can add a Dictionary of String and String to a DialParams object by using the customItems property. The default value of a call's custom items is an empty Dictionary.

Light Color Skin
Copy
const customItemsToAdd = { key1: 'value1', key2: 'value2' };
const addedCustomItems = call.updateCustomItems(
  customItemsToAdd,
  (result, error) => {
    // Handle added custom items within a callback.
  },
);
addedCustomItems.then((result) => {
  // Handle added custom items using a returned promise.
});

Update and delete

During a call, custom items can be modified by directly updating or deleting custom items of a given call. You can use updateCustomItems(): promise.then() to update current custom items with new custom items. If keys for the new custom items don't exist, new custom items will be added to the existing list of items. Otherwise, existing items will be replaced with new custom items.

You can modify custom items without directly referring to the DirectCall object. The custom items of the call from the SendBirdCall can also be modified by calling the same set of methods with an additional callId parameter. If a call with the corresponding callId exists, the SendBirdCall will update the custom items of that call.

You can delete a specific custom item with its given key by using deleteCustomItems(): promise.then() or delete all custom items associated with the call by using deleteAllCustomItems(): promise.then(). Through a completion handler or a returned promise, you will receive the updated custom items, a list of keys of the modified custom items, and an error from Sendbird server.

Light Color Skin
Copy
const customItemsToModify = { key1: 'value3', key2: 'value4' };
const modifiedCustomItems = call.updateCustomItems(
  customItemsToModify,
  (result, error) => {
    // Handle updated custom items within a callback.
  },
);
modifiedCustomItems.then((result) => {
  // Handle updated custom items using a returned promise.
});

const customItemKeysToDelete = ['key1', 'key2'];
const deletedCustomItems = call.deleteCustomItems(
  customItemKeysToDelete,
  (result, error) => {
    // Handle deleted custom items within a callback.
  },
);
deletedCustomItems.then((result) => {
  // Handle deleted custom items using a returned promise.
});

const deleteCustomItems = call.deleteAllCustomItems((result, error) => {
  // Handle deleted custom items within a callback.
});
deletedCustomItems.then((result) => {
  // Handle deleted custom items using a returned promise.
});

Receive events

To receive events from Sendbird server when custom items are modified, you can implement onCustomItemsUpdated() and onCustomItemsDeleted() from the DirectCall. Events contain the DirectCall object of changed custom items and updatedKeys or deletedKeys. Custom items can always be modified, however these events will only be delivered if the call is ongoing. If the call ends, events are not delivered to the DirectCall. You can always access modified custom items even after the call ends with the Calls API or by using the directCall.customItems.

Light Color Skin
Copy
call.onCustomItemsUpdated = (call, updatedKeys) => {
    ...
};
call.onCustomItemsDeleted = (call, deletedKeys) => {
    ...
};

Configure media devices

The SendBirdCall object contains a collection of methods used to configure media devices: retrieve a list of devices, retrieve the current device, select a device, and update a list of devices.

Methods

NameDescription

useMedia(constraints)

Grants permission to access media devices.

getCurrentAudioInputDevice()

Returns the current audio input device.

getAvailableAudioInputDevices()

Returns a set of available audio input devices.

selectAudioInputDevice(mediaDeviceInfo)

Selects the audio input device.

getCurrentAudioOutputDevice()

Returns the current audio output device.

getAvailableAudioOutputDevices()

Returns a set of available audio input devices.

selectAudioOutputDevice(mediaDeviceInfo)

Select the audio output device.

getCurrentVideoInputDevice()

Returns the current video input device.

getAvailableVideoInputDevices()

Returns a set of available video devices.

selectVideoInputDevice(mediaDeviceInfo)

Selects the video input device.

updateMediaDevices(constraints)

Manually updates media devices.

The device specific-event handler also contains a collection of event listeners used to handle changes in media devices.

Event lists

Event listenerInvoked when

onAudioInputDeviceChanged

There are changes in the system’s audio input device or the available audio input devices.

onAudioOutputDeviceChanged

There are changes in the system’s audio output device or the available audio output devices.

onVideoInputDeviceChanged

There are changes in the system’s video input device or the available video input devices.

Before using the methods and event listeners listed above, ensure that the SendBirdCall.useMedia(constraints) has been executed. Failing to do this will result in these methods causing unexpected behaviors or failed outcomes.

Light Color Skin
Copy
const mediaAccess = SendBirdCall.useMedia({audio: true, video: true});

// This code demonstrates for audio input devices. The same can also be done for audio output and video input devices.
const availableDevices = SendBirdCall.getAvilableAudioInputDevices();
const currentDevice = SendBirdCall.getCurrentAudioInputDevice();
// Populate option elements in select element.
populateSelectOption(availableDevices);
// Select option which matches current device.
selectOption(currentDevice);

SendBirdCall.addListener('my-listener', {
    onAudioInputDeviceChanged: (currentDevice, availableDevices) => {
        // Populate option elements in a select element.
        populateSelectOption(availableDevices);
        // Select option which matches current device.
        selectOption(currentDevice);
    }
});

...

SendBirdCall.removeListener('my-listener');

// on settings view closed.
mediaAccess.dispose();

Make sure that the retrieved mediaAccess's dispose() method always gets called from the SendBirdCall.useMedia() method to prevent the unintended use of camera or microphone.

Note: In Chrome or Firefox, the SendBirdCall.updateMediaDevices() doesn’t need to be called if the media device event listener is used to update the view or device list. However, in Safari, those event listeners might not need to be called after a media device has been changed. In such cases, calling the SendBirdCall.updateMediaDevices() manually may be required.


Add event handlers

There are two types of event handlers that the Calls SDK provides: a device-specific listener and a call-specific listener.

Device-specific listener

Add a device-specific 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.

Note: If a device-specific 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 client app. Also, the device-specific event handler is automatically removed when the app closes by default.

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

Methods

NameInvoked when

onRinging()

An incoming call is notified on the callee’s device.

onAudioInputDeviceChanged()

There are changes in the system’s audio input device or the available local audio input devices.

onAudioOutputDeviceChanged()

There are changes in the system’s audio output device or the available local audio output devices.

onVideoInputDeviceChanged()

There are changes in the system’s video input device or the available local video input devices.

Call-specific listener

Before accepting the call, the call-specific 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
// call is 'DirectCall' object
call.onEstablished = (call) => {
  ...
};

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

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

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

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

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

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

call.onCustomItemsUpdated = (call, updatedKeys) => {
  ...
};

call.onCustomItemsDeleted = (call, deletedKeys) => {
  ...
};

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

Methods

NameInvoked when

onEstablished()

The callee has accepted the call by using the directCall.accept() method, but the media devices of caller and callee are not yet connected.

onConnected()

Media devices (for example, microphone and speakers) between the caller and callee are connected and can start the call.

onReconnecting()

The call is attempting to reconnect to Sendbird server after losing connection.

onReconnected()

The call successfully reconnects to Sendbird server.

onEnded()

One of the parties ends a call by using the directCall.end() method and a call is ended due to other reasons such as decline or connection lost.

onRemoteAudioSettingsChanged()

The remote user changes their audio settings.

onRemoteVideoSettingsChanged()

The remote user changes their video settings.

leted.

onRemoteRecordingStatusChanged()

The remote user changes their recording status.

onCustomItemsUpdated()

The custom items of the call are updated.

onCustomItemsDeleted()

The custom items of the call are deleted.


Retrieve call information

One party’s information can be retrieved using the directCall.localUser property while the other party’s information using the directCall.remoteUser property.


Retrieve call history

A user’s call history can be retrieved using the next() method of a DirectCallLogListQuery instance which returns a list of call objects.

Light Color Skin
Copy
/*
interface DirectCallLogListQueryParams {
    myRole: string
    endResults: string[],
    limit: number
}
*/

const params = {
  myRole: 'dc_caller',
  endResults: ['DECLINED', 'COMPLETED'],
  limit: 100,
};

const listQuery = SendBirdCall.createDirectCallLogListQuery(params);

listQuery.next((directCallLog) => {
  if (listQuery.hasNext && !listQuery.isLoading) {
    // The listQuery.next() can be called once more to fetch more call logs.
  }
});

The call log can be immediately obtained after a call has ended. However, in the caller’s case, only the local log will be retrieved unless the sync has been made with the server. If you want to check whether a call log is synchronized with the server or not, use the callLog.isFromServer() method. To retrieve call history from the server instead of the local log, use the DirectCallLogListQuery instance.

Light Color Skin
Copy
call.onEnded = (call) => {
    ...

    let callLog = call.callLog
    // Appropriately add this callLog object to the callLog list.
    ...

}

Capture video views

During a video call, the caller and callee can capture the images of their streaming video by using the captureLocalVideoView() method.

Local video view

Promise
Callback
Light Color Skin
Copy
try {
  const resultImage = await call.captureLocalVideoView();
  // Implement your custom code for a successfully-captured image.
} catch (e) {
  // Handle error.
}
Light Color Skin
Copy
call.captureLocalVideoView(function (resultImage, error) {
  if (error) {
    // Handle error.
  } else {
    // Implement your custom code for a successfully-captured image.
  }
});

Parameters

NameTypeDescription

function (optional)

callback

A callback function to receive the result of video streaming capture images. If a Promise is used instead of the callback function, the returned resultImage and error must be processed within a try-catch block.

Properties of return value

NameTypeDescription

resultImage

nested object

A JSON object which contains the information of the captured result image.

resultImage.width

number

The width of the captured result image.

resultImage.height

number

The height of the captured result image.

resultImage.data

string

The data URL containing a representation of the captured result image, which is returned by the toDataURL() method.

Remote video view

Promise
Callback
Light Color Skin
Copy
try {
  const resultImage = await call.captureRemoteVideoView();
  // Implement code for handling a successfully-captured image.
} catch (e) {
  // Handle error.
}
Light Color Skin
Copy
call.captureRemoteVideoView(function (resultImage, error) {
  if (error) {
    // Handle error.
  } else {
    // Implement code for handling a successfully-captured image.
  }
});

Parameters

NameTypeDescription

function (optional)

callback

A callback function to receive the result of video streaming capture images. If a Promise is used instead of the callback function, the returned resultImage and error must be processed within a try-catch block.

Properties of return value

NameTypeDescription

resultImage

nested object

A JSON object which contains the information of the captured result image.

resultImage.width

number

The width of the captured result image.

resultImage.height

number

The height of the captured result image.

resultImage.data

string

The data URL containing a representation of the captured result image, which is returned by the toDataURL() method.

Note: For errors that may occur when capturing video views, see the Error codes page.


Record audio and video

When making a direct call with Sendbird Calls, audio and video recordings for both local and remote users are available. The recorded file will be saved on the user’s local file storage and users can transfer or process the file.

Only one ongoing recording session is allowed, which means that the current recording session must be stopped in order to start another recording. However, several sessions can be recorded throughout the call, thus multiple recording files created from one call.

The SendBirdCall currently supports five recording types:

Recording types

TypeDescription

remoteAudioAndVideo

An option to record the video and audio of the remote user.

remoteAudioOnly

An option to record the audio of the remote user.

localRemoteAudios

An option to record both audios of the local and remote users.

localAudioRemoteAudioAndVideo

An option to record both audios of the local and remote users, and the video of the remote user.

localAudioAndVideoRemoteAudio

An option to record both audios of the local and remote users, and the video of the local user.

Note: Sendbird Calls SDK uses the MediaRecorder from the MediaStream Recording API when recording a direct call. To check if your browser supports the recording feature, refer to MediaRecorder. If the browser doesn't support the MediaRecorder, directCall.startRecording() will throw error through returned Promise.

Start recording a call

Start recording a call using the directCall.startRecording() method. You can customize the type and the name of the recording as well as the output path where a recorded file will be saved with a RecordingOptions object.

If the name of a file isn't specified for the fileName parameter in the method, the recorded file’s name will follow the default pattern of {recording_type}_{call_id}_{timestamp}.

Light Color Skin
Copy
import { DirectCallRecordOption, RecordingType } from "sendbird-calls";

...

let options = new DirectCallRecordOption({recordingType: RecordingType.REMOTE_AUDIO_AND_VIDEO, callId: callId, fileName: FILE_NAME})
// Record remote user’s audio and video and download it under the name 'FILE_NAME.mp4'.

const recordingId = call.startRecording(options);
if(recordingId){
    // Recording start succeed.
} else {
    // Recording start failed.
}

A recordingId is returned from the completion handler of the directCall.startRecording() method when the recording has been successfully started. Make sure to save the recordingId to stop the recording session. If the recordingId is invalid or missing when the directCall.stopRecording() method is called, you can’t stop the recording session when needed.

Note: The SendBirdCall doesn’t check for file read and write permissions or any other permissions related to the media. Make sure that the application can write at the specified destination folder before starting a recording session.

Stop recording a call

Stop recording a call using the directCall.stopRecording() method with the recordingId received from the directCall.startRecording() method. If the recording session isn’t stopped by the time the call has ended, the recording session automatically ends as well.

Light Color Skin
Copy
call.stopRecording((recordingId: recordingId));
// Stops a recording session with the given ‘recordingId’.
// If the provided ‘recordingId’ is invalid, return false.

After the recording is finished, the SendBirdCallRecordingListener.onRecordingSucceeded() method will be called.

Receive events

To receive events about the completion of the recordings, add a device-specific SendBirdCallRecordingListener by using the SendBirdCall.addRecordingListener() event listener method. Once the event listener is added, your app can handle the following two events as shown below:

Light Color Skin
Copy
SendBirdCall.addRecordingListener((identifier: string), {
  onRecordingSucceeded: (
    callId: string,
    recordingId: string,
    options: DirectCallRecordOption,
    fileName: string,
  ) => {
    // Recording was successfully saved to ‘fileName’.
  },
  onRecordingFailed: (callId: string, recordingId: string, error: Error) => {
    // Recording wasn’t saved due to an ‘error’.
  },
});

You can remove the device-specific SendBirdCallRecordingListener as shown below:

Light Color Skin
Copy
SendBirdCall.removeRecordingListener((id: string));
// Remove a recording event listener with the specified identifier.

SendBirdCall.removeAllRecordingListeners();
// Remove all recording event listeners from the application.

Note: The SendBirdCallRecordingListener.didFailToSaveRecording() event listener method won’t be called if errors occur at the start of recording sessions after calling the directCall.startRecording() method.

Recorded files

Each browser has a different policy and supported codec for recording which means the format of a recorded file is MP4 for safari and WEBM for Chrome and Firefox. If the recorded file is created in Chrome or Firefox, it can't be played with the native media player of your operating system. The recorded file can be played with Browser, VLC media player, or a media player that supports VP8 and Opus codecs. For Safari versions 14 and later, recordings are created in the MP4 file format encoded with H.264 and AAC so that recorded files can be played with the native media player of your operating system. When the recording is complete, the recorded file will automatically be saved to the browser's default download folder.

Recorded videos will have a fixed frame size of 1280x720 pixels. Video recording uses around 20 MB of data per minute, but this may vary depending on the type of the recording content.

The SendBirdCall doesn’t handle anything related to managing recorded files. If there isn’t enough storage to save the recorded file, SendBirdCallRecordingListener.onRecordingFailed will be called.

Recording notifications

During a voice or video call, users can notify each other if the call is being recorded.

If a user starts or stops local recording on their device, the other user will be able to receive an event callback through the DirectCall.onRemoteRecordingStatusChanged method. Users can also check the recording status of the other user with DirectCall.remoteRecordingStatus.

Light Color Skin
Copy
// Start local recording.
const recordId = call.startRecording(options);
// Stop local recording.
call.stopRecording(recordId);

// Receive the event.
call.onRemoteRecordingStatusChanged = (call) => {
    if (call.remoteRecordingStatus === RecordingStatus.RECORDING) {
        console.log("The remote user has started recording");
    } else if (call.remoteRecordingStatus === RecordingStatus.NONE){
        console.log("The remote user has stopped recording");
    }
}

Screen share

During a video call, both the caller and callee can share their screens with each other using the browser’s screen share feature.

Start screen share

Light Color Skin
Copy
try {
  await call.startScreenShare();
  call.onScreenShareStopped = () => {
    // add your process for screen share stop.
  };
} catch (e) {
  // add your process for start screen share fail.
}

When the startScreenShare method is called, the list of contents on your screen will be displayed. Then you can select a content or a screen to share with both the local user's localVideoView and the remote user’s remoteVideoView. Currently, displaying the local camera view and the local screen share view together is not supported.

Note: The screen share function is not provided in mobile browsers.

The following types of content are supported for screen share on each browser when using the Calls SDK for JavaScript.

ChromeFirefoxSafari

Monitor

O

* Screens of all connected monitors

O

O

* Only the screen of the default monitor

App

O

O

X

Tab

O

X

X

Note: If an app that is being shared is minimized, the screen share view will show as black. If the app closes, the screen share view will end.

Stop screen share

You can stop sharing your screen and return to the video view as shown below:

Light Color Skin
Copy
call.stopScreenShare();