Implementing ConnectionService in Android: Native Call Integration

We often see VoIP apps struggling with the system: custom call screen, audio focus issues, missing Bluetooth integration. Users expect app calls to behave like regular calls — appear on the lock screen, pause music, and appear in the call log. This is exactly what ConnectionService — a component of Android Telecom Framework — provides. It allows your app to become a full-fledged phone provider. Implementation requires precise adherence to the Connection lifecycle and working with PhoneAccount. In this article, we share experience from over 50 projects and explain how to avoid common pitfalls.

80% of users expect native call behavior — system screen, auto-pause music, history recording. Without ConnectionService, you have to implement all this manually, and each device manufacturer (Samsung, Xiaomi, OPPO) adds its own quirks. We tested integration on 30+ real devices and identified 5 typical problems that our approach solves.

How ConnectionService Works

ConnectionService is an abstract class from the android.telecom package. Your app inherits from it and registers the implementation in the manifest as a <service> with permission android.permission.BIND_TELECOM_CONNECTION_SERVICE. The Telecom system calls the service callbacks for incoming and outgoing calls.

The central object is Connection. For each call, a separate Connection instance is created with a set of states:

NEW → DIALING → RINGING → ACTIVE → HOLDING → DISCONNECTED

Each transition requires an explicit call to the corresponding method: setDialing(), setRinging(), setActive(), setOnHold(), setDisconnected(DisconnectCause). If a transition is not invoked, the system considers the call stuck. This is one of the most common mistakes in initial implementations: the VoIP stack receives the server response, but the Connection remains in DIALING forever.

PhoneAccount — the provider identifier in the system. It is registered via TelecomManager.registerPhoneAccount(). It requires an icon, label, supported URI schemes (tel, sip, or custom), and capability flags (CAPABILITY_CALL_PROVIDER, CAPABILITY_VIDEO_CALLING, etc.).

The user must explicitly enable the PhoneAccount in system settings — the app cannot do this automatically. The first launch requires navigating to Settings → Apps → [App] → Phone accounts. This is a UX aspect that needs separate design.

Why Audio Focus Is Critical

Note: when Connection transitions to ACTIVE, the system expects the app to take audio focus and configure audio routing. This is done via AudioManager.requestAudioFocus() with AudioFocusRequest (API 26+) or AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE. Without this, other apps (music player, navigation) won't receive a pause signal.

Switching between speaker, headphones, and Bluetooth — via ConnectionService.onCallAudioStateChanged(). The system passes CallAudioState with the current route and a bitmask of available routes. The app must synchronize its state with the system. A common mistake is that the app changes the route directly via AudioManager, ignoring CallAudioState, and the system shows incorrect button states in the system UI.

Where Most Implementations Break

Incoming Call on Lock Screen

An incoming call initiated by the app via TelecomManager.addNewIncomingCall() must be accompanied by an IncomingCallUi — either the system call screen or a 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 the Activity.

For incoming call notifications from API 31, Notification.CallStyle.forIncomingCall() is required — without it, the system might not show a full-screen intent on some devices. On Samsung One UI, behavior differs from AOSP: the full-screen intent is sometimes ignored in favor of the system notification shade.

Hold and Conference

CAPABILITY_HOLD on Connection means the call can be put on hold. But if the VoIP backend does not support hold via SIP re-INVITE with a=sendonly — the capability must be removed, otherwise the system will send onHold(), and the app will be unable to execute it. Conference via the Conference object is a separate complexity: managing participants, merge, swap.

Android Auto and WearOS

ConnectionService automatically integrates with Android Auto — the in-car system interface will show a call card. But if the app overrides audio routing directly, it conflicts with HFP Bluetooth profiles. Testing in the Android Auto emulator is mandatory.

How to Implement ConnectionService in 5 Steps

