Voip Calling

CometChat Calls SDK v5 — VoIP Calling

Overview

Native VoIP calling using Android's Telecom framework (ConnectionService). Shows system call UI on lock screen, works when app is killed, integrates with Bluetooth/car systems. Requires FCM push notifications. Falls back to a high-priority notification when TelecomManager is unavailable.

Prerequisites

• Chat SDK v4 (com.cometchat:chat-sdk-android:4.0.+) + Calls SDK v5 (com.cometchat:calls-sdk-android:5.0.4) integrated
• Firebase Cloud Messaging (FCM) configured with com.google.gms.google-services plugin
• Push notifications enabled in CometChat Dashboard
• Android 8.0+ (API 26+), compileSdk 35

Key Components

Dual Incoming Call Path

Implementation

1. CallData Parcelable Model

package com.cometchat.samplecallsvoip.data.model

import android.os.Parcelable
import kotlinx.parcelize.Parcelize

@Parcelize
data class CallData(
    val sessionId: String,
    val callerName: String,
    val callerUid: String,
    val callType: String,       // "audio" or "video"
    val callerAvatar: String?
) : Parcelable

2. FCM Payload Structure

The FCM push payload for incoming calls:

{
  "type": "call",
  "sessionId": "v1.us.xxx",
  "senderName": "John Doe",
  "senderUid": "john_doe",
  "callType": "video",
  "senderAvatar": "https://..."
}

3. FCM Service

class CallFirebaseMessagingService : FirebaseMessagingService() {

    companion object {
        private const val TAG = "CallFCMService"
        private const val KEY_TYPE = "type"
        private const val KEY_SESSION_ID = "sessionId"
        private const val KEY_SENDER_NAME = "senderName"
        private const val KEY_SENDER_UID = "senderUid"
        private const val KEY_CALL_TYPE = "callType"
        private const val KEY_SENDER_AVATAR = "senderAvatar"
        private const val TYPE_CALL = "call"

        /** Parses FCM data payload into CallData. Returns null if not a call or missing required fields. */
        fun parseCallData(data: Map<String, String>): CallData? {
            if (data[KEY_TYPE] != TYPE_CALL) return null
            val sessionId = data[KEY_SESSION_ID]
            val senderUid = data[KEY_SENDER_UID]
            if (sessionId.isNullOrEmpty() || senderUid.isNullOrEmpty()) return null
            return CallData(
                sessionId = sessionId,
                callerName = data[KEY_SENDER_NAME] ?: "",
                callerUid = senderUid,
                callType = data[KEY_CALL_TYPE] ?: "audio",
                callerAvatar = data[KEY_SENDER_AVATAR]
            )
        }

        /** Returns true when push should be handled (background/killed), false when ignored (foreground). */
        fun shouldHandlePush(isAppInForeground: Boolean): Boolean = !isAppInForeground
    }

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        val callData = parseCallData(remoteMessage.data) ?: return
        if (isAppInForeground()) return
        CallNotificationManager.showIncomingCall(this, callData)
    }

    override fun onNewToken(token: String) {
        CometChat.registerTokenForPushNotification(token, object : CometChat.CallbackListener<String>() {
            override fun onSuccess(message: String) { Log.d(TAG, "FCM token registered") }
            override fun onError(e: CometChatException) { Log.w(TAG, "Failed to register FCM token: ${e.message}") }
        })
    }

    private fun isAppInForeground(): Boolean {
        val app = application
        if (app is VoIPApplication) return app.isInForeground
        return ProcessLifecycleOwner.get().lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)
    }
}

4. Register PhoneAccount

object PhoneAccountManager {
    private const val ACCOUNT_ID = "cometchat_voip_account"
    private const val ACCOUNT_LABEL = "CometChat Calls VoIP"

    fun register(context: Context) {
        val telecomManager = context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
        val handle = getPhoneAccountHandle(context)
        val phoneAccount = PhoneAccount.builder(handle, ACCOUNT_LABEL)
            .setCapabilities(PhoneAccount.CAPABILITY_CALL_PROVIDER or PhoneAccount.CAPABILITY_SELF_MANAGED)
            .build()
        telecomManager.registerPhoneAccount(phoneAccount)
    }

    fun getPhoneAccountHandle(context: Context): PhoneAccountHandle {
        val componentName = ComponentName(context, CallConnectionService::class.java)
        return PhoneAccountHandle(componentName, ACCOUNT_ID)
    }

