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