1. Create a class extending ConnectionService. Implement methods onCreate(), onBind(), onCreateOutgoingConnection(), onCreateIncomingConnection().
2. Register the service in AndroidManifest.xml with permission BIND_TELECOM_CONNECTION_SERVICE and intent-filter for android.telecom.ConnectionService.
3. Create and register a PhoneAccount via TelecomManager. Specify icon, label, URI schemes, and flags.
4. Implement the Connection lifecycle: handle all states, DTMF, hold.
5. Handle audio focus and routing: request audio focus when ACTIVE, react to CallAudioState.

Permissions and Limitations

On devices with custom skins (MIUI, One UI, ColorOS), TelecomManager behavior differs from AOSP. Testing only on emulator is insufficient — real Xiaomi, Samsung, OPPO devices are needed.

Case Study: Medical Consultation App

Recently we integrated ConnectionService for a medical consultation app. The problem: incoming calls were not displayed on the lock screen, causing doctors to miss important calls. The reason was incorrect use of IncomingCallUi and missing setShowWhenLocked. We added an Activity with flags and replaced the ordinary notification with Notification.CallStyle. As a result, call response time decreased by 40%, and missed calls were halved. Importantly, we configured audio focus for exclusive capture — now music automatically pauses. ConnectionService accelerates integration by 3x compared to custom UI.

Process and Timeline

ConnectionService implementation includes several stages: architecture design (how the VoIP stack signals calls to ConnectionService), implementation of the Connection lifecycle, UI integration, audio routing testing on multiple devices.

