PSTN Call

JS SDK supports a normal audio (PSTN) call between its users. Make sure that the web application based on JS SDK is logged in and connected to RTC server before initiating a call. If RTC connection got disconnected due to inactivity, the user should again request for connection to make a successful call.

Different APIs are used to create and join an audio session. It also supports features like hold, unhold, mute, call swap and conferencing. Session related API requests have their respective callbacks to notify the user about the status of the request. The callbacks specific to audio session and generic callbacks for any session type (audio, video or chat) are here.

Create Local Audio Stream

The IrisRtcStream class manages the audio and video streams that can be created using 555 stream APIs. The createStream method is called to create a stream with streamConfig which has audio constraints stream type like audio. This class provides callbacks for stream and errors encountered.

var irisRtcStream = new IrisRtcStream();

var constraints = {
    video : false,
    audio : { mandatory: {}, optional: [] }
}

var streamConfig = {
    "streamType": "audio",
    "resolution": "hd",
    "constraints": constraints
}

irisRtcStream.createStream(streamConfig);

// Stream can also be received with a callback
irisRtcStream.onLocalStream = (stream) => {
    // Audio stream is received
}

irisRtcStream.onStreamError = (errorCode, errorMessage) => {
    // Throws error if failed to create stream
}

// API to stop media stream once call is ended.
irisRtcStream.stopMediaStream(mediaStream);

Initiate an Outgoing Call

Once the RTC connection is made, dial a valid PSTN number to make an outgoing call. An 555 session is then created with the local stream and other necessary values using IrisRtcSession class.

createSessionWithTN API is invoked to create a pstn session, which involves creating the room using the target and source telephone phone number. This API takes three params, userConfig a json object with attributes explained below, IrisRtcConnection object from rtc connetion and IrisRtcStream object from local stream

var irisRtcSession = new IrisRtcSession();

var userConfig = {
    type : "pstn",
    domain : "<app domain>",
    sessionType : "create",
    useBridge : true,
    useAnonymousLogin : false,
    irisToken : "<JWT Token>",
    fromTN: "<Telephone number in E.164 format>",
    toTN: "<Telephone number in E.164 format>"
}

irisRtcSession.createSessionWithTN(userConfig, irisRtcConn, irisRtcStream);

Parameters passed to createSessionWithTN API are :

Parameters
userConfig	JSON object for setting session configuration parameters
irisRtcConn	IrisRtcConnection object after rtc is connetion is successfully established
irisRtcStream	IrisRtcStream object after local stream is successfully created

userConfig JSON contains below parameters :

Parameters
type	Call type must be pstn
irisToken	555 JWT token
routingId	Routing id of the caller
useAnonymousLogin	`false` for PSTN Calls
useBridge	`true` for PSTN Call
toTN	Telephone number of caller in E.164 fromat (Mandatory for pstn calls)
fromTN	elephone number of callee in E.164 fromat (Mandatory for pstn calls)
traceId	Unique time based UUID to identify call uniquely
sessionType	Session type 'create'
publicId	Public id of the caller

Accept or Reject an Incoming Call

When user receives an incoming PSTN call alert, the user can choose to:

Accept call
Reject call

Accept Call

Notification for the incoming calls are received via callback onNotification of Connection, Use this info to join call.

A local stream should be created and passed along with other parameters received in the incoming call notification to joinSession API to join a PSTN call session.

var irisRtcSession = new IrisRtcSession();

var userConfig = {
    type : "pstn",
    domain : "<app domain>",
    sessionType : "join",
    useBridge : true,
    useAnonymousLogin : false,
    irisToken : "<JWT Token>",
    routingId : "<Routing Id>"
}

irisRtcSession.joinSession(userConfig, irisRtcConn, irisRtcStream, notificationPayload);

Parameters
userConfig	JSON object for setting session configuration parameters
irisRtcStream	IrisRtcStream object
irisRtcConn	IrisRtcConnection object
notificationPayload	Notification payload received by `onNotification` callback from `irisRtcConn`

Reject Call

User can reject an incoming call notification. JS SDK provides rejectSession() API in IrisRtcConnection for this feature. The notification information received from onNotification callback after rtc connetion should be passed to rejectSession API as it is without any modifications.

