PSTN Call

Rtc555 Android SDK supports PSTN calls between its users. It supports on-call features such as call hold/unhold, mute/unmute, etc.

Before initiating or accepting a PSTN call, make sure you have logged in to 555 platform.

SDK initialization

Below API initializes and sets the context for the SDK. It is advisable to call this API at the launch of the application. Pass application context to the API.

Rtc555Sdk.initializeLibrary(getApplication());

Parameters	Description
appContext	Application context

Adding SDK configuration

To make PSTN/Voice related API call, SDK should have below mentioned mandatory configuration data to establish a connection with the 555 platform backend.

      Rtc555Config config = Rtc555Sdk.getInstance().getConfig();
      config.phoneNumber = "2149230284" // Source Telephone Number i.e. phone number for the account you are logged in with.
      config.routingId = "a2685b26-5ef0-11ea-83a9-fa163e547f24@uc-prod.comcast.com"  // Unique id for the user logged in 555 platform. 
      config.url = "https://evm.iris.comcast.net" // Event manager URL
      config.token = "<555 JWT token>" // JWT token for accessing the 555 SDK/backend APIs. Token can be access from the 555 login response. 
      config.domain = "uciris12.comcast.net" // Unique domain name
      config.notificationManagerUrl = "https://ntm.iris.comcast.net" // (Optional) For mobile notifications from 555 Platform

      Rtc555Sdk.setConfig(config);

Initiate an Outgoing Call

To make outgoing calls, pass destination telephone number, notification to dial API. Notification payload contains two fields called data and notification. The client can make use of data to send any custom key/value pair to remote (callee) end as part of the push notification payload. The below code shows some example to send caller Id (cid) & caller name (cname). The notification key contains the notification type and federation type as mentioned in below code snippet.

dial API returns a single value response. Success case of response will return call-Id (Unique identifier for the call). On failure it returns Rtc555Exception object.

  Rtc555Voice.dial("1234567890", buildNotificationPayload(), observer ,new Rtc555Result() {
       @Override
       public void onSuccess(String callId) {
           Log.d("Dial success","Dial success = "+callId);
       }
 
       @Override
       public void onError(Rtc555Exception e) {
             Log.d("Dial error = ",e.getMessage());
             Log.d("Dial error code = ",e.getCode());
       }
  });

 
//build notification  payload
String buildNotificationPayload() {
    Context context = mAppContext;
    
    final String phoneNumber = "9876543210" //source TN
    JSONObject userdata = new JSONObject();
      
    try {
        JSONObject data = new JSONObject();
        data.put("cname",phoneNumber);
        data.put("cid",phoneNumber);
        data.put("tar","1234567890"); //Target TN

        JSONObject notification = new JSONObject();
        notification.put("type", "pstn");
        notification.put("topic", "federation/pstn");

        userdata.put("data", data);
        userdata.put("notification", notification);
    }
    catch (Exception e) {
      e.printStackTrace();
    }
    
    return userdata.toString();
}

Parameters	Description
targetTelephoneNum	Target(callee) 10 digit telephone number.
notificationPayload	Notification payload data.
observer	Rtc555VoiceObserver
Rtc555Result	Instance of observer which gives success or failure callback

Below is the Notification payload need to be build for outgoing notificationData:

Property	Type	Description
data	HashMap	e.g. cname cid targetId
notification	HashMap	type:"pstn" topic :"federation/pstn"

Note: Please make sure clinent has microphone permission before accessing the dial/accept APIs from the SDK.

Initiate an Outgoing Call with Voice options

Initiating 911 Call

To make 911 call, pass destination telephone number as 911, notification payload & voice options to dial API. Notification payload contains two fields called data and notification. Voice options should contain two fields latitude and longitude. If client does not have valid latitude and longitude then it should pass 0.0 and 0.0 respectively. The client can make use of data to send any custom key/value pair to remote (callee) end as part of the push notification payload. The below code shows some example to send caller Id (cid) & caller name (cname). The notification key contains the notification type and federation type as mentioned in below code snippet.

dial API returns a single value response. Success case of response will return call-Id (Unique identifier for the call). On failure it returns Rtc555Exception object.

  Rtc555Voice.dial("911", buildNotificationPayload(), {"latitude" : "1.2345678", "longitude":"1.2345678"}, observer ,new Rtc555Result() {
       @Override
       public void onSuccess(String callId) {
           Log.d("Dial success","Dial success = "+callId);
       }
 
       @Override
       public void onError(Rtc555Exception e) {
             Log.d("Dial error = ",e.getMessage());
             Log.d("Dial error code = ",e.getCode());
       }
  });

 