    fun isPhoneAccountEnabled(context: Context): Boolean {
        val telecomManager = context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
        val account = telecomManager.getPhoneAccount(getPhoneAccountHandle(context))
        return account?.isEnabled == true
    }

    fun openPhoneAccountSettings(context: Context) {
        val intent = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            Intent(TelecomManager.ACTION_CHANGE_PHONE_ACCOUNTS)
        } else {
            Intent("android.telecom.action.CHANGE_PHONE_ACCOUNTS")
        }
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        context.startActivity(intent)
    }
}
// Call PhoneAccountManager.register() in Application.onCreate() or SplashActivity

5. CallNotificationManager (TelecomManager + Fallback)

object CallNotificationManager {
    const val NOTIFICATION_ID = 1001
    const val CHANNEL_ID = "voip_call_channel"
    const val ACTION_ACCEPT = "ACTION_ACCEPT"
    const val ACTION_DECLINE = "ACTION_DECLINE"
    const val EXTRA_CALL_DATA = "call_data"

    fun showIncomingCall(context: Context, callData: CallData) {
        // Check PhoneAccount first — if not enabled, go straight to fallback
        if (!PhoneAccountManager.isPhoneAccountEnabled(context)) {
            showFallbackNotification(context, callData)
            return
        }
        try {
            val telecomManager = context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
            val extras = Bundle().apply { putParcelable("call_data", callData) }
            telecomManager.addNewIncomingCall(PhoneAccountManager.getPhoneAccountHandle(context), extras)
        } catch (e: SecurityException) {
            showFallbackNotification(context, callData)
        }
    }

    fun cancelNotification(context: Context) {
        val nm = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        nm.cancel(NOTIFICATION_ID)
    }

    private fun showFallbackNotification(context: Context, callData: CallData) {
        val nm = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        nm.createNotificationChannel(
            NotificationChannel(CHANNEL_ID, "Incoming Calls", NotificationManager.IMPORTANCE_HIGH)
        )

        // Full-screen intent → IncomingCallActivity
        val fullScreenIntent = Intent().apply {
            setClassName(context, "com.cometchat.samplecallsvoip.ui.activity.IncomingCallActivity")
            putExtra(EXTRA_CALL_DATA, callData)
            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
        }
        val fullScreenPI = PendingIntent.getActivity(context, 0, fullScreenIntent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)

        // Accept/Decline actions → CallActionReceiver
        val acceptPI = PendingIntent.getBroadcast(context, 1,
            Intent(context, CallActionReceiver::class.java).apply {
                action = ACTION_ACCEPT; putExtra(EXTRA_CALL_DATA, callData)
            }, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)

        val declinePI = PendingIntent.getBroadcast(context, 2,
            Intent(context, CallActionReceiver::class.java).apply {
                action = ACTION_DECLINE; putExtra(EXTRA_CALL_DATA, callData)
            }, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE)

        val notification = NotificationCompat.Builder(context, CHANNEL_ID)
            .setSmallIcon(R.drawable.ic_cometchat_logo)
            .setContentTitle("${if (callData.callType == "audio") "Voice" else "Video"} Call")
            .setContentText("${callData.callerName.ifEmpty { "Unknown" }} is calling…")
            .setPriority(NotificationCompat.PRIORITY_MAX)
            .setCategory(NotificationCompat.CATEGORY_CALL)
            .setOngoing(true)
            .setFullScreenIntent(fullScreenPI, true)
            .addAction(0, "Accept", acceptPI)
            .addAction(0, "Decline", declinePI)
            .build()

        nm.notify(NOTIFICATION_ID, notification)
    }
}

6. ConnectionService

class CallConnectionService : ConnectionService() {
    override fun onCreateIncomingConnection(
        connectionManagerPhoneAccount: PhoneAccountHandle?,
        request: ConnectionRequest?
    ): Connection {
        val callData: CallData? = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            request?.extras?.getParcelable("call_data", CallData::class.java)
        } else {
            @Suppress("DEPRECATION")
            request?.extras?.getParcelable("call_data")
        }
        val connection = CallConnection(applicationContext, callData)
        CallConnectionHolder.set(connection)
        return connection
    }
}

7. CallConnection (Accept/Reject)

