Voice calling (iOS SDK)

​

Installation

// Pre-1.0: breaking changes bump the MINOR version, so pin to next-minor.
.package(url: "https://github.com/polyai/ios-sdk.git", .upToNextMinor(from: "0.9.0"))

// target dependencies (the package identity is the repo name, `ios-sdk`):
.product(name: "PolyMessaging", package: "ios-sdk")
.product(name: "PolyVoice", package: "ios-sdk")

pod 'PolyVoice', '~> 0.9.0'   # chat-only apps use `pod 'PolyMessaging', '~> 0.9.0'` instead

​

Quickstart

import PolyMessaging
import PolyVoice

let call = try PolyVoice.call(
    config: Configuration(apiKey: "YOUR_CONNECTOR_TOKEN"),        // connector token — Agent Studio › Connector Settings
    options: VoiceOptions(webrtcToken: "YOUR_WEB_CALLING_TOKEN")  // web calling token — same page, a distinct value
)   // throws PolyError.invalidConfiguration on a blank token, or a .custom environment without signalingHost

// Observe the lifecycle: .idle → .connecting → .connected → .ended / .failed
Task { for await state in call.states { render(state) } }

try await call.start()   // after the microphone permission is granted
await call.setMuted(true)
await call.end()

​

Credentials

​

Microphone permission

​

Backgrounding

<key>UIBackgroundModes</key>
<array><string>audio</string></array>

​

Audio routing

Task { for await snapshot in call.audioStates {
    show(current: snapshot.selectedDevice)      // e.g. "Output: AirPods"
} }

// speaker ↔ earpiece — the entries come from snapshot.availableDevices
await call.setAudioDevice(speakerDevice)    // .kind == .speakerphone
await call.setAudioDevice(earpieceDevice)   // .kind == .earpiece
let muted = await call.isMuted

​

CallKit

func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
    PolyVoice.callKitConfigureAudioSession() // configure EARLY — never self-activate
    Task { try? await call.start() }
    action.fulfill()
    provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: nil)
}
func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
    PolyVoice.callKitAudioSessionDidActivate(audioSession)   // audio starts HERE
}
func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
    PolyVoice.callKitAudioSessionDidDeactivate(audioSession)
}

• Declare the voip background mode (alongside audio) in UIBackgroundModes. Without it every CXCallController transaction is refused (com.apple.CallKit.error.requesttransaction Code=1) and the call never starts.
• Request, don’t command: start / end / mute go through CXCallController actions and are executed in the matching perform callback, so the system can arbitrate and the system UI stays in sync. Remote endings (the agent hangs up, a failure) are reported via reportCall(with:endedAt:reason:) instead.
• Never call AVAudioSession.setActive(true) during a CallKit call — a self-activated session blocks CallKit’s elevated activation and didActivate never fires (the classic “call connects, no audio” bug).
• System interruptions move to CallKit: a cellular call arrives as a hold action plus didDeactivate, not as the SDK’s interruption handling. After the interrupting call ends, iOS may not resume you automatically — offer a manual un-hold path.
• Simulator: CallKit is broken there (iOS 17+ auto-ends calls). Gate on targetEnvironment(simulator) and fall back to a plain call.
• China: Apple rejects CallKit UI for the Chinese App Store. Keep callKit: behind a region or remote-config gate if you ship there.

​

Resilience

• Connectivity: STUN/TURN servers are fetched from the gateway per call, so calls connect behind symmetric NAT / CGNAT (falls back to public STUN if the fetch fails).
• Reconnect: a dropped signaling socket reconnects automatically (backoff 1s / 2s / 4s) on the same session before the call is failed.
• Interruptions: an incoming phone call or Siri mutes the mic and restores it; a non-resumable interruption ends the call as PolyError.voice(.interrupted).
• Retryable errors: a post-connect drop surfaces as PolyError.voice(.disconnected). Both it and .interrupted are isRetryable, so you can offer a one-tap retry.

​

Troubleshooting

​

Architecture

​

Example apps

• Examples/SwiftUI/Voice/01-Hello
• Examples/UIKit/Voice/01-Hello

​

Related pages