//build notification  payload
String buildNotificationPayload() {
    Context context = mAppContext;
    
    final String phoneNumber = "9876543210" //source TN
    JSONObject userdata = new JSONObject();
      
    try {
        JSONObject data = new JSONObject();
        data.put("cname",phoneNumber);
        data.put("cid",phoneNumber);
        data.put("tar","1234567890"); //Target TN

        JSONObject notification = new JSONObject();
        notification.put("type", "pstn");
        notification.put("topic", "federation/pstn");

        userdata.put("data", data);
        userdata.put("notification", notification);
    }
    catch (Exception e) {
      e.printStackTrace();
    }
    
    return userdata.toString();
}

Parameters	Description
targetTelephoneNum	911
notificationPayload	Notification payload data.
voiceOptions	HashMap<String,Object>	e.g. {"latitude":"1.2345678", "longitude":"1.2345678"}
observer	Rtc555VoiceObserver
Rtc555Result	Instance of observer which gives success or failure callback

Below is the Notification payload need to be build for outgoing notificationData:

Property	Type	Description
data	HashMap	e.g. cname cid targetId
notification	HashMap	type:"pstn" topic :"federation/pstn"

Note: Please make sure client has microphone permission before accessing the dial 911 APIs from the SDK.

Initiate an Emergency Call

To make emergency calls, pass Rtc555Config, destination telephone number, notification to emergencyDial API. Notification payload contains two fields called data and notification. The client can make use of data to send any custom key/value pair to remote (callee) end as part of the push notification payload. The below code shows some example to send caller Id (cid) & caller name (cname). The notification key contains the notification type and federation type as mentioned in below code snippet.

emergencyDial API returns a single value response. Success case of response will return call-Id (Unique identifier for the call). On failure it returns Rtc555Exception object.

  Rtc555Voice.emergencyDial(config, "1234567890", buildNotificationPayload(), observer ,new Rtc555Result() {
       @Override
       public void onSuccess(String callId) {
           Log.d("Emergency Dial success","Dial success = "+callId);
       }
 
       @Override
       public void onError(Rtc555Exception e) {
             Log.d("Emergency Dial error = ",e.getMessage());
             Log.d("Emergency Dial error code = ",e.getCode());
       }
  });

 
//build notification  payload
String buildNotificationPayload() {
    Context context = mAppContext;
    
    final String phoneNumber = "9876543210"; //source TN
    JSONObject userdata = new JSONObject();
      
    try {
        JSONObject data = new JSONObject();
        data.put("cname",phoneNumber);
        data.put("cid",phoneNumber);
        data.put("tar","1234567890"); //Target TN

        JSONObject notification = new JSONObject();
        notification.put("type", "pstn");
        notification.put("topic", "federation/pstn");

        userdata.put("data", data);
        userdata.put("notification", notification);
    }
    catch (Exception e) {
      e.printStackTrace();
    }
    
    return userdata.toString();
}

Parameters	Description
config	Rtc555Config object
targetTelephoneNum	Target(callee) 10 digit telephone number.
notificationPayload	Notification payload data.
observer	Rtc555VoiceObserver
Rtc555Result	Instance of observer which gives success or failure callback

Below is the Notification payload need to be build for outgoing notificationData:

Property	Type	Description
data	HashMap	e.g. cname cid targetId
notification	HashMap	type:"pstn" topic :"federation/pstn"

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

To accept the incoming PSTN call request, invoke accept API and pass the data received from incoming push notification. The API also needs an instance of RTC555Result observer which provides onSuccess and onError callbacks.

accept API returns call-Id (Unique identifier for the call). On failure it returns Rtc555Exception object.

  Rtc555Voice.accept(HashMap notificationdata,observer, new Rtc555Result() {
          @Override
          public void onSuccess(String callId) {
              Log.d("Dial success","Dial success = "+callId);            
          }

          @Override
          public void onError(Rtc555Exception e) {
              Log.d("Dial error = ",e.getMessage());
              Log.d("Dial error code = ",e.getCode());
          }
       });

Parameters	Description
notificationdata	Incoming notification payload data.
observer	Rtc555VoiceObserver
Rtc555Result	Instance of observer which gives success or failure callback

First parameter i.e notificationdata is the map including the key/value pair for the values received as part of the incoming push payload. Parse the notification payload and populate the notificationdata map for below keys.

Parameters	Description	Mapping in Notification Payload
trace_id	Trace ID for the call	<trace_id>
room_id	Room ID that needs to be joined	<room_id>
room_token	Room token	<room_token>
room_token_expiry_time	Room token expiry time	<room_token_expiry_time>
to_routing_id	Caller's routing Id	<routing_id>
rtc_server	RTC server URL	<rtc_server>

Reject Call

To reject an incoming call invoke the reject API. Pass the data received in incoming push notification and an instance of RTC555Result observer which provides onSuccess and onError callbacks.

    Rtc555Voice.reject(HashMap notificationdata, new Rtc555Result() {
            @Override
            public void onSuccess(String callId) {
                Log.d("Dial success","Dial success = "+callId);                     
            }

            @Override
            public void onError(Rtc555Exception e) {
                Log.d("Dial error = ",e.getMessage());
                Log.d("Dial error code = ",e.getCode());
            }
         });

