PSTN Call
Iris Android SDK supports PSTN calls between its users. It supports on-call features such as hold, mute, call swapping and conferencing. Every session related API requests have their respective callbacks to notify the user about the status of the request. IrisRtcAudioSessionObserver interface provides the callbacks specific to audio session, in addition to the generic callbacks for any session type (audio, video or chat).
Before initiating or accepting a PSTN call, make sure to have logged in and have an active Rtc Connection. If app has been disconnected from Rtc server due to inactivity, user has to request for Rtc connection. Before creating or joining a session, audio stream should be created.
Create Local Audio Stream
The IrisRtcStream class manages the audio and video streams that can be created using IRIS stream APIs. When a video or audio session is created, you can associate the session with a stream. The IrisRtcStreamObserver provides callbacks related to stream class.
IrisRtcStream(IrisRtcStream.IrisRtcSdkStreamType type, IrisRtcStream.IrisRtcSdkStreamQuality streamQuality, IrisRtcStream.IrisRtcCameraType camType, IrisRtcStream.IrisRtcStreamObserver observer, Context context)
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. |
streamQuality | The stream quality. It can be kStreamQuality_FullHD (Resolution of 1920 by 1080), kStreamQuality_HD( Resolution of 1280 by 720), kStreamQuality_VGA (Resolution of 640 by 368), kStreamQuality_QCIF (Resolution of 320 by 240) |
camType | A choice between front (kCameraTypeFront) and back (kCameraTypeBack) camera of the device |
observer | Listener to receive the callbacks upon completion or failure of the operation. |
context | Application context |
To start the local audio stream, call the startPreview API from the above created stream.
...
...
IrisRtcStream rtcStream = new IrisRtcStream(IrisRtcStream.IrisRtcSdkStreamType.kStreamTypeAudio, IrisRtcStream.IrisRtcSdkStreamQuality.kStreamQuality_FullHD, IrisRtcStream.IrisRtcCameraType.kCameraTypeFront, observer, context);
rtcStream.startPreview(eglBaseContext);
...
...
Note: When using the stream class, it will ask user to allow to use microphone while running. Please make sure access is allowed. The run time permission dialog is shown after Andriod version Marshmallow onwards. When the stream is started, it wont immediately access the microphone, it will use the microphone only when the call is connected. Hence the pop-up for microphone access will be presented to the user at a later point of time.
Initiate an Outgoing Call
Create a local stream and pass it to SDK with other parameters to create an audio session.
Create the session for your PSTN call using,
void create(String sourceTN, String targetTN, String userData, IrisRtcStream stream, IrisRtcAudioSession.IrisRtcAudioSessionObserver observer) throws IrisRtcSDKException
Parameters | |
---|---|
sourceTN | Source telephone number in e.164 format. |
targetTN | Target telephone number in e.164 format. |
userData | Notification payload data. |
stream | Local Audio stream to be sent. |
observer | Listener to receive the callbacks for audio session. |
IrisRtcSDKException | Exception handler for SDK. |
...
...
IrisRtcAudioSession audioSession = new IrisRtcAudioSession(appContext);
...
...
try{
audioSession.create(dialerNo, targetNo, buildNotificationPayload(), rtcStream, audiosessionObserver);
} catch (IrisRtcSDKException e) {
Log.e(e, "Failed to create session");
}
...
...
//build notification payload
String buildNotificationPayload() {
Context context = mAppContext;
JSONObject userdata = new JSONObject();
JSONObject notification = new JSONObject();
JSONObject data = new JSONObject();
try {
final String phoneNumber = PrefManager.getPhoneNumber(context);
data.put("cname", phoneNumber);
data.put("cid", phoneNumber);
data.put("tar", targetId);
notification.put("type", "pstn");
notification.put("topic", "federation/pstn");
userdata.put("data", data);
userdata.put("notification", notification);
} catch (JSONException e) {
e.printStackTrace();
}
}
Once the remote party has accepted your call request, audio stream from remote participant is as well available to the app. Now, both parties can hear the remote audio.
Accept/Reject an Incoming Call
When user receives an incoming PSTN call alert, the user can choose either to:
Accept Call
If the user wants to accept the incoming PSTN call request, the user should be in active Rtcconnection and local audio stream has to be initiated. To join the session, below API should be used:
void join(String roomId, String roomToken, String roomTokenExpiry,IrisRtcStream stream, String rtcServer, IrisRtcAudioSessionObserver observer) throws IrisRtcSDKException
Parameters | |
---|---|
roomId | Room name that needs to be joined which is recieved in notification payload. |
roomToken | Room token which is recieved in notification payload. |
roomTokenExpiry | Room token expiry time retrieved from notification payload. |
stream | Local Audio stream to be sent. |
rtcServer | RTC server URL extracted from notification payload. |
observer | Listener to receive the callbacks for audio session. |
IrisRtcSDKException | Exception handler for SDK. |
...
...
IrisRtcAudioSession audioSession = new IrisRtcAudioSession(appContext);
...
...
try{
audioSession.join(roomId, roomToken, roomTokenExpiryTime, rtcStream, rtcserver, audiosessionObserver);
} catch (IrisRtcSDKException e) {
Log.e(e, "Failed to join pstn call session");
}
...
...
Reject Call
User can reject an incoming call notification. Iris Android SDK provides reject() API in IrisRtcAudioSession for this feature.
static void reject(String roomId, String toId, String traceId, String rtcServer) throws IrisRtcSDKException
Parameters | |
---|---|
roomId | Room Id of the already created room received in notification payload |
toId | Target routing Id received in notification payload |
traceId | Trace Id received in notification payload |
rtcServer | RTC server URL received in notification payload |
IrisRtcSDKException | Exception handler for SDK. |
...
...
IrisRtcAudioSession audioSession = new IrisRtcAudioSession(appContext);
...
...
try {
audioSession.reject(roomId, targetRoutingId, traceId, rtcServer);
} catch (IrisRtcSDKException e) {
e.printStackTrace();
}
...
...
End an Active Call
On end call, all data and objects associated with that particular call must be cleared to avoid memory leak and efficiency. Close audio session by invoking close() API in IrisRtcAudioSession, audio session will get closed by releasing all objects associated with it.
...
private IrisRtcAudioSession audioSession;
...
...
audioSession.close();
...
...
On-call Features
Features offered by Iris Android SDK for PSTN call are:
Hold Call
Either caller or callee can hold a call. When the call is on hold, neither of the participants will be able to send or receive audio stream. Iris Android SDK provides the hold() API in IrisRtcAudioSession class to hold an active call.
...
private IrisRtcAudioSession audioSession;
...
...
audioSession.hold();
...
...
Unhold Call
The participant who puts the call on hold can resume the call and all the participants will now be able to send & receive audio streams. Iris Android SDK provides unhold() API in IrisRtcAudioSession class to unhold a call which is already on hold.
...
private IrisRtcAudioSession audioSession;
...
...
audioSession.unhold();
...
...
Mute Local Audio
The participant can mute his end to stop sharing audio from their end, but at the same time they can receive audio from the other end. Iris Android SDK provides mute() API in IrisRtcStream class for the same.
...
private IrisRtcStream rtcStream;
...
...
rtcStream.mute();
...
...
Unmute Local Audio
If a participant is on mute, he can unmute the call. Only then the other party can hear the audio. Iris Android SDK provides unmute() API in IrisRtcStream class for the same.
...
private IrisRtcStream rtcStream;
...
...
rtcStream.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 SDK in IrisRtcAudioSession class for this feature.
boolean mergeSession(IrisRtcAudioSession heldSession)
Parameters | |
---|---|
heldSession | First Audio session which is on hold |
...
private IrisRtcAudioSession secondAudioSession;
...
private IrisRtcAudioSession heldSession;
...
...
boolean state = secondAudioSession.mergeSession(heldSession);
...
...
Audio Call Related Callbacks
onSessionSIPStatus
This callback gets invoked when we receives status of ongoing PSTN call.
void onSessionSIPStatus(IrisSIPStatus status, String roomId, String traceId);
Parameters | |
---|---|
status | Status of ongoing call |
roomId | Room id received from backend |
traceId | Trace id |
Status:
- kInitializing - When the call is initializing
- kConnecting - When the call is connecting
- kConnected - When the call is connected
- kDisconnected - When the call is disconnected
- kHold - When the call is hold
onSessionMerged
This callback gets invoked when merging an active session with the held session in PSTN call, i.e conferencing.
void onSessionMerged(String roomId, String traceId);
Parameters | |
---|---|
roomId | Room id received from backend |
traceId | Trace id |
onStreamQualityIndicator
This method is called to indicate the audio stream quality in the call.
void onStreamQualityIndicator(IrisStreamQuality quality, String roomId, String traceId);
Parameters | |
---|---|
quality | Stream quality |
roomId | Room id received from backend |
traceId | Trace id |
Quality:
- kNonHD - When the call is not hd
- kHD - When the call is hd
onSessionEarlyMedia
This callback gets invoked when session is about to start.
void onSessionEarlyMedia(String roomId, String traceId);
Parameters | |
---|---|
roomId | Room id received from backend |
traceId | Trace id |