@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-android-v5-calls/references/voip-calling.md

@@ -1,526 +0,0 @@
----
-name: voip-calling
-description: Implement native VoIP calling with ConnectionService, PhoneAccount, FCM push, and system call UI. Use when receiving calls in background/killed state, lock screen calls, or Telecom framework integration. Triggers on "VoIP", "voip calling", "ConnectionService", "PhoneAccount", "push notification call", "background call".
-inclusion: manual
----
-
-# 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.+`) 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
-
-| Component | Purpose |
-|-----------|---------|
-| `CallFirebaseMessagingService` | Receives FCM push for incoming calls, parses payload, routes to CallNotificationManager |
-| `CallConnectionService` | Bridges app with Android Telecom, creates CallConnection instances |
-| `PhoneAccountManager` | Registers app as self-managed VoIP calling provider |
-| `CallConnection` | Represents individual call (accept/reject/hold) in Telecom framework |
-| `CallNotificationManager` | Routes calls to TelecomManager with fallback to high-priority notification |
-| `CallActionReceiver` | Handles accept/decline from fallback notification |
-| `CallConnectionHolder` | Singleton for cross-component access to active CallConnection |
-| `CallData` | Parcelable call metadata passed between components |
-| `VoIPApplication` | Application subclass tracking foreground state, global CallListener |
-
-## Dual Incoming Call Path
-
-| App State | Trigger | Handler | UI |
-|-----------|---------|---------|-----|
-| Foreground | `CometChat.CallListener` | `VoIPApplication` global listener | `IncomingCallActivity` |
-| Background | FCM push | `CallFirebaseMessagingService` → `CallNotificationManager` → `TelecomManager` | System call UI |
-| Killed | FCM push | `CallFirebaseMessagingService` → `CallNotificationManager` → `TelecomManager` | System call UI |
-| Background/Killed (fallback) | FCM push | `CallNotificationManager` → high-priority notification | `IncomingCallActivity` via full-screen intent |
-
-## Implementation
-
-### 1. CallData Parcelable Model
-
-```kotlin
-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:
-
-```json
-{
-  "type": "call",
-  "sessionId": "v1.us.xxx",
-  "senderName": "John Doe",
-  "senderUid": "john_doe",
-  "callType": "video",
-  "senderAvatar": "https://..."
-}
-```
-
-### 3. FCM Service
-
-```kotlin
-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
-
-```kotlin
-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)
-
-```kotlin
-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
-
-```kotlin
-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)
-
-```kotlin
-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)
-
-```kotlin
-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
-
-```kotlin
-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)
-
-```kotlin
-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
-
-```xml
-<!-- 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:
-
-```kotlin
-// 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