WebRTC to WebRTC calls migration guide

Note

Start your migration process by updating infobip-rtc dependency to version 2.1.0 or newer. As before, we publish it as an NPM package and as a standalone JS file hosted on a CDN.

callWebrtc(identity: string, options?: WebrtcCallOptions): WebrtcCall

If you previously used the call method, start by migrating to the newly added callWebrtc method. As before, this method is used to establish calls between two WebRTC endpoints.

Arguments

While the first argument, identity, is unchanged, the type of the second argument has changed. WebrtcCallOptions are introduced and should be used instead of the previously used CallOptions.

Note that by switching to WebrtcCallOptions, you will be able to configure the use of audio and video filters when making your WebRTC calls.

Returns

The return type has changed to WebrtcCall and should be used instead of the previously available OutgoingCall. Consult the documentation of the WebrtcCall to get familiar with the newly added methods that can be used with it.

Example

//Initiate a call with video in SDK 1.x
let call = infobipRTC.call('Alice', CallOptions.builder().setVideo(true).build());

//Initiate a call with video in SDK 2.0
let call = infobipRTC.callWebrtc('Alice', WebrtcCallOptions.builder().setVideo(true).build());

WebrtcCall

Deprecated Call and newly added WebrtcCall support a similar set of methods, but there are some notable changes:

• options method now returns the WebrtcCallOptions
• if you previously configured RecordingOptions on your individual calls, please note that this is not supported yet when migrating to RTC SDK 2.0 (for more details, consult Recording section of the migration guide),
• source and destination methods now return the Endpoint.

Among newly available methods you will find:

• counterpart method used to simplify accessing the remote endpoint,
• pauseIncomingVideo and resumeIncomingVideo methods as well as,
• audioFilter and videoFilter methods that return the audio/video filter being used during the WebRTC call,
• setAudioFilter(audioFilter) and setVideoFilter(videoFilter) methods that configure audio and video filters.

on(event: CallsApiEvent, eventHandler: CallsEventHandlers): void

There are several breaking changes concerning the configuration of the event handler.

Types of eventName and eventHandler have changed. Get familiar with the new types to understand emitted events and how to handle them:

• eventName: CallsApiEvent
• eventHandler: CallsEventHandlers - Function that will be called when a specified event occurs, with exactly one parameter being passed to the function containing event information.

RINGING event

There are no changes to the payload of the RINGING event.

EARLY_MEDIA event

The payload of the EARLY_MEDIA event has changed. MediaStream object passed in the EARLY_MEDIA event now specifically corresponds to the media to be played before establishing a call.

//Payload of `early-media` event in SDK 1.x
event = { localStream: streamObject, remoteStream: streamObject }

//Payload of CallsApiEvent.EARLY_MEDIA event in SDK 2.0
event = { stream: MediaStream }

ESTABLISHED event

The payload of the ESTABLISHED event has changed. While audio and video media was passed before, MediaStream object passed in the ESTABLISHED event now corresponds to the common audio media stream only.

//Payload of `established` event in SDK 1.x
event = { localStream: streamObject, remoteStream: streamObject }

//Payload of CallsApiEvent.ESTABLISHED event in SDK 2.0
event = { stream: MediaStream }

Local and remote video events

When either side called cameraVideo(cameraVideo) and/or screenShare(screenShare) methods, updated event was emitted.

Instead of it, a set of new events should be handled:

• CAMERA_VIDEO_ADDED

• CAMERA_VIDEO_UPDATED

• CAMERA_VIDEO_REMOVED

• SCREEN_SHARE_ADDED

• SCREEN_SHARE_REMOVED

• REMOTE_CAMERA_VIDEO_ADDED

• REMOTE_CAMERA_VIDEO_REMOVED

• REMOTE_CAMERA_VIDEO_ADDED

• REMOTE_CAMERA_VIDEO_REMOVED

Consult CallsApiEvent documentation to get familiar with payloads of the newly added call events.

HANGUP event

The payload of the HANGUP event has been expanded with the TotalMediaStats.

//Payload of CallsApiEvent.HANGUP event in SDK 2.0
event = { errorCode: ErrorCode, totalMediaStats: TotalMediaStats }

