PSTN Call

555 RTC React Native SDK supports PSTN calls between its users. It supports on-call features such as call hold/unhold, mute/unmute, merge, etc.

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

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.

import {Rtc555Sdk,Rtc555Voice} from 'rtc-react-native-sdk';
var config = {"token" : "<555 JWT token>", // JWT token for accessing the 555 SDK/backend APIs. Token can be access from the 555 login response.
"routingId" : "a2685b26-5ef0-11ea-83a9-fa163e547f24@uc-prod.comcast.com",  // Unique id for the user logged in 555 platform.;
"url" : "https://evm.iris.comcast.net", // Event manager URL
"phoneNumber" : "2149230284", // Source Telephone Number i.e. phone number for the account you are logged in with.
"domain" : "uciris12.comcast.net", // Unique domain name 
"notificationManagerUrl" :  "https://ntm.iris.comcast.net/",//(Optional) For mobile notifications from 555 Platform.
"enableReconnect" : Boolean Value }// flag to reconnect incase of network lost/switch in an active call.
Rtc555Sdk.setConfig(config);

Initiating 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 promise. A successful dial API call return call Id, failure case return error code, and the reason for the error.


Rtc555Voice.dial(targetTN, this.getNotificationPayload())
    .then(function (response) {
    // handle success
    console.log("call id ::",response);
  })
  .catch(function (error) {
    // handle error
    console.log(error.code);
    console.log(error.reason);
  })

getNotificationPayload(){
    let data =  {'cname': <Source Telephone Number>, 'cid': <Source Telephone Number>} ;
    let notificationpayload =  [{'type': 'pstn'} , {'topic': 'federation/pstn'}];
    let userdata = {
        'data':data,
        'notification' : notificationpayload
    }

    let notificationdata = JSON.stringify(userdata);
    return notificationdata;
}

Parameters	Type	Description
number	string	Target(callee) 10 digit telephone number
notificationPayload	serialized json	Notification type (PSTN/Video) & custom user data

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

Parameters	Type	Description
data (Optional)	dictionary	e.g. cname cid
notification	dictionary	type:"pstn" topic :"federation/pstn"

Note: Please make sure client has microphone permission before accessing the dial/accept APIs from the SDK.Please add mandatory microphone permission in your info.plist file for iOS and manifest file for Android before accessing Dial/Accept call APIs to allow SDK to create local audio stream

Initiating 911 Call

To make 911 call, pass destination telephone number as 911, notification payload, voice options. 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. 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 enum Result. A successful dial API call with return call Id, failure case return error code, and the reason for the error.


Rtc555Voice.dial(targetTN, this.getNotificationPayload(),{"latitude":"1.2345678",
"longitude":"1.2345678"})
    .then(function (response) {
    // handle success
    console.log("call id ::",response);
  })
  .catch(function (error) {
    // handle error
    console.log(error.code);
    console.log(error.reason);
  })

getNotificationPayload(){
    let data =  {'cname': <Source Telephone Number>, 'cid': <Source Telephone Number>} ;
    let notificationpayload =  [{'type': 'pstn'} , {'topic': 'federation/pstn'}];
    let userdata = {
        'data':data,
        'notification' : notificationpayload
    }

    let notificationdata = JSON.stringify(userdata);
    return notificationdata;
}

Initiating an Emergency Call

To make emergency calls, pass RtcConfig, 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 promise. A successful dial API call return call Id, failure case return error code, and the reason for the error.


Rtc555Voice.emergencyDial(config, targetTN, this.getNotificationPayload())
    .then(function (response) {
    // handle success
    console.log("call id ::",response);
  })
  .catch(function (error) {
    // handle error
    console.log(error.code);
    console.log(error.reason);
  })

getNotificationPayload(){
    let data =  {'cname': <Source Telephone Number>, 'cid': <Source Telephone Number>} ;
    let notificationpayload =  [{'type': 'pstn'} , {'topic': 'federation/pstn'}];
    let userdata = {
        'data':data,
        'notification' : notificationpayload
    }

    let notificationdata = JSON.stringify(userdata);
    return notificationdata;
}

Parameters	Type	Description
config	RtcConfig	Object
number	string	Target(callee) 10 digit telephone number
notificationPayload	serialized json	Notification type (PSTN/Video) & custom user data

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

Parameters	Type	Description
data (Optional)	dictionary	e.g. cname cid
notification	dictionary	type:"pstn" topic :"federation/pstn"

Accept/Reject an Incoming Call

When user receives an incoming PSTN call alert, the user can choose to:

Accept call
Reject call

Accept Call

If the user wants to accept the incoming PSTN call request, use accept API and pass the notification payload received from incoming notification. accept API returns promise. A successful Accept API call will return call id and failure case return error code and reason for the error.

  
  var notificationData = {
      room_id: notificationPayload.roomid,
      trace_id: notificationPayload.traceid,
      to_routing_id: notificationPayload.routingid,
      rtc_server: notificationPayload.rtcserver,
      room_token: notificationPayload.roomtoken,
      room_token_expiry_time: notificationPayload.roomtokenexpirytime,
  };

  Rtc555Voice.accept(notificationData)
     .then(function (response) {
        // handle success
        console.log("call id ::",response);
     })
     .catch(function (error) {
        // handle error
       console.log(error.code);
       console.log(error.reason);
  })

Pass notification payload received at incoming notification.

Parameters	Type	Description
notificationData	dictionary	Contains key/value pair for the data received from push payload

Notification data is constructed from the values received from the incoming push notification payload :