Parameters	Description	Mapping in Notification Payload
trace_id	Trace ID for the call	<trace_id>
room_id	Room ID that needs to be joined	<room_id>
room_token	Room token	<room_token>
room_token_expiry_time	Room token expiry time	<room_token_expiry_time>
to_routing_id	Caller's routing Id	<routing_id>
rtc_server	RTC server URL	<rtc_server>

End an Active Call

Users need to invoke hangup API to end the active call.

  Rtc555Voice.hangup(String callId);

Parameters	Description
callId	callId is unique id for this call which was returned from dial/accept API

Clean up the session.

Call below API in Rtc555Sdk to release all the resources used by SDK. This call also allows the client to disconnect with the 555 platform backend. The app developer should call this API if the app goes to the background or kill state to release the SDK resource. Client need to call setConfig API again before attempting to initiate/accept the call.

  Rtc555Sdk.cleanup();

On-call Features

Features offered by Android SDK for PSTN call are:

Hold Call
Unhold Call
Mute Local Audio
Unmute Local Audio
DTMF Tone

Hold Call

This API call allows users to hold the ongoing call. Both caller and callee won't able to hear to each other after invoking this call.

    Rtc555Voice.hold(String callId);

Parameters	Description
callId	callId is unique id for this call which was returned from dial/accept API

Unhold Call

This API call allows users to un-hold the already held call. Both caller and callee will hear each other after invoking this call.

    Rtc555Voice.unHold(String callId);

Parameters	Description
callId	callId is unique id for this call which was returned from dial/accept API

Mute Local Audio

This API call allows users to mute it's audio in the call.

    Rtc555Voice.mute(String callId);

Parameters	Description
callId	callId is unique id for this call which was returned from dial/accept API

Unmute Local Audio

This API call allow user to un-mute it's audio in the call.

    Rtc555Voice.unMute(String callId);

Parameters	Description
callId	callId is unique id for this call which was returned from dial/accept API

Send DTMF Tone

This API call allows users to send DTMF during the call.

    Rtc555Voice.sendDTMF(String callId,DtmfInputType tone)

Parameters	Description
callId	callId is unique id for this call which was returned from dial/accept API
DtmfInputType	Input for DTMF tone

Merge Call

This API call allow user to merge two calls. After invoking this, both calls will be merged and all three participants will be able to hear each other.

    Rtc555Voice.merge(String activeCallId,String heldCallId){
    @Override
    public void onSuccess() {
        Log.d("Merge success");          
    }

    @Override
    public void onError(Rtc555Exception e) {
        Log.d("Merge error = ",e.getMessage());
    }
 });

Parameters	Description
activeCallId	callId is unique id for the call which was returned from dial/accept API
heldCallId	callId is unique id for the call which was returned from dial/accept API

Audio Call Callbacks

To get call status or error report during the call, implement Rtc555VoiceObserver interface and initialize the observer and pass in Dial/Accept API

onStatus

This callback gets invoked when we receive the status of an ongoing PSTN call.

    void onStatus(Rtc555Sdk.CallStatus callStatus, String callId);

Parameters	Description
status	status of ongoing call
callId	Call id for the ongoing call

Call Status:

initializing - When the call is initializing
connecting - When the call is connecting i.e. when remote party is ringing.
connected - When the call is connected and media(voice) started transferring.
disconnected - When the call is disconnected i.e. when remote side hang up the call.
hold - When the call is hold

onError

This callback gets invoked when we receives Rtc555Exception from an ongoing PSTN call.

    void onError(Rtc555Exception rtc555Exception, String callId);

Parameters	Description
rtc555Exception	error object consists of error code and error message
callId	callId received from backend

onCallStats

This callback gives call quality during the call(i.e. 4,3,2,1), which presents ( 1: "very bad", 2: "bad", 3: "good",4: "very good").

   public void onCallStats(Integer callQuality, String bitrate) {
    System.out.println("Call quality "+callQuality+" Bitrate "+bitrate);
  }

Parameters	Description
callQuality	call quality of ongoing call as integer value
bitrate	cTransmit bitrate of ongoing call as string value

onNotification

In case you want to use XMPP notification (Instead of FCM), use this callback. The client needs to be connected to 555 backend to avail of this notification callback.

    void onNotification(HashMap notifyData);

Parameters	Description
notifyData	notification payload for incoming notification

Platform

IOS SDK

Android SDK

IOS SDK

Android SDK

React Native SDK

SDK initialization

Adding SDK configuration

Initiate an Outgoing Call

Initiate an Outgoing Call with Voice options

Initiating 911 Call

Initiate an Emergency Call

Accept/Reject an Incoming Call

Accept Call

Reject Call

End an Active Call

Clean up the session.

On-call Features

Hold Call

Unhold Call

Mute Local Audio

Unmute Local Audio

Send DTMF Tone

Merge Call

Audio Call Callbacks

onStatus

onError

onCallStats

onNotification