◉ Ringlr

Introduction

Ringlr is a Kotlin Multiplatform Mobile (KMM) library that gives you a single, consistent API for placing, receiving, and managing phone calls on both Android and iOS.

Under the hood it bridges Android's Telecom framework and iOS's CallKit, so your shared call logic never forks into platform-specific branches.

Features

Architecture

Ringlr follows the KMM expect/actual pattern. The shared module declares expect class CallManager and expect class PlatformConfiguration; each platform provides its actual implementation.

Setup

Ringlr is currently distributed as a local Gradle module. Maven Central publishing is coming soon.

1. Clone the repository

git clone https://github.com/Rohit-554/Ringlr.git

2. Copy the shared module into your project

Place the shared directory at the root of your project alongside your app module.

3. Register the module

In your project's settings.gradle.kts:

include(":shared")

4. Add the dependency

In your app module's build.gradle.kts:

dependencies {
    implementation(project(":shared"))
}

5. Sync Gradle

./gradlew build

Android Initialization

Application class

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        PlatformConfiguration.init(this)
    }
}

AndroidManifest.xml

<application android:name=".MyApplication">

    <service
        android:name="io.jadu.ringlr.call.TelecomConnectionService"
        android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE"
        android:exported="true">
        <intent-filter>
            <action android:name="android.telecom.ConnectionService" />
        </intent-filter>
    </service>

</application>

Compose entry point

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        val configuration = PlatformConfiguration.create()
        setContent {
            App(configuration = configuration)
        }
    }
}

iOS Initialization

No Application subclass is needed on iOS. Create and initialise PlatformConfiguration in your Compose entry point. The CXProvider is a singleton owned by PlatformConfiguration — never recreate it per call.

fun MainViewController() = ComposeUIViewController {
    val configuration = remember {
        PlatformConfiguration.create().also {
            it.initializeCallConfiguration()
        }
    }
    App(configuration = configuration)
}

Info.plist

Android Permissions

Declare these in your AndroidManifest.xml:

<uses-permission android:name="android.permission.ANSWER_PHONE_CALLS" />
<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
<uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

iOS Permissions

CallKit handles call access at the system level — no runtime CALL_PHONE equivalent is required.

Runtime Permission Handling

Bind the controller in your Composable

@Composable
fun App(configuration: PlatformConfiguration) {
    val factory = rememberPermissionsControllerFactory()
    val controller = remember(factory) { factory.createPermissionsController() }
    BindEffect(controller)
}

Request a permission

scope.launch {
    when (controller.getPermissionState(Permission.CALL_PHONE)) {
        PermissionState.Granted      -> placeCall()
        PermissionState.DeniedAlways -> controller.openAppSettings()
        else -> {
            try {
                controller.providePermission(Permission.CALL_PHONE)
                placeCall()
            } catch (e: DeniedAlwaysException) {
                controller.openAppSettings()
            } catch (e: DeniedException) {
                showPermissionRationale()
            }
        }
    }
}

Available permissions

Placing Calls

Setup

val configuration = PlatformConfiguration.create()
configuration.initializeCallConfiguration()
val callManager = CallManager(configuration)

Outgoing call

val result = callManager.startOutgoingCall(
    number      = "+1234567890",
    displayName = "John Doe"
)

when (result) {
    is CallResult.Success -> println("Call started: ${result.data.id}")
    is CallResult.Error   -> println("Failed: ${result.error}")
}

SIP / VoIP call

callManager.startOutgoingCall(
    number      = "alice@sip.example.com",
    displayName = "Alice",
    scheme      = "sip"
)

End / Answer / Decline

callManager.endCall(call.id)
callManager.answerCall(call.id)
callManager.declineCall(call.id)

Call Controls

callManager.muteCall(call.id, muted = true)
callManager.muteCall(call.id, muted = false)

callManager.holdCall(call.id, onHold = true)
callManager.holdCall(call.id, onHold = false)

val stateResult = callManager.getCallState(call.id)
val allCalls    = callManager.getActiveCalls()

CallState values

Audio Routing

callManager.setAudioRoute(AudioRoute.SPEAKER)
callManager.setAudioRoute(AudioRoute.EARPIECE)
callManager.setAudioRoute(AudioRoute.BLUETOOTH)
callManager.setAudioRoute(AudioRoute.WIRED_HEADSET)

val routeResult = callManager.getCurrentAudioRoute()

Callbacks

val callback = object : CallStateCallback {
    override fun onCallStateChanged(call: Call) {
        when (call.state) {
            CallState.ACTIVE  -> showActiveCallUI(call)
            CallState.ENDED   -> dismissCallUI()
            CallState.HOLDING -> showOnHoldBadge()
            else -> {}
        }
    }
    override fun onCallAdded(call: Call)   { showIncomingCallUI(call) }
    override fun onCallRemoved(call: Call) { dismissCallUI() }
}

callManager.registerCallStateCallback(callback)
callManager.unregisterCallStateCallback(callback)

CallResult

Every CallManager operation returns CallResult<T>. No exceptions leak through the API boundary.

sealed class CallResult<out T> {
    data class Success<T>(val data: T) : CallResult<T>()
    data class Error(val error: CallError) : CallResult<Nothing>()
}

CallError variants

CallScreen