Integration depends on the existing VoIP stack: if using a ready-made SIP stack (LinphoneSDK, PJSIP via Android wrapper, WebRTC via Google's libwebrtc), its events need to be translated into Connection transitions. If the stack is being developed from scratch, timelines increase significantly.

Estimation: 2-3 weeks for basic integration of incoming/outgoing calls with system UI, 4-6 weeks for full functionality with hold, conference, DTMF, Android Auto. Cost is calculated individually after analyzing the existing VoIP stack and requirements.

What's Included

• ConnectionService implementation supporting incoming and outgoing calls
• PhoneAccount registration with URI scheme configuration
• Audio focus and routing handling (speaker, Bluetooth, headphones)
• Integration with system call log
• Testing on 5+ real devices (Samsung, Xiaomi, OPPO, Pixel)
• Operations documentation and 2 weeks post-delivery support

Contact us for a free project assessment. Order a turnkey integration — get a ready-to-use solution with a guarantee of functionality.

For more details, see official documentation: Android Developer Docs — Android Telecom Framework.

Why is native Android development with Kotlin the production standard?

RecyclerView with DiffUtil.calculateDiff() on main thread, a list of 500 items, an average older Android phone – the user gets 200–400 ms freezes on every data update. Move the diff calculation to a background thread via AsyncListDiffer – the problem disappears. These things aren't obvious without a profiler and understanding Android’s threading model. According to Wikipedia (Android development), improper threading is one of the top causes of ANRs. We encounter such pitfalls daily, so our team bakes profiling and optimization into every sprint. One day of downtime due to ANR can cost an app with 100 000 DAU significant revenue losses – refactoring threading pays off within a week.

Kotlin + Jetpack Compose + Coroutines is the current production standard for native Android development. XML and View system haven’t disappeared, but we start new projects only with Compose. The result: fewer bugs, faster iterations, 30% less code compared to the classic approach. Want to estimate savings on your project? Contact us – we’ll do a free code audit within half a day.

How does recomposition work in Jetpack Compose and why is it important?

Compose is a declarative UI framework. Instead of TextView.setText() and adapter.notifyItemChanged() – composable functions that describe UI as a function of state. When state changes, Compose recomputes only the affected parts of the tree. This is called recomposition.

Problem: recomposition can be too frequent. If you pass a lambda created on every recomposition of the parent to a composable, the child composable will recompose every time, even if the visible data hasn’t changed.

// Bad – new lambda on each recomposition, child component thinks parameter changed
@Composable
fun ParentScreen(viewModel: MyViewModel = hiltViewModel()) {
    val items by viewModel.items.collectAsState()
    ItemList(
        items = items,
        onItemClick = { id -> viewModel.selectItem(id) } // created anew each time
    )
}

// Good – remember stabilizes the lambda
@Composable
fun ParentScreen(viewModel: MyViewModel = hiltViewModel()) {
    val items by viewModel.items.collectAsState()
    val onItemClick = remember { { id: String -> viewModel.selectItem(id) } }
    ItemList(items = items, onItemClick = onItemClick)
}

Stability and @Stable/@Immutable

Compose determines whether to recompose a composable by checking the stability of parameters. A type is considered stable if Compose can guarantee: if two values are equal by equals(), their UI representation is the same.

Primitives, String, data classes with val fields of stable types are automatically stable. List<T> is unstable because it’s an interface. MutableList can change without notification. Solution: use ImmutableList from kotlinx.collections.immutable or annotate a data class with @Immutable.

// List<Item> is unstable – LazyColumn will recompose excessively
@Composable
fun ItemList(items: List<Item>) { ... }

// ImmutableList is stable – Compose skips recomposition if items haven't changed
@Composable
fun ItemList(items: ImmutableList<Item>) { ... }

For diagnosing recomposition issues we use Compose Compiler Metrics. Add flags -P plugin:androidx.compose.compiler.plugins.kotlin:reportsDestination=... to build.gradle and get a report: which composables are restartable, which are skippable, why a parameter is unstable.

LazyColumn and list performance

LazyColumn is the RecyclerView equivalent in Compose. key in items { } is mandatory for any list where items can move or be deleted. Without key, Compose cannot distinguish moving an item from deleting one and adding another, breaking animations and potentially causing unexpected cell state reset.

LazyColumn {
    items(
        items = messages,
        key = { message -> message.id } // stable identifier
    ) { message ->
        MessageItem(message = message)
    }
}

contentType is an additional optimization. With multiple cell types, Compose can reuse composition for cells of the same type. It’s analogous to getItemViewType in RecyclerView.

How to avoid common mistakes when using coroutines?

Coroutines are structured concurrency with a clear scope and lifecycle.

viewModelScope is a coroutine scope tied to the ViewModel lifecycle. When the ViewModel is cleared (onCleared()), all coroutines in the scope are automatically cancelled. This eliminates a whole class of leaks typical for callback-based approaches.

@HiltViewModel
class OrderViewModel @Inject constructor(
    private val orderRepository: OrderRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow<OrderUiState>(OrderUiState.Loading)
    val uiState: StateFlow<OrderUiState> = _uiState.asStateFlow()

    fun loadOrder(orderId: String) {
        viewModelScope.launch {
            _uiState.value = OrderUiState.Loading
            try {
                val order = orderRepository.getOrder(orderId) // suspend function
                _uiState.value = OrderUiState.Success(order)
            } catch (e: IOException) {
                _uiState.value = OrderUiState.Error(e.message)
            }
        }
    }
}

What to choose: StateFlow or LiveData?

StateFlow and SharedFlow are the recommended replacements for LiveData in Kotlin projects. LiveData is lifecycle-aware but tied to the Android platform. Flow is pure Kotlin, testable without Android dependencies.

collectAsState() in Compose subscribes to StateFlow and triggers recomposition on new value. lifecycleScope.launch { flow.collect { } } is for collection in Fragment or Activity with lifecycle awareness via repeatOnLifecycle(Lifecycle.State.STARTED).

repeatOnLifecycle is important. Without it, the flow will be collected even when the app is in the background, potentially causing UI event processing when the window is not active. Apps that ignore this see up to 40% more battery drain and missed UI updates.

Dispatchers and structured concurrency

Dispatchers.IO for network requests and file operations. Dispatchers.Default for CPU-intensive tasks (parsing, sorting, encryption). Dispatchers.Main for UI.

withContext(Dispatchers.IO) switches the coroutine to the appropriate dispatcher without creating a new scope. This is more efficient than launch(Dispatchers.IO) inside another launch.

// Correct pattern in Repository
suspend fun getOrders(): List<Order> = withContext(Dispatchers.IO) {
    orderDao.getAll() // Room automatically suspend, but explicit IO dispatcher is good practice
}

Hilt and dependency injection

Hilt is the official DI framework for Android built on top of Dagger 2. It eliminates Dagger boilerplate: no need to write Component and manually connect Module with Component.

@HiltViewModel + @Inject constructor – ViewModel with dependency injection without factories. @Singleton, @ActivityScoped, @ViewModelScoped – proper lifecycle for dependencies.

A common mistake: using @Singleton for a repository that holds an Activity context. This leaks the Activity. Rule: @Singleton only for dependencies that need Application context or don’t store Android-specific state.

Want to implement DI without headaches? Contact us – we’ll set up Hilt within an hour on any existing project.

WorkManager and background tasks

WorkManager for guaranteed background tasks that must execute even after app or device restart. Data sync, analytics upload, file downloads.

CoroutineWorker is the suspend version of Worker. It runs on Dispatchers.IO by default.

Android 14 tightened background execution requirements. FOREGROUND_SERVICE_TYPE is mandatory for foreground services. WorkManager correctly handles constraints (network, charging) and doesn’t require foreground service for most tasks.

Tools

Android Studio Profiler – CPU profiler with System Trace shows everything: coroutine suspension points, RenderThread, MainThread. Memory profiler – heap dump, allocation tracking. Network profiler – all HTTP requests with bodies.

Compose Layout Inspector – composable tree with recomposition counts. Shows which composables recompose too often – more precise than any logging.

LeakCanary – automatic memory leak detection in development builds. Shows reference chain to the leak. Added with one dependency, works without configuration.

Firebase Crashlytics + Performance Monitoring – crash-free rate by version, network request traces, custom traces for critical operations.

What’s included in native Android development: our process

1. Requirements audit and architecture design – diagrams, stack selection, prototype.
2. Implementation with Kotlin + Jetpack Compose – StateFlow, Hilt, Coroutines, Navigation.
3. Backend integration – REST/GraphQL, WebSocket, push notifications (FCM), Android App Links.
4. Testing – unit tests (JUnit, MockK) with 85%+ coverage, UI tests (Compose Test), load testing.
5. CI/CD – GitHub Actions / GitLab CI with automated builds, linters, and publication to Google Play Console.
6. Documentation – README, ADR (Architecture Decision Records), code comments.
7. Post-release support – monitoring, crashlytics, hotfixes, updates.
8. Code warranty – 3 months of free support after delivery.

From real projects we’ve seen: missing key in LazyColumn causes broken animations and binding resets; @Singleton repository with Activity context leads to memory leaks; flows collected without repeatOnLifecycle process events in background; using Dispatchers.Main for IO results in ANR; unstable types in Compose cause excessive list recomposition; manual cache management without Room or DataStore creates chaos. After refactoring these issues, clients report a 40% reduction in crash rate within the first month, and API response time drops from 1200 ms to 400 ms due to proper dispatcher handling and caching.

Timelines

Cost is calculated after requirements analysis and specification. Estimate is free. Get a consultation – we’ll prepare a detailed commercial proposal with stage breakdown.

Why trust us

5+ years on the market, 70+ completed Android projects (from startups to enterprise). Our team includes a Lead Android Developer with experience at Google and Associate Android Developer certification. All projects undergo Code Review with Checkstyle and Detekt, ensuring code quality. For production builds, we use ProGuard/R8 with custom shrink rules, reducing APK size by 25–35% without loss of functionality. With us you get a predictable result – contact us to see how your app can improve.