ERROR event

There are no changes to the payload of the ERROR event.

When using SDK 2.0, you may encounter Calls API error codes and WebRTC error codes.

Note that ERROR event is now emitted only when a call encounters an error which does not hang up the call, unlike before.

Example

Let's assume you have an audio HTML element with the id callAudio and video HTML elements with the ids cameraVideo, remoteCameraVideo, screenShareVideo, and remoteScreenShareVideo.

let infobipRTC = createInfobipRtc('2e29c3a0-730a-4526-93ce-cda44556dab5', {debug: true});
infobipRTC.connect();

let webrtcCall = infobipRTC.callWebrtc('alice');

webrtcCall.on(CallsApiEvent.RINGING, () => {
    console.log('Ringing...');
});
webrtcCall.on(CallsApiEvent.EARLY_MEDIA, (event) => {
    console.log('Ringtone playing...');
    $('#callAudio').srcObject = event.stream;
});
webrtcCall.on(CallsApiEvent.ESTABLISHED, (event) => {
    console.log('Call established...');
     $('#callAudio').srcObject = event.stream;
});
webrtcCall.on(CallsApiEvent.HANGUP, (event) => {
    console.log(`Call finished. Status: ${event.errorCode.name}`);
});
webrtcCall.on(CallsApiEvent.ERROR, (event) => {
    console.log(`An error has occurred. Error: ${event.errorCode.name}`);
});
webrtcCall.on(CallsApiEvent.CAMERA_VIDEO_ADDED, (event) => {
    $('#cameraVideo').srcObject = event.stream;
});
webrtcCall.on(CallsApiEvent.REMOTE_CAMERA_VIDEO_ADDED, (event) => {
    $('#remoteCameraVideo').srcObject = event.stream;
});
webrtcCall.on(CallsApiEvent.SCREEN_SHARE_ADDED, (event) => {
    $('#screenShareVideo').srcObject = event.stream;
});
webrtcCall.on(CallsApiEvent.REMOTE_SCREEN_SHARE_ADDED, (event) => {
    $('#remoteScreenShareVideo').srcObject = event.stream;
});
webrtcCall.on(CallsApiEvent.REMOTE_MUTED, (event) => {
    console.log(`Remote user is muted`);
});
webrtcCall.on(CallsApiEvent.REMOTE_UNMUTED, (event) => _ => {
    console.log(`Remote user is unmuted`);
});

Receiving a WebRTC call

When migrating to SDK 2.0, in order to receive a WebRTC call, you will need to register the incoming-webrtc-call event handler of InfobipRTC client, replacing the previously available incoming-call event.

//Receiving a WebRTC call in SDK 1.x
infobipRTC.on('incoming-call', function (incomingCallEvent) {
    const incomingCall = incomingCallEvent.incomingCall();
    console.log('Received incoming call from: ' + incomingCall.source().identity);

    incomingCall.on('established', function () {
    });
    incomingCall.on('hangup', function () {
    });

    incomingCall.accept(); // or incomingCall.decline();
});

//Receiving a WebRTC call in SDK 2.0
infobipRTC.on('incoming-webrtc-call', function (incomingWebrtcCallEvent) {
    const incomingCall = incomingWebrtcCallEvent.incomingCall();
    console.log('Received incoming call from: ' + incomingCall.source().identifier);

    incomingCall.on(CallsApiEvent.ESTABLISHED, function () {
    });
    
    incomingCall.on(CallsApiEvent.HANGUP, function () {
    });

    incomingCall.accept(); // or incomingCall.decline();
});

Note that incomingCall method now returns IncomingWebrtcCall, instead of the previously used Call.

Recording

If you already have Recording add-on enabled on account level, you can set the recording preferences under Channels & Numbers > WebRTC > Recording or control it via ALWAYS, ON_DEMAND and DISABLED recording flag when generating the token for the session.

When ON_DEMAND flag is used, RecordingOptions should be passed via WebrtcCallOptions. Note that RecordingOptions are different from the previously available RecordingOptions (1.x).

To determine the expected behaviour when combining any of these three elements, consult the Outcome of the recording table.

To access recording files, use the available API or Portal, passing call identifier as the callId parameter.