Voice Calling

Voice Calling Setup

iOS

Configure your Xcode project for outgoing calls.

• In your app's info.plist, add the NSMicrophoneUsageDescription key. This is required to request microphone permission.

• In your app's capabilities, add the background mode capabilities Audio, Airplay, and Picture in Picture ,Voice over IP, and Remote Notifications

• Add the Push Notifications capability.

Android

Configure your Android application for outgoing calls.

• Add the following to your Android Manifest file:

  <uses-permission android:name="android.permission.RECORD_AUDIO"/>

• Request microphone permissions from within your application code:

  ActivityCompat.requestPermissions(
      this, 
      arrayOf(Manifest.permission.RECORD_AUDIO), 
      MIC_PERMISSION_REQUEST_CODE // a code you set for monitoring whether or not the permission was granted
  )

Configure your Android application for incoming calls.

• Incoming calls take advantage of Firebase Cloud Messaging. To get started with Cloud Messaging follow the Firebase set up instructions here. **

Making an Outgoing Call

Outgoing calls are made using the createVoiceCall method. The active call is returned to the provided delegate or listener once it connects. During this time the call can be considered to be in progress.

Swift

let localNumber: PhoneNumber!
let remoteNumber = "2024561414"
let delegate: ActiveCallDelegate
try! telephonyClient.createVoiceCall(localNumber: localNumber, remoteNumber: remoteNumber, delegate: delegate)

Kotlin

val localNumber: PhoneNumber
val remoteNumber = "2024561414"
val listener: ActiveCallListener
telephonyClient.createVoiceCall(localNumber, remoteNumber, listener)

Interacting With an Active Call

The active call delegate (iOS) / listener (Android) must be provided when a call is created and is used to communicate active call events such as when the call connects, disconnects, or fails.

If a call connects successfully, the delegate/listener will be provided with anActiveVoiceCall object via the activeVoiceCallDidConnect method. This object provides functions for manipulating the call such as muting the microphone, ending the call, or switching the audio to speakerphone.

Swift

public protocol ActiveCallDelegate {

    /// Notifies the delegate that the call has connected
    /// - Parameters:
    ///     - call: The `ActiveVoiceCall`
    func activeVoiceCallDidConnect(_ call: ActiveVoiceCall)

    /// Notifies the delegate that the call failed to connect
    /// - Parameters:
    ///     - error: `CallingError` that occurred.
    func activeVoiceCallDidFailToConnect(withError error: CallingError)

    /// Notifies the delegate that the call has been disconnected
    /// - Parameters:
    ///     - call: The `ActiveVoiceCall`
    ///     - error: Error that caused the call to disconnect if one occurred.
    func activeVoiceCall(_ call: ActiveVoiceCall, didDisconnectWithError error: Error?)

    /// Notifies the delegate that the call has been muted or un-muted
    /// - Parameters:
    ///     - call: The `ActiveVoiceCall`
    ///     - isMuted: Whether outgoing call audio is muted
    func activeVoiceCall(_ call: ActiveVoiceCall, didChangeMuteState isMuted: Bool)

    /// Called when the system audio route has changed.
    /// Use `call.isOnSpeaker` to determine if the call is on speaker.
    ///
    /// - Parameter call: The `ActiveVoiceCall`
    func activeVoiceCallAudioRouteDidChange(_ call: ActiveVoiceCall)
}

Kotlin

interface ActiveCallListener : TelephonySubscriber {
    /**
     * Notifies the listener that the call has connected
     * @param call The `ActiveVoiceCall`
     */
    fun activeVoiceCallDidConnect(call: ActiveVoiceCall)

    /**
     * Notifies the listener that the call failed to connect
     * @param exception An Exception that occurred
     */
    fun activeVoiceCallDidFailToConnect(exception: Exception)

    /**
     * Notifies the listener that the call has been disconnected
     * @param call The `ActiveVoiceCall`
     * @param exception An optional Exception that is the cause of the disconnect if not null
     */
    fun activeVoiceCallDidDisconnect(call: ActiveVoiceCall, exception: Exception?)