class CallConnection(
    private val context: Context,
    private val callData: CallData?
) : Connection() {

    companion object {
        const val EXTRA_SESSION_ID = "session_id"
        const val EXTRA_CALL_TYPE = "call_type"
    }

    init {
        connectionProperties = PROPERTY_SELF_MANAGED
        connectionCapabilities = CAPABILITY_HOLD or CAPABILITY_SUPPORT_HOLD
        audioModeIsVoip = true
        callData?.let {
            setCallerDisplayName(it.callerName, TelecomManager.PRESENTATION_ALLOWED)
            setAddress(Uri.fromParts("tel", it.callerUid, null), TelecomManager.PRESENTATION_ALLOWED)
        }
        setInitializing()
        setRinging()
    }

    override fun onAnswer() {
        val sessionId = callData?.sessionId ?: run {
            setDisconnected(DisconnectCause(DisconnectCause.ERROR)); destroy(); return
        }
        CometChat.acceptCall(sessionId, object : CometChat.CallbackListener<Call>() {
            override fun onSuccess(call: Call) {
                setActive()
                launchCallActivity(sessionId)
                CallNotificationManager.cancelNotification(context)
            }
            override fun onError(e: CometChatException) {
                setDisconnected(DisconnectCause(DisconnectCause.ERROR)); destroy()
            }
        })
    }

    override fun onReject() {
        val sessionId = callData?.sessionId
        if (!sessionId.isNullOrEmpty()) {
            CometChat.rejectCall(sessionId, CometChatConstants.CALL_STATUS_REJECTED,
                object : CometChat.CallbackListener<Call>() {
                    override fun onSuccess(call: Call) {}
                    override fun onError(e: CometChatException) {}
                })
        }
        setDisconnected(DisconnectCause(DisconnectCause.REJECTED))
        destroy()
        CallNotificationManager.cancelNotification(context)
    }

    override fun onDisconnect() {
        setDisconnected(DisconnectCause(DisconnectCause.LOCAL))
        destroy()
    }

    private fun launchCallActivity(sessionId: String) {
        val intent = Intent().apply {
            setClassName(context, "com.cometchat.samplecallsvoip.ui.activity.CallActivity")
            putExtra(EXTRA_SESSION_ID, sessionId)
            putExtra(EXTRA_CALL_TYPE, callData?.callType ?: CometChatConstants.CALL_TYPE_VIDEO)
            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
        }
        context.startActivity(intent)
    }
}

8. CallActionReceiver (Fallback Notification Actions)

class CallActionReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val callData = intent.getParcelableExtra<CallData>(CallNotificationManager.EXTRA_CALL_DATA)
        val sessionId = callData?.sessionId ?: return

        when (intent.action) {
            CallNotificationManager.ACTION_ACCEPT -> {
                CometChat.acceptCall(sessionId, object : CometChat.CallbackListener<Call>() {
                    override fun onSuccess(call: Call) {
                        val launchIntent = Intent().apply {
                            setClassName(context, "com.cometchat.samplecallsvoip.ui.activity.CallActivity")
                            putExtra(CallConnection.EXTRA_SESSION_ID, sessionId)
                            putExtra(CallConnection.EXTRA_CALL_TYPE, callData?.callType ?: CometChatConstants.CALL_TYPE_VIDEO)
                            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
                        }
                        context.startActivity(launchIntent)
                        CallNotificationManager.cancelNotification(context)
                    }
                    override fun onError(e: CometChatException) {
                        CallNotificationManager.cancelNotification(context)
                    }
                })
            }
            CallNotificationManager.ACTION_DECLINE -> {
                CometChat.rejectCall(sessionId, CometChatConstants.CALL_STATUS_REJECTED,
                    object : CometChat.CallbackListener<Call>() {
                        override fun onSuccess(call: Call) {}
                        override fun onError(e: CometChatException) {}
                    })
                CallNotificationManager.cancelNotification(context)
            }
        }
    }
}

9. CallConnectionHolder

object CallConnectionHolder {
    private var activeConnection: Connection? = null

    fun set(connection: Connection) { activeConnection = connection }
    fun get(): Connection? = activeConnection
    fun clear() { activeConnection = null }

    /** Ends the active call by calling onDisconnect() and clears the reference. */
    fun endCall() {
        activeConnection?.onDisconnect()
        clear()
    }
}

10. VoIPApplication (Foreground State + Global CallListener)

class VoIPApplication : Application(), DefaultLifecycleObserver {
    var isInForeground: Boolean = false
        private set

    override fun onCreate() {
        super<Application>.onCreate()
        ProcessLifecycleOwner.get().lifecycle.addObserver(this)
    }

    override fun onStart(owner: LifecycleOwner) { isInForeground = true }
    override fun onStop(owner: LifecycleOwner) { isInForeground = false }

