ConnectionService Implementation for Android (System Calls Integration)
Most VoIP apps on Android work via custom UI: custom call screen on top, system phone unaware. Works — until user expects call from your app behaves normally: displays on lock screen, pauses music via audio focus, visible in system call log, compatible with Bluetooth headset and Android Auto.
Exactly for this ConnectionService exists — component of Telecom Framework letting app register as full phone provider in Android system. Implementation non-trivial: API requires precise Connection lifecycle following, work with PhoneAccount, handling system events like DTMF and audio routing.
What ConnectionService Actually Implements
ConnectionService — abstract class from android.telecom package. App inherits and registers implementation in manifest as <service> with permission android.permission.BIND_TELECOM_CONNECTION_SERVICE. System Telecom calls service callbacks on incoming/outgoing calls.
Central object — Connection. For each call create own Connection instance with states:
NEW → DIALING → RINGING → ACTIVE → HOLDING → DISCONNECTED
Each transition — explicit method call: setDialing(), setRinging(), setActive(), setOnHold(), setDisconnected(DisconnectCause). If transition not called — system considers call hung. This most common error in first implementations: VoIP stack gets server answer but Connection stays DIALING forever.
PhoneAccount — provider identifier in system. Registered via TelecomManager.registerPhoneAccount(). Requires icon, label, supported URI schemes (tel, sip or custom), capability flags (CAPABILITY_CALL_PROVIDER, CAPABILITY_VIDEO_CALLING etc.).
User must explicitly enable PhoneAccount in system settings — app can't do auto. First run requires navigation to Settings → Apps → [App] → Phone accounts. This UX moment needs separate design.
Where Most Implementations Break
Audio Routing
When Connection transitions to ACTIVE, system expects app takes audio focus and configures sound routing. Via AudioManager.requestAudioFocus() with AudioFocusRequest (API 26+) or AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE. Without this other apps (music player, navigator) don't get pause signal.
Switching between speaker, headphones, Bluetooth — via ConnectionService.onCallAudioStateChanged(). System passes CallAudioState with current route and bitmask available routes. App must sync its state with system. Common error — app changes route via AudioManager directly, ignoring CallAudioState, and system shows wrong button state.
Incoming Call on Locked Screen
Incoming call initiated via TelecomManager.addNewIncomingCall() must come with IncomingCallUi — either system call screen or custom Activity with flags FLAG_SHOW_WHEN_LOCKED | FLAG_TURN_SCREEN_ON | FLAG_KEEP_SCREEN_ON. From API 27 use setShowWhenLocked(true) and setTurnScreenOn(true) on Activity.
Notification from API 31 requires Notification.CallStyle.forIncomingCall() — without this system might not show full-screen intent on some devices. On Samsung One UI behavior differs from AOSP: full-screen intent sometimes ignored for system notification shade.
Hold and Conferences
CAPABILITY_HOLD on Connection means call can be put on hold. But if VoIP backend doesn't support hold via SIP re-INVITE with a=sendonly — remove capability, otherwise system sends onHold() but app can't execute. Conference via Conference object — separate complexity level: managing participants, merge, swap.
Android Auto and WearOS
ConnectionService auto-integrates with Android Auto — vehicle system interface shows call card. But if app overrides audio routing directly, this conflicts with Bluetooth HFP profiles. Testing in Android Auto emulator mandatory.
Permissions and Limitations
READ_PHONE_STATE — get phone state. MANAGE_OWN_CALLS — if app manages calls without registering as full provider (simplified mode, no system log integration). RECORD_AUDIO — microphone capture. From Android 10+ extra limits on background Activity launch — full-screen intent requires USE_FULL_SCREEN_INTENT permission, from API 34 requires explicit user permission.
On custom ROMs (MIUI, One UI, ColorOS) TelecomManager behavior differs from AOSP. Emulator testing insufficient — need real Xiaomi, Samsung, OPPO devices.
Process and Timeline
Implementation includes: architecture design (how VoIP stack signals calls to ConnectionService), Connection lifecycle implementation, UI integration, audio routing testing on multiple devices.
Integration depends on existing VoIP stack: if using ready SIP stack (LinphoneSDK, PJSIP via Android wrapper, WebRTC via Google libwebrtc), translate its events to Connection transitions. If stack develops from scratch — timelines grow substantially.
Estimate: 2-3 weeks for basic incoming/outgoing calls with system UI, 4-6 weeks for full functionality with hold, conference, DTMF, Android Auto. Cost — after existing VoIP stack and requirements analysis.