PSTN Call

IOS SDK supports a normal audio (PSTN) call between its users. Make sure that the app 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. IrisRtcAudioSessionDelegate interface handles the callbacks specific to audio session, in addition to the generic callbacks for any session type (audio, video or chat).

Create Local Audio Stream

The IrisRtcStream class manages the audio and video streams that can be created using Iris stream APIs. The following method is called to create a stream with options. The IrisRtcStreamDelegate provides callbacks specific to stream class.

(id)initWithType:(IrisRtcSdkStreamType)type quality:(IrisRtcSdkStreamQuality)quality cameraType:(IrisRtcCameraType)cameraType delegate:(id<IrisRtcStreamDelegate>)delegate error:(NSError **)outError

Parameters
type	The type of the stream that will be created. It can be audio (kStreamTypeAudio) or video (kStreamTypeVideoOnly) or both (kStreamTypeVideo) for the stream creation.
quality	The stream quality. It can be kStreamQualityFullHD (Resolution of 1920 by 1080), kStreamQualityHD( Resolution of 1280 by 720), kStreamQualityVGA (Resolution of 640 by 368), kStreamQualityQCIF (Resolution of 320 by 240)
cameraType	A choice between front (kCameraTypeFront) and back (kCameraTypeBack) camera of the device
delegate	The delegate object for the stream that is used to receive messages during execution and upon completion or failure of the operation.
outError	Provides error code and basic error description when any exception occur in api call

startPreview() API is called after stream creation to start local audio stream.

private var micStream : IrisRtcStream?
private weak var delegate: PstnCallDelegate?
...
...
weak var streamDelegate = self
micStream = IrisRtcStream(type: kStreamTypeAudio,
                          quality: kStreamQualityHD,
                          cameraType: kCameraTypeFront,
                          delegate: streamDelegate)

// startPreview is called to start local audio stream.
micStream?.startPreview()

Note: When using the stream class, it will ask user to allow to use microphone while running. Please make sure access is allowed. When the stream is started, it won't immediately access the microphone, it will use the microphone only when the call is connected. Hence the pop-up for mic access will be presented to the user at a later point of time.

Initiate an Outgoing Call

Once the RTC connection is made, dial a valid PSTN number to make an outgoing call. An audio session is then created with the local stream and other necessary values using IrisRtcAudioSession class. createWithTN API is invoked to create a pstn/audio session, which involves creating the room using the target and source phone number.

(BOOL)createWithTN:(NSString *)targetTN _sourceTelephoneNum:(NSString *)sourceTN notificationData:(NSString *)notificationData stream:(IrisRtcStream *)stream sessionConfig:(IrisRtcSessionConfig *)sessionConfig delegate:(id<IrisRtcAudioSessionDelegate>)delegate error:(NSError **)outError

Parameters
targetTN	Contains target 10 digit telephone number
sourceTN	Contains source 10 digit telephone number
notificationData	Notification Data
stream	Local audio stream
sessionConfig	IrisRtcSessionConfig object for setting additional optional session configuration parameters
delegate	Delegate object for IrisRtcAudioSession,used to receive callbacks
outError	Provides error code and basic error description when exceptions occur in api call

var audioSession : IrisRtcAudioSession?
...
...
audioSession = IrisRtcAudioSession()
let sessionConfig = IrisRtcSessionConfig()

// this will create a room and also start call session
audioSession?.create(withTN: targetId,
                     _sourceTelephoneNum: sourceId,
                     notificationData: buildNotificationPayload(),
                     stream: micStream,
                     sessionConfig: sessionConfig,
                     delegate: self)
...
...
//build notification  payload
 private func buildNotificationPayload() -> String{
     let data = ["cname" : getPhoneNumber(),    // source telephone number
                 "cid" : getPhoneNumber(),      // source telephone number
                 "tar" : getTargetContact()]    // target telephone number

    let notificationPayload = ["type" : "pstn",
                               "topic": "federation/pstn"]


    let userData = ["data": data, "notification" : notificationPayload]

    do{
        let jsonData = try JSONSerialization.data(withJSONObject: userData, options: JSONSerialization.WritingOptions.prettyPrinted)

        return String(data: jsonData, encoding: String.Encoding.utf8)!
    }catch {
        Log.e("Error creating notification payload")
    }
    return " "
}

Accept/Reject an Incoming Call

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

Accept call
Reject call

Accept Call

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

(BOOL)joinWithSessionId:(NSString *)sessionId roomToken:(NSString *)roomToken roomTokenExpiryTime:(NSInteger)roomTokenExpiry stream:(IrisRtcStream *)stream rtcServer:(NSString *)rtcServer sessionConfig:(IrisRtcSessionConfig *)sessionConfig delegate:(id<IrisRtcAudioSessionDelegate>)delegate error:(NSError **)outError

Parameters
sessionId	Room name to be joined which is received in notification
roomToken	Room token which is received in notification
roomTokenExpiryTime	Room token expiry time which is received in notification
stream	Local audio stream
rtcServer	RTC server URL
sessionConfig	IrisRtcSessionConfig object for setting additional optional session configuration parameters
delegate	Delegate object for IrisRtcAudioSession,used to receive the callbacks
outError	Provides error code and basic error description when any exception occured in api call