Ringlr ships a ready-to-use Compose Multiplatform call screen. Drop it into App() and you get a complete calling UI with no extra work.

@Composable
fun App(configuration: PlatformConfiguration) {
    val callManager = remember(configuration) {
        configuration.initializeCallConfiguration()
        CallManager(configuration)
    }
    val factory = rememberPermissionsControllerFactory()
    val permissionsController = remember(factory) { factory.createPermissionsController() }
    BindEffect(permissionsController)

    MaterialTheme(colorScheme = darkColorScheme()) {
        CallScreen(
            callManager           = callManager,
            permissionsController = permissionsController
        )
    }
}

CallScreen routes between three sub-screens based on call state:

UI Components

VoIP / SIP Overview

Ringlr provides the system-UI and call-lifecycle layer for VoIP/SIP — it does not bundle a SIP stack or media engine. You bring your own.

Android

Android removed its built-in SipManager in Android 12 (API 31).

• API ≤ 30: configureSipAccount() sets up the system SIP manager automatically.
• API 31+: configureSipAccount() returns CallError.SipUnsupported. Establish your session with Linphone, PJSIP, or WebRTC, then call startOutgoingCall(scheme = "sip").

myVoipStack.connect(sipAddress) { sessionEstablished ->
    scope.launch {
        callManager.startOutgoingCall(
            number      = sipAddress,
            displayName = "Alice",
            scheme      = "sip"
        )
    }
}

iOS

CallKit is transport-agnostic. configureSipAccount() stores the profile for your own use; CallKit shows the system UI via startOutgoingCall(scheme = "sip") regardless of the underlying protocol.

callManager.configureSipAccount(
    SipProfile(
        username    = "alice",
        server      = "sip.example.com",
        password    = "secret",
        port        = 5060,
        displayName = "Alice"
    )
)

callManager.startOutgoingCall(
    number      = "bob@sip.example.com",
    displayName = "Bob",
    scheme      = "sip"
)

VoIP Push Notifications

VoIP push wakes the app for an incoming call even when it is suspended. Without it, iOS will not reliably display the incoming call screen.

iOS — PushKit (automatic)

val registrar = VoipPushRegistrar(platformConfig)
registrar.register(object : VoipPushListener {
    override fun onTokenRefreshed(token: String) { sendTokenToServer(token) }
    override fun onIncomingCall(payload: VoipPushPayload) {
        // CallKit system UI is shown by Ringlr automatically.
    }
})

Android — FCM bridge

// Application.onCreate
val registrar = VoipPushRegistrar(platformConfig)
registrar.register(object : VoipPushListener {
    override fun onTokenRefreshed(token: String) { sendToServer(token) }
    override fun onIncomingCall(payload: VoipPushPayload) { /* show in-app UI */ }
})

// FirebaseMessagingService
override fun onNewToken(token: String) {
    registrar.handleTokenRefresh(token)
}

override fun onMessageReceived(message: RemoteMessage) {
    if (message.data["type"] == "voip") {
        registrar.handleVoipPush(
            VoipPushPayload(
                callId       = message.data["call_id"]       ?: "",
                callerNumber = message.data["caller_number"] ?: "",
                callerName   = message.data["caller_name"]   ?: "Unknown",
                scheme       = message.data["scheme"]        ?: "sip"
            )
        )
    }
}

Project Structure

shared/
└── src/
    ├── commonMain/
    │   ├── CallScreen.kt
    │   ├── App.kt
    │   └── call/
    │       ├── CallHandler.kt          # expect PlatformConfiguration + CallManager
    │       ├── CallManagerInterface.kt
    │       ├── Call.kt · CallState.kt · CallResult.kt · CallError.kt
    │       ├── AudioRoute.kt · CallStateCallback.kt
    │       └── voip/
    │           ├── VoipPushRegistrar.kt
    │           ├── VoipPushListener.kt
    │           └── VoipPushPayload.kt
    ├── androidMain/
    │   └── call/
    │       ├── CallHandler.android.kt
    │       ├── TelecomConnectionService.kt
    │       ├── PhoneAccountRegistrar.kt
    │       └── voip/VoipPushRegistrar.android.kt
    └── iosMain/
        └── call/
            ├── CallHandler.ios.kt
            ├── callkit/
            │   ├── ActiveCallRegistry.kt
            │   ├── SystemCallBridge.kt
            │   ├── CallActionDispatcher.kt
            │   └── CallAudioRouter.kt
            └── voip/VoipPushRegistrar.ios.kt

demoApp/
└── src/main/kotlin/io/jadu/ringlr/demo/
    ├── DemoApplication.kt
    └── MainActivity.kt

Important Notes

• Always call initializeCallConfiguration() before CallManager — the platform bridges are set up lazily; skipping this causes silent failures.
• Call cleanupCallConfiguration() when done — on iOS this invalidates the CXProvider; on Android it unregisters the phone account.
• Android: register TelecomConnectionService in the manifest — calls will silently fail without it.
• iOS: PlatformConfiguration is a singleton — never recreate it per call; the CXProvider must be stable for the lifetime of the app.
• Always unregister callbacks — use DisposableEffect in Compose to tie callback lifetime to composable lifetime.
• SIP on Android 12+ requires an external stack — the system SipManager was removed in API 31.

Troubleshooting