    /**
     * Notifies the listener that the call has been muted or un-muted
     * @param call The `ActiveVoiceCall`
     * @param isMuted Whether outgoing call audio is muted
     */
    fun activeVoiceCallDidChangeMuteState(call: ActiveVoiceCall, isMuted: Boolean)

    /**
     * Notifies the listener that the call audio routing has changed
     * @param call The `ActiveVoiceCall`
     * @param audioDevice The `AudioDevice` that the audio has been routed to
     */
    fun activeVoiceCallDidChangeAudioDevice(call: ActiveVoiceCall, audioDevice: VoiceCallAudioDevice)
}

Receiving an Incoming Call

VOIP Notifications for Incoming Calls. Receiving incoming voice calls on iOS and Android devices requires APNS and FCM push credentials, respectively. If you would like to enable this functionality, contact your solutions engineer to assist you in configuring your environments with push credentials for your applications.

iOS

Subscribe to Incoming Calls

In AppDelegate.swift import PushKit and add a PKPushRegistry variable:

AppDelegate.swift

import PushKit
class AppDelegate: UIResponder, UIApplicationDelegate {
    // ...
    var pushRegistry: PKPushRegistry!
}

In the applicationDidFinishLaunchingWithOptions function set up the push registry:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...
    self.pushRegistry = PKPushRegistry(queue: nil)
    pushRegistry.delegate = self
    pushRegistry.desiredPushTypes = [.voIP]
    return true
}

Implement the PKPushRegistryDelegate methods to register, deregister and handle incoming call push notifications. When a push notification comes in, pass the payload from the voip push on to the SudoTelephonyClient along with an IncomingCallNotificationDelegate:

extension AppDelegate: PKPushRegistryDelegate {

    func pushRegistry(_ registry: PKPushRegistry, didUpdate pushCredentials: PKPushCredentials, for type: PKPushType) {
        try! self.telephonyClient.registerForIncomingCalls(with: pushCredentials.token, useSandbox: true, completion: { (error) in
            if let error = error {
                // Error updating push credentials
            }
            else {
                // Push credentials updated with telephony SDK
            }
        })
    }

    func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
        let _ = try! self.telephonyClient.handleIncomingPushNotificationPayload(payload.dictionaryPayload, notificationDelegate: self)
        completion()
    }

    func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) {
        try! self.telephonyClient.deregisterForIncomingCalls(completion: { (error) in
            if let error = error {
                // Error de-registering for push notifications
            } else {
                // Successfully de-registered
            }
        })
    }
}

IncomingCallNotificationDelegate:

public protocol IncomingCallNotificationDelegate: class {
    /// Called when an incoming call is recieved.  This is called before reporting the call to callkit so the correct
    /// display name can be provided.
    ///
    /// In your implementation of this function you should set the `displayName` property of the incoming call that should be displayed by callKit.
    ///
    /// You should also set the `delegate` of the incoming call.  When the call is answered, `incomingCallAnswered(_ call: ActiveVoiceCall)` will be called
    /// and future call related events will be delivered to the delegate.
    func incomingCallReceived(_ call: IncomingCall) -> Void

    /// Indicates that the incoming call was canceled.
    /// - Parameter call: The incoming call
    /// - Parameter error: The error that occured, if any.
    func incomingCall(_ call: IncomingCall, cancelledWithError error: Error?)


    /// An incoming call was answered through CallKit and is in the process of connecting.
    /// No more updates on the incoming call will be provided to this delegate.
    /// Future call updates will be provided to the delegate set on the incoming call delegate in `incomingCallReceived(_ call: IncomingCall) -> Void`.
    func incomingCallAnswered(_ call: ActiveVoiceCall)
}

When the incomingCallReceived() function is called, you can take the IncomingCall object and either accept the call or decline the call. The accept method takes an ActiveCallDelegate instance which will then handle all of the call events.

IncomingCall:

public protocol IncomingCall: class {

