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.
|
notification | HashMap |
|
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.
|
notification | HashMap |
|
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.
|
notification | HashMap |
|
Accept/Reject an Incoming Call
When user receives an incoming PSTN call alert, the user can choose either to:
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());
}
});
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> |
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
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 |