PSTN Call

RTC 555 iOS 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.

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.

Rtc555Sdk.initializeLibrary()

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.

let config:Rtc555Config = Rtc555Sdk.sharedInstance.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. (Identity manager response) 
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: config)

Initiating an Outgoing Call

To make outgoing calls, pass destination telephone number, notification & Rtc555VoiceDelegate 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 enum Result. A successful dial API call with return call Id, failure case return error code, and the reason for the error.

Rtc555Voice.dial( number: "1234567890", notificationPayload:buildNotificationPayload(), rtcVoiceDelegate: self){ result in
           switch result {
           case .success(let callId):
               print("Dial was success and callid is = \(callId)")
           case .failure(let error):
            print(error)
           }
       }
       
 //build notification  payload
 private func buildNotificationPayload() -> String{
     let data = ["cname" : "Caller Name"
                 "cid" : "Caller Id"]
                 
    let notificationPayload = ["type" : "pstn",
                               "topic": "federation/pstn"]

    let userData = ["data": data, "notification" : notificationPayload]

    do{
        let jsonData = try JSONSerialization.data(withJSONObject: userData, options: JSONSerialization.WritingOptions.prettyPrinted)

        return String(data: jsonData, encoding: String.Encoding.utf8)!
    }catch {
        print("Error creating notification payload")
    }
    return " "
}

Parameters	Type	Description
number	string	Target(callee) 10 digit telephone number
notificationPayload	serialized json	Notification type (PSTN/Video) & custom user data
rtcVoiceDelegate	Rtc555VoiceDelegate	Delegate object for call status & error callback

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 to add mandatory microphone permission in your info.plist file before accessing Dial/emergencyDial/Accept call APIs to allow SDK to create local audio stream

Initiating an Outgoing Call with Voice options

Initiating 911 Call

To make 911 call, pass destination telephone number as 911, notification payload, voice options & Rtc555VoiceDelegate to dial API. 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(number: "911", notificationPayload:buildNotificationPayload(), voiceOptions:["latitude" : "1.2345678", "longitude":"1.2345678"], rtcVoiceDelegate: self){ result in
           switch result {
           case .success(let callId):
               print("Dial was success and callid is = \(callId)")
           case .failure(let error):
                print(error)
           }
       }
       
 //build notification  payload
 private func buildNotificationPayload() -> String{
     let data = ["cname" : "Caller Name"
                 "cid" : "Caller Id"]
                 
    let notificationPayload = ["type" : "pstn",
                               "topic": "federation/pstn"]

    let userData = ["data": data, "notification" : notificationPayload]

    do{
        let jsonData = try JSONSerialization.data(withJSONObject: userData, options: JSONSerialization.WritingOptions.prettyPrinted)

        return String(data: jsonData, encoding: String.Encoding.utf8)!
    }catch {
        print("Error creating notification payload")
    }
    return " "
}

Parameters	Type	Description
number	string	911
notificationPayload	serialized json	Notification type (PSTN/Video) & custom user data
voiceOptions	Dictionary<String,Any>	e.g. ["latitude" : "1.2345678", "longitude":"1.2345678"]
rtcVoiceDelegate	Rtc555VoiceDelegate	Delegate object for call status & error callback

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

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

Note: Please make sure to add mandatory microphone and location permission in your info.plist file before accessing dail 911 API to allow SDK to create local audio stream

Initiating an Emergency Call

To make emergency calls, pass Rtc555Config, destination telephone number, notification & Rtc555VoiceDelegate 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 enum Result. A successful dial API call with return call Id, failure case return error code, and the reason for the error.

Rtc555Voice.emergencyDial(config:Rtc555Config, number: "1234567890", notificationPayload:buildNotificationPayload(),rtcVoiceDelegate: self) { result in
           switch result {
           case .success(let callId):
               print("Emergency Dial was success and callid is = \(callId)")
           case .failure(let error):
                print(error)
           }
       }
       
 //build notification  payload
 private func buildNotificationPayload() -> String{
     let data = ["cname" : "Caller Name"
                 "cid" : "Caller Id"]
                 
    let notificationPayload = ["type" : "pstn",
                               "topic": "federation/pstn"]

    let userData = ["data": data, "notification" : notificationPayload]

    do{
        let jsonData = try JSONSerialization.data(withJSONObject: userData, options: JSONSerialization.WritingOptions.prettyPrinted)

        return String(data: jsonData, encoding: String.Encoding.utf8)!
    }catch {
        print("Error creating notification payload")
    }
    return " "
}

Parameters	Type	Description
config	Rtc555Config	Class Object
number	string	Target(callee) 10 digit telephone number
notificationPayload	serialized json	Notification type (PSTN/Video) & custom user data
rtcVoiceDelegate	Rtc555VoiceDelegate	Delegate object for call status & error callback

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

Parameters	Type	Description
data (Optiinal)	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 APNS push notification & & Rtc555VoiceDelegate . accept API returns enum result. Success case of result will return call id and failure case return error code and reason for the error.

Rtc555Voice.accept(notificationData: buildNotificationData(),rtcVoiceDelegate: self){ result in
            switch result {
            case .success(let callId):
                print("Accept was success and callid is = \(callId)")
                 self.callId = callId
            case .failure(let error):
                print(error)
            }
        }

