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
• Reject Call

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