Parameters
trace_id	trace id
room_id	Room name that needs to be joined which is received in notification payload.
room_token	Room token which is received in notification payload.
room_token_expiry_time	Room token expiry time retrieved from notification payload.
to_routing_id	Caller's routing Id
rtc_server	RTC server URL extracted from notification payload.

Reject Call

Users can reject an incoming call using reject API. Pass notification payload received in incoming notification.A successful reject API call will return call id and failure case return error code and reason for the error.

  var notificationData = {
    room_id: notificationPayload.roomid,
    trace_id: notificationPayload.traceid,
    to_routing_id: notificationPayload.routingid,
    rtc_server: notificationPayload.rtcserver,
    room_token: notificationPayload.roomtoken,
    room_token_expiry_time: notificationPayload.roomtokenexpirytime,
  };

  Rtc555Voice.reject(notificationData)
    .then(function (response) {
      // handle success
      console.log("call id ::",response);
    })
    .catch(function (error) {
      // handle error
      console.log(error.code);
      console.log(error.reason);
    })

Pass notification payload received at incoming notification.

Parameters	Type	Description
notificationData	dictionary	Contains key/value pair for the data received from push payload

Notification data is constructed from the values received from the incoming push notification payload :

Parameters
trace_id	trace id
room_id	Room name that needs to be joined which is received in notification payload.
room_token	Room token which is received in notification payload.
room_token_expiry_time	Room token expiry time retrieved from notification payload.
to_routing_id	Caller's routing Id
rtc_server	RTC server URL extracted from notification payload.

End an Active Call

Users need to hangup API to end the active call.

Rtc555Voice.hangup(callId)

Parameters
callId	callId is unique id for the 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()

Callkit Support

Use https://github.com/react-native-webrtc/react-native-callkeep Package for Callkit Features on iOS and Callkit in client requires below API calls from SDK

Initialize Audio Unit

This API call allows users to manually initilize Audio Uint while using CallKit. User need to call this before starting / joining the call. This API is platform specific and is only required in iOS to initialize audio.

if (Platform.OS === "ios") {
      Rtc555Voice.initializeManualAudio(isAudioManual);
    }

Parameters	Type	Description
isAudioManual	Bool	Pass "true" to initilize Audio unit Manually

Enable Audio

This API is only effective if initilizeManualAudio is "true". This API call allows users to activate / deactivate audio while using callkit. This API is platform specific and is only required in iOS to enable audio true/false.

Use this API on the CallKeep listeners "didActivateAudioSession" and "didDeactivateAudioSession" as shown below to enable audio true/false.

      RNCallKeep.addEventListener("didActivateAudioSession", () => {
        if (Platform.OS === "ios") {
          Rtc555Voice.enableAudio(isAudioEnabled);
        }
      });
      RNCallKeep.addEventListener("didDeactivateAudioSession", () => {
        if (Platform.OS === "ios") {
          Rtc555Voice.enableAudio(isAudioEnabled);
        }
      });

Parameters	Type	Description
isAudioEnabled	Bool	Pass "true" or "false" to start /stop Audio

On-call Features

Features offered by SDK for PSTN call are:

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

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(callId)

Parameters
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 already held call. Both caller and callee will hear each other after invoking this call.

Rtc555Voice.unhold(callId)

Parameters
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(callId)

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

Unmute Local Audio

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

Rtc555Voice.unmute(callId)

Parameters
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(callId,tone)

Parameters
callId	callId is unique id for this call which was returned from dial/accept API
tone	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(activeCallId, heldCallId)
    .then(function (response) {
      // handle success
      console.log("success");
    })
    .catch(function (error) {
      // handle error
      console.log(error.code);
      console.log(error.reason);
    })

Parameters
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

Callbacks

To get call status or error report during the call, Pass event name and listener to addEventListener api.

Rtc555Voice.addEventListener(event,listener);

Parameters
event	event name i.e.. "status" or "error"
listener	function which listens callback

onStatus

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

Rtc555Voice.addEventListener("status",this.onCallStatus.bind(this));

onCallStatus = (callId, status) =>{
  console.log("Call id is",callId)
  console.log("Call status is",status)
}

Parameters
callId	Call id for the ongoing call
status	status of 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.
reconnecting - When the call is reconnecting i.e. when there is switch in network (wifi to LTE and vice versa)
hold - When the call is hold

onError

This callback gets invoked when we receive an error from an ongoing PSTN call.

Rtc555Voice.addEventListener("error",this.onCallError.bind(this));

onCallError = (callId, errorInfo) =>{
  console.log("Call status is",errorInfo.code)
  console.log("Call status is",errorInfo.reason)
}

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

In order to remove listeners for event, pass callid and event to removeEventListener api.

Rtc555Voice.removeEventListener(callId,event);

Parameters
callId	unique id for this call which was returned from dial/accept API
event	event name which we want to stop receiving callback i.e., "status" or "error"

OnCallStats

Call Stats 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" }

Rtc555Voice.addEventListener("callStats",this.onCallStats.bind(this));

onCallStats = (callId, status) =>{
  console.log("Call quality is", status.callQuality)
}

Parameters
callId	Call id for the ongoing call
callQuality	call quality of ongoing call as integer value

onNotification

Use notification callback to receive notify and cancel XMPP notifications or the cancel notification when subscribed to APNs/FCM. The client needs to be connected to 555 backend to avail of this notification callback.

    Rtc555Sdk.on("notification", (notificationData) => {
        console.log("notification",JSON.stringify(notificationData))
    }

Parameters
notificationData	notification payload for incoming notification

Platform

IOS SDK

Android SDK