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
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
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)