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