Voice Calling
iOS
Android
Configure your Xcode project for outgoing calls.
- In your app's
info.plist
, add theNSMicrophoneUsageDescription
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
, andRemote Notifications
- Add the
Push Notifications
capability.
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. **
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
Kotlin
let localNumber: PhoneNumber!
let remoteNumber = "2024561414"
let delegate: ActiveCallDelegate
try! telephonyClient.createVoiceCall(localNumber: localNumber, remoteNumber: remoteNumber, delegate: delegate)
val localNumber: PhoneNumber
val remoteNumber = "2024561414"
val listener: ActiveCallListener
telephonyClient.createVoiceCall(localNumber, remoteNumber, listener)
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 an
ActiveVoiceCall
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
Kotlin
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)
}
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)
}
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
Android
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 }
}
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()
}
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.
Retrieve a list of call records with a provided
PhoneNumber
and an optional limit and token for pagination:Swift
Kotlin
// 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
}
}
// 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 a
CallRecord
providing its ID.Swift
Kotlin
// callRecordId: String
try telephonyClient.getCallRecord(callRecordId: callRecordId) { (result) in
switch result {
case .success(let callRecord):
// callRecord: CallRecord
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// callRecordId: String
sudoTelephonyClient.calling.getCallRecord(callRecordId) { result ->
when (result) {
is Result.Success -> {
// result.value: CallRecord
}
is Result.Error -> {
// result.throwable: Throwable
}
}
}
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
Kotlin
let subscriptionToken = try telephonyClient.subscribeToCallRecords(resultHandler: { (result) in
switch result {
case .success(let callRecord):
// callRecord: CallRecord
case .failure(let error):
// error: SudoTelephonyClientError
}
})
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 a
CallRecord
providing its ID.Swift
Kotlin
// callRecordId: String
try telephonyClient.deleteCallRecord(id: callRecordId) { (result) in
switch result {
case .success(let deletedId):
// deletedId: String
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// callRecordId: String
sudoTelephonyClient.calling.deleteCallRecord(callRecordId) { result ->
when (result) {
is Result.Success -> {
// result.value: String (callRecordId)
}
is Result.Error -> {
// result.throwable: Throwable
}
}
}
A
CallRecord
contains all the information for a voice call made or received.Swift
Kotlin
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?
}
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
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.
Retrieve a list of voicemail records with a provided
PhoneNumber
and an optional limit and token for pagination:Swift
Kotlin
// 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
}
}
// 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 a
Voicemail
by its ID.Swift
Kotlin
// voicemailId: String
telephonyClient.getVoicemail(id: voicemailId) { (result) in
switch result {
case .success(let voicemail):
// voicemail: Voicemail
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// voicemailId: String
sudoTelephonyClient.calling.getVoicemail(voicemailId) { result ->
when (result) {
is Result.Success -> {
// result.value: Voicemail
}
is Result.Error -> {
// result.throwable: Throwable
}
}
}
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
Kotlin
let subscriptionToken = try telephonyClient.subscribeToVoicemails(resultHandler: { (result) in
switch result {
case .success(let voicemail):
// voicemail: Voicemail
case .failure(let error):
// error: SudoTelephonyClientError
}
})
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
Kotlin
// voicemailId: String
try telephonyClient.deleteVoicemail(id: voicemailId) { (result) in
switch result {
case .success:
// successfully deleted
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// voicemailId: String
sudoTelephonyClient.calling.deleteVoicemail(voicemailId) { result ->
when (result) {
is Result.Success -> {
// result.value: String (voicemailId)
}
is Result.Error -> {
// result.throwable: Throwable
}
}
}
A
Voicemail
contains all the information for a voicemail recording.Swift
Kotlin
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
}
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
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
Kotlin
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
}
}
// voicemail: Voicemail
sudoTelephonyClient.downloadData(voicemail.media) { result ->
when (result) {
is Result.Success -> {
// result.value: ByteArray
}
is Result.Error -> {
// result.throwable: Throwable
}
}
}
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
Kotlin
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
}
val callRecord: CallRecord
callRecord.voicemail?.let { voicemailData ->
// The call record has associated voicemail data.
// voicemailData.id: String
// voicemailData.durationSeconds: Int
// voicemailData.media: MediaObject
}
The
Voicemail
record also has an optional callRecordId
property which relates the voicemail to its call record if the call record has not been deleted.Last modified 1yr ago