var audioSession : IrisRtcAudioSession?
...
...
audioSession = IrisRtcAudioSession()
let sessionConfig = IrisRtcSessionConfig()

audioSession?.join(withSessionId: roomId,
                   roomToken: roomToken,
                   roomTokenExpiryTime: Int(truncatingIfNeeded: (roomTokenExpiryTime)!),
                   stream:micStream,        // Local audio stream
                   rtcServer: rtcServer,
                   sessionConfig: sessionConfig,
                   delegate: self)

Reject Call

User can reject an incoming call notification. iOS SDK provides reject() API in IrisRtcAudioSession for this feature.

(BOOL)reject:(NSString *)roomId toId:(NSString *)toId traceId:(NSString *)traceId server:(NSString *)server error:(NSError **)outError

Parameters
roomId	Room Id of the already created room received in notification
toId	Target routing Id received in notification
traceId	Trace Id received in notification
server	RTC server URL received in notification
outError	Provides error code and basic error description when any exception occured in api call

IrisRtcAudioSession.reject(roomId, toId:targetRoutingId, traceId:traceId, server:rtcServer)

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 audio session
By invoking close() API in IrisRtcAudioSession, audio 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 close() API once the session is closed.

var audioSession : IrisRtcAudioSession?
private var micStream : IrisRtcStream?
...
...
audioSession?.close()
micStream?.close()

On-call Features

Features offered by iOS 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. iOS SDK provides the hold() API in IrisRtcAudioSession class to hold an active call.

var audioSession : IrisRtcAudioSession?
...
...
audioSession?.hold()

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. iOS SDK provides unhold() API in IrisRtcAudioSession class to unhold a call which is already on hold.

var audioSession : IrisRtcAudioSession?
...
...
audioSession?.unhold()

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. iOS SDK provides mute() API in IrisRtcStream class for the same.

private var micStream : IrisRtcStream?
...
...
micStream?.mute()

Unmute Local Audio

If an user is on mute he can unmute the call and resume conversation. unmute() API in IrisRtcStream class is used for this feature.

private var micStream : IrisRtcStream?
...
...
micStream?.unmute()

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 IrisRtcAudioSession class for this feature.

(BOOL)mergeSession:(IrisRtcAudioSession*) heldSession

Parameters
heldSession	Audio session which is on hold

//First call

firstAudioSession?.create(withTN: targetId,
                          _sourceTelephoneNum: sourceId,
                          notificationData: buildNotificationPayload(),
                          stream: micStream,    // Local audio stream
                          sessionConfig: sessionConfig,
                          delegate: self)

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

secondAudioSession?.create(withTN: targetId,
                          _sourceTelephoneNum: sourceId,
                          notificationData: buildNotificationPayload(),
                          stream: micStream,    // Local audio stream
                          sessionConfig: sessionConfig,
                          delegate: self)

 //Or join a session with the incoming notification
 secondAudioSession?.join(withSessionId: roomId,
                          roomToken: roomToken,
                          roomTokenExpiryTime: Int(truncatingIfNeeded: (roomTokenExpiryTime)!),
                          stream:micStream,     // Local audio stream
                          rtcServer: rtcServer,
                          sessionConfig: sessionConfig,
                          delegate: self)

//When the sessions need to be merged call merge API as follows
secondAudioSession?.merge(firstAudioSession)

Audio Call Related Callbacks

onSessionSIPStatus

This callback gets invoked when we receives status of ongoing PSTN call.

(void)onSessionSIPStatus:(IrisSIPStatus )status roomId:(NSString*)roomId traceId:(NSString *)traceId

Parameters
status	Status of ongoing call
roomId	Room id received from Iris backend
traceId	Trace id

Status:

kInitializing - When the call is initializing
kConnecting - When the call is connecting
kConnected - When the call is connected
kHold - When the call is on hold
kDisconnected - When the call is disconnected

onSessionMerged

This callback gets invoked when merging an active session with the held session in PSTN call, i.e conferencing.

(void)onSessionMerged:(NSString*)roomId traceId:(NSString *)traceId

Parameters
roomId	Room id received from Iris backend
traceId	Trace id

onStreamQualityIndicator

This method is called to indicate the audio stream quality in the call.

@optional
(void)onStreamQualityIndicator:(IrisStreamQuality )quality roomId:(NSString*)roomId traceId:(NSString *)traceId;

Parameters
quality	Stream quality
roomId	Room id received from Iris backend
traceId	Trace id received from Iris backend

Quality:

kNonHD - When the call is not hd
kHD - When the call is hd
kNONE - Default

onSessionEarlyMedia

This callback gets invoked when session is about to start

(void)onSessionEarlyMedia:(NSString *)roomId traceId:(NSString *)traceId;

Parameters
roomId	Room id received from Iris backend
traceId	Trace id received from Iris backend

Platform

IOS SDK

Android SDK