var irisRtcConn =  new IrisRtcConnection() 

// Callback to Receive Notifications 
irisRtcConn.onNotification = (notificationInfo) => {}

// API to reject incoming call
irisRtcConn.rejectSession(notificationInfo);

Parameters
notificationInfo	Pass notificationInfo to `rejectSession` API as it is

End an Active Call

On end call, all data and objects associated with that particular call must be cleared for efficiency and to avoid memory leak . While closing a PSTN call session following things must be kept in mind.

Close 555 Rtc session
By invoking endSession() API in IrisRtcSession, 555 session will get closed by releasing all objects associated with it.
Close stream
The close operation of stream class is synchronous and can take time while closing the stream. Closing the stream during a session can cause an error in video or audio sessions. Hence it is advisable to use stopMediaStream() API once the session is closed.

var irisRtcSession = new IrisRtcSession();
irisRtcSession.endSession(roomId);


var irisRtcStream = new IrisRtcStream();
irisRtcStream.stopMediaStream(stream);

On-call Features

Features offered by JS SDK for PSTN call are:

Hold call
Unhold call
Mute local audio
Unmute local audio
Swap between two calls
Merge two calls

Hold Call

Either caller or callee can hold a call. When the call is on hold neither of the users will be able to send or receive audio streams. JS SDK provides the pstnHold() API in IrisRtcSession class to hold an active call.

var irisRtcSession = new IrisRtcSession();
irisRtcSession.pstnHold(roomId, participantJid);

Unhold Call

The user who kept the call on hold can unhold the call and the both the users will be able to send & receive audio streams. JS SDK provides pstnUnHold() API in IrisRtcSession class to unhold a call which is already on hold.

var irisRtcSession = new IrisRtcSession();
irisRtcSession.pstnUnHold(roomId, participantJid);

Blind Call Transfer

JS SDK provides the blindTransfer() API in IrisRtcSession class to transfer an active call to another TN

var irisRtcSession = new IrisRtcSession();
irisRtcSession.blindTransfer(roomId, targetTN, participantJid);

Consultative Call Transfer

JS SDK provides consultTransfer() API in IrisRtcSession class to perform consultative call transfer to another TN.

var irisRtcSession = new IrisRtcSession();
irisRtcSession.consultTransfer(roomId, firstParticipantJid, secondSession, secondParticipantJid;

Mute Local Audio

An user can mute his end to stop sharing audio from their end, but at the same time they can receive audio from other end. JS SDK provides audioMuteToggle() API in IrisRtcSession class for the same.

If an user is on mute he can unmute the call and resume conversation by calling the same API again audioMuteToggle(). RoomId Should be passed as a parameter

var irisRtcSession = new IrisRtcSession();
irisRtcSession.audioMuteToggle(roomId);

Swap between two Calls

If the participant (say UserA) wants to create/join a new PSTN call session with another user (say UserC) while in an active call session (with say UserB), then UserA should put the current call with UserB on hold and create/join a new audio call with UserC. Now, to swap between two calls, UserA should hold the active call and unhold the call on hold.

Merge two Calls

In this feature, active call is kept on hold to make/join a new call, then both the calls are merged to create a conference call. Following method is provided by iOS SDK in IrisRtcSession class for this feature.

var irisRtcSession = new IrisRtcSession();

irisRtcSession.pstnMerge(roomId, firstParticipantJid, heldSession, secondParticipantJid);

Parameters
heldSession	Audio session which is on hold

//First call
var irisRtcSession = new IrisRtcSession();

irisRtcSession.createSessionWithTN(userConfig, irisRtcConn, irisRtcStream);

//Once the first call is connected add another call by keeping the first call on hold

var secondRtcSession = new IrisRtcSession();

secondRtcSession.createSessionWithTN(userConfig, irisRtcConn, irisRtcStream);


 //Or join a session with the incoming notification
irisRtcSession.joinSession(userConfig, irisRtcConn, irisRtcStream, notificationPayload);
 
//When the sessions need to be merged call merge API as follows
secondAudioSession?.merge(firstAudioSession)

Platform

IOS SDK

Android SDK