//Note : Here userInfo is the dictionary payload received in didReceiveIncomingPushWith callback for push notification or notificationData received from onNotification for XMPP notification.

private func buildNotificationData() -> Dictionary{
     let notificationdata = ["trace_id" : (userInfo["trace_id"] as? String) ?? "",
                         "room_id" : (userInfo["room_id"] as? String) ?? ""y,
                         "rtc_server" : n(userInfo["rtc_server"] as? String) ?? "",
                         "to_routing_id" : (userInfo["routing_id"] as? String) ?? "",
                         "room_token" : (userInfo["room_token"] as? String) ?? "",
                         "room_token_expiry_time" : (userInfo["room_token_expiry_time"] as? Int64) ?? 0
     ] as [String : Any]       
     return notificationdata
}

Pass notification payload received at incoming notification.

Parameters	Type	Description
notificationdata	dictionary	Contains key/value pair for the data received from incoming APNs/XMPP payload
rtcVoiceDelegate	Rtc555VoiceDelegate	Delegate object for call status & error callback

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

Parameters	Description
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 APNs/XMPP notification.

Rtc555Voice.reject(notificationData: buildNotificationData()){ result in
    switch result {
    case .success(let callId):
        print("Reject was success  = \(callId)")
         self.callId = result
    case .failure(let error):
        print(error)
    }
}

//Note : Here userInfo is the dictionary payload received in didReceiveIncomingPushWith callback for push notification or notificationData received from onNotification for XMPP notification.

private func buildNotificationData() -> Dictionary{
     let notificationdata = ["trace_id" : (userInfo["trace_id"] as? String) ?? "",
                         "room_id" : (userInfo["room_id"] as? String) ?? ""y,
                         "rtc_server" : n(userInfo["rtc_server"] as? String) ?? "",
                         "to_routing_id" : (userInfo["routing_id"] as? String) ?? "",
                         "room_token" : (userInfo["room_token"] as? String) ?? "",
                         "room_token_expiry_time" : (userInfo["room_token_expiry_time"] as? Int64) ?? 0
     ] as [String : Any]       
     return notificationdata
}

Pass notification payload received at incoming notification.

Parameters	Type	Description
notificationdata	dictionary	Contains key/value pair for the data received from incoming APNs/XMPP payload

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

Parameters	Description
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: callId)

Parameters	Description
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

Callkit in client requires below API calls from SDK

Initialize Audio Unit

This API call allows users to manually initilize Audio Unit while using CallKit. User need to call this before starting / joining the call.

Rtc555Voice.initilizeManualAudio(audioManual: Bool)

Parameters	Type	Description
audioManual	Bool	Pass Yes to initilize Audio unit Manually

Activate/Deactive Audio Unit

This API is only effective if initilizeManualAudio is YES. This API call allows users to activate / deactivate audio while using callkit. Need to call this API in provider(:didActivate:) delegate and provider(:didDeactivate:) delegate.

Rtc555Voice.enableAudio(enableAudio: Bool)

//Usage :: Callkit delegates
func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
    Rtc555Voice.enableAudio(enableAudio: false)
}

func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
    Rtc555Voice.enableAudio(enableAudio: true)
}

Parameters	Type	Description
enableAudio	Bool	Pass Yes or No to start /stop Audio unit

On-call Features

Features offered by iOS 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: 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(callId: 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(callId: callId)

Parameters	Description
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: 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: callId, dtmfTone: DtmfInputType)

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(activeCallId: callId, heldCallId: callId){ result in
            switch result {
            case .success():
                print("success")
            case .failure(let error):
                print(error)
            }
        }

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

Call Delegates

To get call status or error report during the call, Rtc555VoiceDelegate is passed to the dial/accept API call. This delegate provide below callbacks.

onStatus

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

    func onStatus(status callStatus: CallStatus,id callId:String) {
         
     }

Parameters	Description
callStatus	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 oh hold

onError

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

    func onError(error errorInfo: Error,id callId:String) {
         
     }

Parameters	Description
errorInfo	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".

func onCallStats(callQuality: Int, bitrate: String, id callId: String) {
        print("Rtc555SdkTests :: callQuality: \(callQuality)")
    }

Parameters
callQuality	call quality of ongoing call as integer value
bitrate	Transmit bitrate of ongoing call as string value
callId	callId received from backend

onNotification

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

    @objc func onNotification(notification notificationData: [AnyHashable : Any]) {

    }

Parameters	Description
notificationData	notification payload for incoming notification

Platform

IOS SDK

Android SDK

IOS SDK

Android SDK

React Native SDK

SDK initialization

Adding SDK configuration.

Initiating an Outgoing Call

Initiating an Outgoing Call with Voice options

Initiating 911 Call

Initiating an Emergency Call

Accept/Reject an Incoming Call

Accept Call

Reject Call

End an Active Call

Clean up the session.

Callkit Support

Initialize Audio Unit

Activate/Deactive Audio Unit

On-call Features

Hold Call

Unhold Call

Mute Local Audio

Unmute Local Audio

Send DTMF Tone

Merge Call

Call Delegates

onStatus

onError

onCallStats

onNotification