    /** Register after SDK init + user login. Launches IncomingCallActivity for foreground calls. */
    fun registerCallListener() {
        CometChat.addCallListener("voip_app_call_listener", object : CometChat.CallListener() {
            override fun onIncomingCallReceived(call: Call?) {
                if (call == null || !isInForeground) return
                val caller = call.callInitiator as? User
                val intent = Intent(this@VoIPApplication, IncomingCallActivity::class.java).apply {
                    putExtra("session_id", call.sessionId)
                    putExtra("caller_name", caller?.name ?: "Unknown")
                    putExtra("caller_avatar", caller?.avatar ?: "")
                    putExtra("call_type", call.type)
                    addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
                }
                startActivity(intent)
            }
            override fun onOutgoingCallAccepted(call: Call?) {}
            override fun onOutgoingCallRejected(call: Call?) {}
            override fun onIncomingCallCancelled(call: Call?) {}
            override fun onCallEndedMessageReceived(call: Call?) {}
        })
    }

    fun unregisterCallListener() {
        CometChat.removeCallListener("voip_app_call_listener")
    }
}

11. Manifest

<!-- Permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />

<!-- VoIP ConnectionService -->
<service android:name=".voip.CallConnectionService"
    android:exported="true"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.ConnectionService" />
    </intent-filter>
</service>

<!-- FCM Service -->
<service android:name=".voip.CallFirebaseMessagingService" android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

<!-- Fallback notification action receiver -->
<receiver android:name=".voip.CallActionReceiver" android:exported="false" />

Call Session Integration

When a call is accepted (via ConnectionService or fallback notification), launch CallActivity which joins the session:

// Build SessionSettings based on call type
val isVoiceOnly = callType == CometChatConstants.CALL_TYPE_AUDIO
val settings = CometChatCalls.SessionSettingsBuilder()
    .setTitle("CometChat Call")
    .setSessionType(if (isVoiceOnly) SessionType.VOICE else SessionType.VIDEO)
    .setLayout(if (isVoiceOnly) LayoutType.SPOTLIGHT else LayoutType.TILE)
    .setAudioMode(if (isVoiceOnly) AudioMode.EARPIECE else AudioMode.SPEAKER)
    .startVideoPaused(isVoiceOnly)
    .startAudioMuted(false)
    .build()

CometChatCalls.joinSession(sessionId, settings, callContainer, listener)

// On session joined → start foreground service
CometChatOngoingCallService.launch(activity)

// On session end → clean up
CometChatOngoingCallService.abort(activity)
CallConnectionHolder.endCall()
CallNotificationManager.cancelNotification(activity)

Gotchas

• CAPABILITY_SELF_MANAGED is required for VoIP apps that manage their own UI
• Some devices require users to manually enable the PhoneAccount in Settings — use PhoneAccountManager.isPhoneAccountEnabled() to check and openPhoneAccountSettings() to redirect
• If app is in foreground, let CometChat.CallListener handle it instead of ConnectionService — the FCM service checks isAppInForeground() and skips
• CallData must implement Parcelable to pass between components (Services, Activities, BroadcastReceivers)
• Always register PhoneAccount in Application.onCreate() or SplashActivity before any calls arrive
• On API 33+ use the typed getParcelable(key, Class) overload in ConnectionService.onCreateIncomingConnection()
• Always cancel the fallback notification on terminal call states (answered, rejected, cancelled) via CallNotificationManager.cancelNotification()
• Always disconnect the CallConnection via CallConnectionHolder.endCall() when the call session ends
• The fallback notification uses PRIORITY_MAX, CATEGORY_CALL, ongoing=true, and a full-screen intent for lock screen display
• This builds on top of the basic ringing integration — understand that first

Sample App Reference

• samples/sample-app-voip/ — Complete working VoIP sample app demonstrating all patterns above
  • voip/CallFirebaseMessagingService.kt — FCM push handling with payload parsing
  • voip/PhoneAccountManager.kt — PhoneAccount registration and status checks
  • voip/CallConnectionService.kt — ConnectionService bridging Telecom framework
  • voip/CallConnection.kt — Individual call representation (accept/reject/disconnect)
  • voip/CallNotificationManager.kt — TelecomManager routing with fallback notification
  • voip/CallActionReceiver.kt — Fallback notification accept/decline handler
  • voip/CallConnectionHolder.kt — Singleton for active connection access
  • data/model/CallData.kt — Parcelable call metadata
  • VoIPApplication.kt — Application class with foreground tracking and global CallListener
  • ui/activity/CallActivity.kt — Call session with SessionSettings mapping