    /// When an incoming call is recieved the delegate should be set in order to get updates on call related events.
    /// For example if the call is answered through CallKit the delegate will recieve the call connected event with
    /// a handle to the call.
    var delegate: ActiveCallDelegate? { get set }

    /// The phone number receiving the call
    var localNumber: String { get }

    /// The phone number the call is coming from
    var remoteNumber: String { get }

    /// The UUID for the call
    var uuid: UUID { get }

    /// Accepts the call with a delegate to provide call lifecycle updates.
    func accept(with delegate: ActiveCallDelegate)

    /// Decline the call.
    func decline()

    /// The display name used by callKit when reporting a call
    var displayName: CallKitDisplayName? { get set }
}

Android

Subscribe to Incoming Calls

In order to receive calls you must first set up Firebase Cloud Messaging in your app. Instructions can be found here.

_**_Subscribe to incoming calls using the fcmToken provided by Firebase. The following code will fail if Google Play Services are not enabled on the device.

FirebaseInstanceId.getInstance().instanceId
    .addOnCompleteListener(OnCompleteListener { task ->
        if (!task.isSuccessful) {
            // failed to get instance id
            return@OnCompleteListener
        }

        val fcmToken = task.result!!.token
        sudoTelephonyClient.calling.registerForIncomingCalls(fcmToken) { result ->
            when (result) {
                is Result.Success -> {
                    // successfully registered
                }
                is Result.Error -> {
                    // failed to register
                }
            }
        }
    })

Handle Incoming Firebase Messages

When a message comes in from Firebase, pass it on to the SudoTelephonyClient along with an IncomingCallNotificationListener:

override fun onMessageReceived(message: RemoteMessage) {
    super.onMessageReceived(message)
    // listener: IncomingCallNotificationListener
    sudoTelephonyClient.calling.handleIncomingPushNotification(message.data, listener)
}

IncomingCallNotificationListener:

/**
 * Listener for receiving notifications about new `IncomingCall` events.
 */
interface IncomingCallNotificationListener: TelephonySubscriber {
    /**
     * Notifies the listener that the call was received
     * @param call The `IncomingCall`
     */
    fun incomingCallReceived(call: IncomingCall)

    /**
     * Notifies the listener that the call was canceled
     * @param call The `IncomingCall`
     */
    fun incomingCallCanceled(call: IncomingCall, error: Throwable?)
}

When the incomingCallReceived() function is called, you can take the IncomingCall object and either accept the call or decline the call. The accept method takes an ActiveCallListener instance which will then handle all of the call events.

IncomingCall:

class IncomingCall() {
    /**
     * The phone number receiving the call
     */
    var localNumber: String

    /**
     * The phone number the call is coming from
     */
    var remoteNumber: String

    /**
     * The unique string identifying the call invite
     */
    var callSid: String

    /**
     * Accepts the call
     * @param listener A listener to receive call lifecycle updates
     */
    fun acceptWithListener(listener: ActiveCallListener)

    /**
     * Declines the call
     */
    fun decline()
}

Manage Call Records

A call record is generated for each call made and received. The SDK provides three methods for accessing that data and one for deleting call records.

Get Call Records

Retrieve a list of call records with a provided PhoneNumber and an optional limit and token for pagination:

Swift

