WebRTC to Phone 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.

callPhone(phoneNumber: string, phoneCallptions?: PhoneCallOptions): PhoneCall

If you previously used the callPhoneNumber method, start by migrating to the newly added callPhone method. As before, this method is used to establish calls between WebRTC and phone endpoints.

Arguments

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

Note that by switching to PhoneCallOptions, you will be able to configure the use of audio filters when making your phone calls.

Returns

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

Example

//Initiate a phone call in SDK 1.x
let call = infobipRTC.callPhoneNumber('41793026727', CallPhoneNumberOptions.builder().setFrom('33712345678').build());

//Initiate a phone call in SDK 2.0
let call = infobipRTC.callPhone('41793026727', PhoneCallOptions.builder().setFrom('33712345678').build());

PhoneCall

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

• options method now returns the PhoneCallOptions
• 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,
• audioFilter method that returns the audio filter being used during the phone call,
• setAudioFilter(audioFilter) method that configures the audio filter.

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.

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

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

ESTABLISHED event

The payload of the ESTABLISHED event has changed. 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 }

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.

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

let phoneCall = infobipRTC.callPhone('41793026727');

phoneCall.on(CallsApiEvent.RINGING, () => {
    console.log('Ringing...');
});
phoneCall.on(CallsApiEvent.EARLY_MEDIA, (event) => {
    console.log('Ringtone playing...');
    $('#callAudio').srcObject = event.stream;
});
phoneCall.on(CallsApiEvent.ESTABLISHED, (event) => {
    console.log('Call established...');
     $('#callAudio').srcObject = event.stream;
});
phoneCall.on(CallsApiEvent.HANGUP, (event) => {
    console.log(`Call finished. Status: ${event.errorCode.name}`);
});
phoneCall.on(CallsApiEvent.ERROR, (event) => {
    console.log(`An error has occurred. Error: ${event.errorCode.name}`);
});

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 PhoneCallOptions. 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.