// localNumber: PhoneNumber
// nextToken: String
try telephonyClient.getCallRecords(localNumber: localNumber, limit: nil, nextToken: nextToken) { (result) in
    switch result {
    case .success(let listToken):
        // listToken: TelephonyListToken<CallRecord>
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// localNumber: PhoneNumber
// nextToken: String
sudoTelephonyClient.calling.getCallRecords(localNumber, null, nextToken) { result ->
    when (result) {
        is Result.Success -> {
            // result.value.items: List<CallRecord>
        }
        is Result.Absent -> {
            // no call records
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Get Call Record

Get a CallRecord providing its ID.

Swift

// callRecordId: String
try telephonyClient.getCallRecord(callRecordId: callRecordId) { (result) in
    switch result {
    case .success(let callRecord):
        // callRecord: CallRecord
    case .failure(let error):
        // error: SudoTelephonyClientError
    }  
}

Kotlin

// callRecordId: String
sudoTelephonyClient.calling.getCallRecord(callRecordId) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: CallRecord
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Subscribe To Call Records

Subscribe to CallRecord events and state changes. On iOS the subscribeToCallRecords() function returns a SubscriptionToken which can be used to cancel the subscription. On Android the function takes a CallRecordSubscriber instance which will receive CallRecord updates.

Swift

let subscriptionToken = try telephonyClient.subscribeToCallRecords(resultHandler: { (result) in
    switch result {
    case .success(let callRecord):
        // callRecord: CallRecord
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
})

Kotlin

sudoTelephonyClient.calling.subscribeToCallRecords(this, "CallRecordSubscriberId")



/**
 * Subscriber for receiving notifications about new `CallRecord` objects.
 */
interface CallRecordSubscriber : TelephonySubscriber {

    /**
     * Notifies the subscriber of a new 'CallRecord'.
     */
    fun callRecordReceived(callRecord: CallRecord)
}

Delete Call Record

Delete a CallRecord providing its ID.

Swift

// callRecordId: String
try telephonyClient.deleteCallRecord(id: callRecordId) { (result) in
    switch result {
    case .success(let deletedId):
        // deletedId: String
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// callRecordId: String
sudoTelephonyClient.calling.deleteCallRecord(callRecordId) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: String (callRecordId)
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Call Record

A CallRecord contains all the information for a voice call made or received.

Swift

public struct CallRecord {
    /// Enum that represents the direction of the call.
    public enum Direction {
        case inbound
        case outbound
        case unknown

        init(internalDirection: SudoTelephony.Direction) {
            switch internalDirection {
            case .inbound:
                self = .inbound
            case .outbound:
                self = .outbound
            case .unknown:
                self = .unknown
            }
        }
    }

    // Enum that represents the state of the call record.
    public enum State {
        case authorized
        case queued
        case ringing
        case answered
        case completed
        case unanswered
        case unknown

        init(internalState: CallState) {
            switch internalState {
            case .authorized:
                self = .authorized
            case .queued:
                self = .queued
            case .ringing:
                self = .ringing
            case .answered:
                self = .answered
            case .completed:
                self = .completed
            case .unanswered:
                self = .unanswered
            case .unknown:
                self = .unknown
            }
        }
    }

    /// Voicemail data belonging to a call record
    public struct VoicemailData {
        /// Unique ID of the voicemail record
        public let id: String
        /// The duration of the voicemail recording in seconds
        public let durationSeconds: UInt
        /// The media object that can be used to download the voicemail recording
        public let media: MediaObject
    }

    /// Unique ID of the call record
    public let id: String
    /// The user ID of the owner of the call record (also referred to as the subject)
    public let owner: String
    /// The ID of the sudo that made or received the call
    public let sudoOwner: String
    /// The ID of the `PhoneNumber` associated with the call record
    public let phoneNumberId: String
    /// The direction of the call. Either `outbound` or `inbound`
    public let direction: Direction
    /// The state of the call record
    public let state: State
    /// Timestamp that represents the last time the call was updated
    public let updated: Date
    /// Timestamp that represents the time the call was created
    public let created: Date
    /// The E164Number of the local phone number
    public let localPhoneNumber: String
    /// The E164Number of the remote phone number
    public let remotePhoneNumber: String
    /// The duration of the call in seconds
    public let durationSeconds: UInt32
    /// The voicemail data of this call record if it exists
    public let voicemail: VoicemailData?
}

Kotlin

data class CallRecord(
     /**
      * Unique ID of the call record
      */
     val id: String,
     /**
      * The user ID of the owner of the call record (also referred to as the subject)
      */
     val owner: String,
     /**
      * The ID of the sudo that made or received the call
      */
     val sudoOwner: String,
     /**
      * The ID of the `PhoneNumber` associated with the call record
      */
     val phoneNumberId: String,
     /**
      * The direction of the call. Either `outbound` or `inbound`
      */
     val direction: Direction,
     /**
      * The state of the call record
      */
     val state: CallRecordState,
     /**
      * Timestamp that represents the last time the call was updated
      */
     val updated: Instant,
     /**
      * Timestamp that represents the time the call was created
      */
     val created: Instant,
     /**
      * The E164Number of the local phone number
      */
     val localPhoneNumber: String,
     /**
      * The E164Number of the remote phone number
      */
     val remotePhoneNumber: String,
     /**
      * The duration of the call in seconds
      */
     val durationSeconds: Int,
     /**
      * The voicemail data of this call record if it exists
      */
     val voicemail: VoicemailData?

) : Parcelable

/**
 * Enum that represents the state of the call record.
 */
enum class CallRecordState() {
     AUTHORIZED,
     QUEUED,
     RINGING,
     ANSWERED,
     COMPLETED,
     UNANSWERED,
     UNKNOWN;
}

/**
 * Voicemail data belonging to a call record
 */
data class VoicemailData (
     /**
      * Unique ID of the voicemail record
      */
     val id: String,
     /**
      * The duration of the voicemail recording in seconds
      */
     val durationSeconds: Int,
     /**
      * The media object that can be used to download the voicemail recording
      */
     val media: MediaObject
) : Parcelable

Voicemail

When an incoming call is rejected or times out, the caller is sent to voicemail. After hearing a recorded greeting, the caller can record up to 3 minutes of voicemail. The SDK provides several methods to manage these stored voicemail recordings.

Get Voicemails

Retrieve a list of voicemail records with a provided PhoneNumber and an optional limit and token for pagination:

Swift

// localNumber: PhoneNumber
// nextToken: String
telephonyClient.getVoicemails(localNumber: localNumber, limit: nil, nextToken: nextToken) { (result) in
    switch result {
    case .success(let listToken):
        // listToken: TelephonyListToken<Voicemail>
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// localNumber: PhoneNumber
// nextToken: String
sudoTelephonyClient.calling.getVoicemails(localNumber, null, nextToken) { result ->
    when (result) {
        is Result.Success -> {
            // result.value.items: List<Voicemail>
        }
        is Result.Absent -> {
            // no voicemails
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Get Voicemail

Get a Voicemail by its ID.

Swift

// voicemailId: String
telephonyClient.getVoicemail(id: voicemailId) { (result) in
    switch result {
    case .success(let voicemail):
        // voicemail: Voicemail
    case .failure(let error):
        // error: SudoTelephonyClientError
    }  
}

Kotlin

// voicemailId: String
sudoTelephonyClient.calling.getVoicemail(voicemailId) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: Voicemail
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Subscribe To Voicemails

Subscribe to Voicemail create events, update events, and delete events. On iOS the subscribeToVoicemails() function returns a SubscriptionToken which can be used to cancel the subscription. On Android the function takes a VoicemailSubscriber instance which will receive Voicemail events.

Swift

let subscriptionToken = try telephonyClient.subscribeToVoicemails(resultHandler: { (result) in
    switch result {
    case .success(let voicemail):
        // voicemail: Voicemail
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
})

Kotlin

sudoTelephonyClient.calling.subscribeToVoicemails(this, "VoicemailSubscriberId")



/**
 * Subscriber for receiving notifications about new `Voicemail` updates.
 */
interface VoicemailSubscriber : TelephonySubscriber {

    /**
     * Notifies the subscriber of a new 'Voicemail' update.
     */
    fun voicemailUpdated(voicemail: Voicemail)
}

Delete Voicemail

Delete a Voicemail by its ID.

Swift

// voicemailId: String
try telephonyClient.deleteVoicemail(id: voicemailId) { (result) in
    switch result {
    case .success:
        // successfully deleted
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// voicemailId: String
sudoTelephonyClient.calling.deleteVoicemail(voicemailId) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: String (voicemailId)
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Voicemail Record

A Voicemail contains all the information for a voicemail recording.

Swift

public struct Voicemail {
    /// Unique ID of the voicemail record
    public let id: String
    /// The ID of the Sudo Platform user that owns the voicemail.
    public let owner: String
    /// The ID of the Sudo that received the voicemail.
    public let sudoOwner: String
    /// The ID of the `PhoneNumber` associated with the voicemail.
    public let phoneNumberId: String
    /// The ID of the `CallRecord` associated with the voicemail.
    public let callRecordId: String?
    /// Timestamp that represents the time the voicemail was created.
    public let created: Date
    /// Timestamp that represents the last time the voicemail was updated.
    public let updated: Date
    /// The E.164 formatted phone number that received the voicemail.
    public let localPhoneNumber: String
    /// The E.164 formatted phone number of the caller.
    public let remotePhoneNumber: String
    /// The duration of the voicemail recording in seconds.
    public let durationSeconds: UInt
    /// The media object that can be used to download the voicemail recording.
    public let media: MediaObject
}

Kotlin

data class Voicemail(
    /**
     * Unique ID of the voicemail record
     */
    val id: String,
    /**
     * The ID of the Sudo Platform user that owns the voicemail.
     */
    val owner: String,
    /**
     * The ID of the Sudo that received the voicemail.
     */
    val sudoOwner: String,
    /**
     * The ID of the `PhoneNumber` associated with the voicemail.
     */
    var phoneNumberId: String,
    /**
     * The ID of the `CallRecord` associated with the voicemail.
     */
    var callRecordId: String?,
    /**
     * Timestamp that represents the time the voicemail was created.
     */
    val created: Instant,
    /**
     * Timestamp that represents the last time the voicemail was updated.
     */
    val updated: Instant,
    /**
     * The E.164 formatted phone number that received the voicemail.
     */
    val localPhoneNumber: String,
    /**
     * The E.164 formatted phone number of the caller.
     */
    val remotePhoneNumber: String,
    /**
     * The duration of the voicemail recording in seconds.
     */
    val durationSeconds: Int,
    /**
     * The media object that can be used to download the voicemail recording.
     */
    val media: MediaObject
) : Parcelable

Downloading Voicemail Audio Data

When voicemail records are retrieved, the audio data is not automatically downloaded. This gives you control over performance when retrieving voicemail records, particularly those with long recordings.

To download voicemail audio data, use the downloadData() method, passing it a MediaObject which can be retrieved from the media property of a Voicemail. This method returns the raw audio data.

Swift

import AVFoundation

let voicemail: Voicemail
telephonyClient.downloadData(for: voicemail.media) { (result) in
    switch result {
    case .success(let data):
        let audioPlayer = try! AVAudioPlayer(data: data)
        audioPlayer.play()
    case .failure(let error):
        // error: SudoTelephonyClientError
    }
}

Kotlin

// voicemail: Voicemail
sudoTelephonyClient.downloadData(voicemail.media) { result ->
    when (result) {
        is Result.Success -> {
            // result.value: ByteArray                   
        }
        is Result.Error -> {
            // result.throwable: Throwable
        }
    }
}

Associating Voicemail Records with Call Records

Voicemail records and call records can be managed independently. However, a call record that has a corresponding voicemail has an additional voicemail property containing a copy of the voicemail data. When said voicemail is deleted this copy is also deleted.

Swift

let callRecord: CallRecord
if let voicemailData: CallRecord.VoicemailData = callRecord.voicemail {
    // The call record has associated voicemail data.
    // voicemailData.id: String
    // voicemailData.durationSeconds: UInt
    // voicemailData.media: MediaObject
}

Kotlin

val callRecord: CallRecord
callRecord.voicemail?.let { voicemailData ->
    // The call record has associated voicemail data.
    // voicemailData.id: String
    // voicemailData.durationSeconds: Int
    // voicemailData.media: MediaObject
}

The Voicemailrecord also has an optional callRecordId property which relates the voicemail to its call record if the call record has not been deleted.