feat(android): create VoipCallService with FOREGROUND_SERVICE_MICROPHONE

[diegolmello]

Proposed changes

Create VoipCallService — an Android foreground Service with foregroundServiceType="microphone" — so VoIP audio calls keep running when the app is backgrounded. Without a foreground service, Android terminates the process and drops the active WebRTC audio session, which is the same problem iOS solves via CallKit audio retention.

What this adds

• VoipCallService.kt — foreground service that starts/stops around the call lifecycle.
  • startService(context, callId): starts in foreground with an ongoing notification.
  • stopService(context): requests shutdown.
  • ACTION_START / ACTION_STOP intent actions for explicit control.
  • ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE on API 29+.
  • Low-priority notification channel and ongoing notification.
• AndroidManifest.xml — declares the service with foregroundServiceType="microphone", enabled="true", exported="false".

Review fixes applied

Addresses CodeRabbit review findings #1 (production crash) and #2 (start-command semantics):

1. stopService() helper now calls context.stopService(intent) instead of context.startService(intent). On Android 8+ (API 26+), invoking startService from a background context throws IllegalStateException / BackgroundServiceStartNotAllowedException — which is exactly when a hangup from a backgrounded or headless-notification flow happens.
2. onStartCommand returns START_NOT_STICKY for ACTION_START (was START_STICKY). A redelivered null intent cannot recover the WebRTC peer connection, so sticky semantics would only log a warning and terminate anyway.
3. stopSelf(startId) replaces stopSelf() in the ACTION_STOP and unknown-action branches, so only the matching start token is released and no start counts are leaked.

Issue(s)

N/A — internal VoIP work.

How to test or reproduce

1. Place a VoIP call (ACTION_START), background the app, verify audio continues and the ongoing notification is visible.
2. Hang up from the notification (ACTION_STOP); verify the service stops without IllegalStateException in logs.
3. Send ACTION_STOP while the app is fully backgrounded; the service still tears down cleanly (this is the case the fix unblocks).

Types of changes

• New feature (non-breaking change which adds functionality)
• Bugfix (non-breaking change which fixes an issue) — for the review-fix commit on top

Checklist

• I have read the CONTRIBUTING doc
• I have signed the CLA
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works — N/A for foreground service lifecycle; covered by manual VoIP test plan above
• I have added necessary documentation — N/A
• Any dependent changes have been merged and published in downstream modules

Further comments

Merge order

This is PR 3 of 6 in the VoIP Android integration series:

1. PR-2: fix(ios) DDP cleanup — independent (merged)
2. PR-1: fix(ios) NSLock + timeout — independent (merged)
3. PR-3: feat(android) VoipCallService ← this PR
4. PR-4: fix(android) service integration — depends on PR-3
5. PR-5: fix(both) null guard — independent, merge before PR-6
6. PR-6: chore(ts) cleanup — last (shares file with PR-5)

Summary by CodeRabbit

• New Features
  • VoIP calling now runs reliably in the background, allowing calls to persist when switching apps.
  • Active calls show a persistent notification so users are informed and can return to the app quickly.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0ebfdb2b-f542-49a3-a4d0-3d9253991606

📥 Commits

Reviewing files that changed from the base of the PR and between 359f1bf and 4d9feb2.

📒 Files selected for processing (1)

• android/app/src/main/java/chat/rocket/reactnative/voip/VoipCallService.kt

🚧 Files skipped from review as they are similar to previous changes (1)

• android/app/src/main/java/chat/rocket/reactnative/voip/VoipCallService.kt

---

Walkthrough

Adds a new Android foreground service, VoipCallService, to manage VoIP calls in the background; it is declared in the manifest with microphone foreground service type and provides intent-based start/stop entry points, notification handling, and lifecycle management.

Changes

Cohort / File(s)	Summary
Android Manifest Configuration android/app/src/main/AndroidManifest.xml	Added a new <service> entry for chat.rocket.reactnative.voip.VoipCallService with android:enabled="true", android:exported="false", and android:foregroundServiceType="microphone".
VoIP Call Service Implementation android/app/src/main/java/chat/rocket/reactnative/voip/VoipCallService.kt	New foreground Service class with companion helpers startService(context, callId) and stopService(context) that send start/stop intents; handles ACTION_START/ACTION_STOP, prevents duplicate starts via isRunning, creates notification channel (O+), builds ongoing notification with PendingIntent to MainActivity, starts foreground (uses FOREGROUND_SERVICE_TYPE_MICROPHONE on Q+), and cleans up on destroy.

Sequence Diagram(s)

sequenceDiagram
    participant App as App / Caller
    participant Service as VoipCallService
    participant Notif as NotificationManager
    participant OS as Android OS
    participant Main as MainActivity
    participant User as User

    App->>Service: startService(context, callId)
    Service->>Service: if isRunning -> ignore
    alt not running
        Service->>Notif: createNotificationChannel() (Android O+)
        Service->>Notif: build ongoing Notification (PendingIntent -> Main)
        Service->>OS: startForeground(notification) [FOREGROUND_SERVICE_TYPE_MICROPHONE on Q+]
        Service->>Service: isRunning = true
    end

    User->>Main: tap notification (PendingIntent)

    App->>Service: stopService(context)
    Service->>Service: onStartCommand(ACTION_STOP) -> stopSelf()
    Service->>OS: stopForeground/stopSelf()
    Service->>Service: onDestroy() -> isRunning = false

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

type: feature

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(android): create VoipCallService with FOREGROUND_SERVICE_MICROPHONE' accurately and specifically describes the main change: creation of a new Android VoIP service with foreground microphone capability.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (6)

• PR-2: Request failed with status code 401
• PR-1: Request failed with status code 401
• PR-3: Request failed with status code 401
• PR-4: Request failed with status code 401
• PR-5: Request failed with status code 401
• PR-6: Request failed with status code 401

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[diegolmello]

Code Review — PR #7199

Files Reviewed: VoipCallService.kt, AndroidManifest.xml
Issues: 0 CRITICAL/HIGH, 2 LOW observations

---

[LOW] isRunning flag is static but also managed via service lifecycle

File: VoipCallService.kt:26

isRunning is a static flag used to prevent duplicate startForeground calls. However, since each startService() call with ACTION_START creates a new startId, the START_STICKY return value means the service could be killed and recreated. The isRunning flag won't be reset on service recreation (it remains true), which means subsequent startService calls would be silently dropped.

Fix: Remove the isRunning guard entirely — startForeground() is idempotent and can be called multiple times on the same service instance. If the service is killed and recreated, Android recreates it in a fresh state.

override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
    when (intent?.action) {
        ACTION_STOP -> {
            Log.d(TAG, "Stopping VoipCallService")
            stopSelf()
            return START_NOT_STICKY
        }
        ACTION_START -> {
            val callId = intent.getStringExtra(EXTRA_CALL_ID) ?: "unknown"
            Log.d(TAG, "Starting VoipCallService for callId: $callId")
            startForegroundWithNotification(callId)
            return START_STICKY
        }
        else -> {
            Log.w(TAG, "Unknown action: ${intent?.action}")
            return START_NOT_STICKY
        }
    }
}

---

[LOW] Small icon fallback uses application icon which may not be visible

File: VoipCallService.kt:99

getApplicationInfo().icon falls back to the app's launcher icon, which is typically not designed for notification small icons (expects a flat, monochrome drawable). On Android 5-6, this renders as a white silhouette. Consider creating a dedicated ic_voip_call drawable.

This is LOW because: (a) the notification is PRIORITY_LOW and not user-facing, (b) the fallback is standard Android practice, (c) CallKit/Telecom keeps the call alive anyway.

---

Acceptance Criteria Verification

Criterion	Status	Notes
VoipCallService.kt exists and compiles	✅	BUILD SUCCESSFUL
Manifest declares service with foregroundServiceType="microphone"	✅	Line 152-156
Manifest declares FOREGROUND_SERVICE_MICROPHONE permission	✅	Implied by foregroundServiceType attribute (no separate permission needed on API 34-)
Service starts in foreground with notification	✅	startForegroundWithNotification() with ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE on API 29+
Service stops via stopSelf() correctly	✅	ACTION_STOP path calls stopSelf() at line 79

---

Positive Observations

1. Clean intent-based control. ACTION_START/ACTION_STOP pattern is simple, testable, and avoids static state.
2. API-level guard correct. ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE only used on API 29+ (Android 10), with plain startForeground on earlier versions.
3. Notification channel properly scoped. IMPORTANCE_LOW + setShowBadge(false) is correct for a persistent service notification that shouldn't interrupt the user.
4. PendingIntent flags correct. Uses FLAG_IMMUTABLE on API 31+ with fallback to 0.
5. Matches iOS CallKit pattern. Parity with how CallKit keeps the VoIP call alive on iOS.

---

Verdict

LGTM — All 5 acceptance criteria satisfied. Both LOW observations are informational only and don't block the PR. The isRunning guard issue is LOW because in practice, startForeground is idempotent even if the flag isn't reset on recreation.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@android/app/src/main/java/chat/rocket/reactnative/voip/VoipCallService.kt`:
- Around line 73-74: The code logs a potentially sensitive call identifier when
starting the service; in VoipCallService replace the Log.d(TAG, "Starting
VoipCallService for callId: $callId") with a generic lifecycle message that
omits the callId (e.g., "Starting VoipCallService"); keep retrieving
EXTRA_CALL_ID into callId if needed for logic but do not include it in any logs
or exceptions, and make the same change for the other occurrence that logs
callId (the Log.d/Log.i call around the second usage noted at the other
occurrence).
- Around line 50-56: The stopService function in VoipCallService builds an
Intent with ACTION_STOP and incorrectly calls context.startService(intent);
change this to call context.stopService(intent) so the service is stopped via
Context.stopService(), avoiding background-start IllegalStateException on
Android 8+; update the call inside fun stopService(context:
android.content.Context) to use context.stopService(intent) while keeping the
Intent construction with ACTION_STOP and the VoipCallService::class.java target.
- Around line 65-85: The onStartCommand implementation in VoipCallService should
not return START_STICKY because the service cannot recover call state from a
null intent; update the ACTION_START branch return to START_NOT_STICKY so the OS
won't restart the service expecting to restore an active WebRTC call, and change
unconditional stopSelf() calls to stopSelf(startId) to use the precise lifecycle
token; specifically modify VoipCallService.onStartCommand (handling ACTION_STOP
and ACTION_START), keep the existing isRunning and
startForegroundWithNotification(callId) logic, but replace returns of
START_STICKY with START_NOT_STICKY and replace stopSelf() with
stopSelf(startId).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 849f03af-c8b1-4ac9-bb62-a4f316ce8da8

📥 Commits

Reviewing files that changed from the base of the PR and between d30c291 and 359f1bf.

📒 Files selected for processing (2)

• android/app/src/main/AndroidManifest.xml
• android/app/src/main/java/chat/rocket/reactnative/voip/VoipCallService.kt

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: ESLint and Test / run-eslint-and-test

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
Repo: RocketChat/Rocket.Chat.ReactNative PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T17:49:17.538Z
Learning: Applies to app/lib/services/voip/**/*.{ts,tsx} : Implement VoIP with WebRTC peer-to-peer audio calls in app/lib/services/voip/ using Zustand stores instead of Redux, with native CallKit (iOS) and Telecom (Android) integration; keep VoIP and VideoConf separate

📚 Learning: 2026-04-07T17:49:17.538Z

Learnt from: CR
Repo: RocketChat/Rocket.Chat.ReactNative PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T17:49:17.538Z
Learning: Applies to app/lib/services/voip/**/*.{ts,tsx} : Implement VoIP with WebRTC peer-to-peer audio calls in app/lib/services/voip/ using Zustand stores instead of Redux, with native CallKit (iOS) and Telecom (Android) integration; keep VoIP and VideoConf separate

Applied to files:

• android/app/src/main/AndroidManifest.xml
• android/app/src/main/java/chat/rocket/reactnative/voip/VoipCallService.kt

🔇 Additional comments (1)

android/app/src/main/AndroidManifest.xml (1)

150-155: LGTM — service declaration matches the foreground microphone use case.

The service is non-exported and declares the expected microphone foreground service type.

[diegolmello]

Code Review — Opus-Level Architecture Review

PR: #7199 — feat(android): create VoipCallService with FOREGROUND_SERVICE_TYPE_MICROPHONE
Files Reviewed: 2 (VoipCallService.kt, AndroidManifest.xml)
Total Issues: 3 (0 CRITICAL, 1 HIGH, 2 MEDIUM, 0 LOW)

---

Stage 1 — Spec Compliance

Acceptance Criterion	Status
VoipCallService.kt exists and compiles	PASS
Manifest declares service with foregroundServiceType=\"microphone\"	PASS
Manifest declares FOREGROUND_SERVICE_MICROPHONE permission	PASS
Service starts in foreground with notification	PASS
Service stops via stopSelf() correctly	PASS

All five acceptance criteria are satisfied.

---

Stage 2 — Code Quality

[HIGH] Race condition in isRunning flag on ACTION_START

File: VoipCallService.kt:65-70

if (!isRunning) {
    isRunning = true
    startForegroundWithNotification(callId)
} else {
    Log.d(TAG, \"Service already running, skipping duplicate start\")
}

The read of isRunning on line 65 and the write on line 66 are not atomic. If two ACTION_START intents arrive in quick succession — or if the service is recreated by the system between onStartCommand calls — the duplicate-start guard can be bypassed. Specifically, onCreate() resets isRunning = false, so a system-recreated instance would re-enter startForegroundWithNotification on the next ACTION_START.

Additionally, the isRunning flag lives in the companion object (JVM class-level state), meaning all instances of the service share the same flag. Android can instantiate the service multiple times between startForegroundService and onDestroy, making the flag unreliable as an instance-level guard.

Fix: Move the guard inside startForegroundWithNotification as a private instance field:

private var isForeground = false

private fun startForegroundWithNotification(callId: String) {
    if (isForeground) return
    isForeground = true
    // ... existing logic
}

Remove the companion object's isRunning field entirely.

---

[MEDIUM] getApplicationInfo().icon may not be the correct notification icon

File: VoipCallService.kt:131

.setSmallIcon(getApplicationInfo().icon)

This uses the app's main launcher icon. On Android 8+ (API 26+), notification icons must be monochrome (alpha-only). The launcher icon typically does not meet this requirement and will render as a grey silhouette on modern Android.

VoipNotification.kt:834-835 in the same package handles this correctly:

val smallIconResId = context.resources.getIdentifier(\"ic_notification\", \"drawable\", packageName)
// ...
setSmallIcon(smallIconResId)

Fix: Use the same resource lookup pattern as VoipNotification.kt, or reference a specific drawable resource by ID if ic_notification does not exist:

val smallIconResId = context.resources.getIdentifier(
    \"ic_notification\", \"drawable\", context.packageName
)
setSmallIcon(if (smallIconResId != 0) smallIconResId else getApplicationInfo().icon)

---

[MEDIUM] ACTION_STOP via startService is a no-op with an unnecessary service instantiation

File: VoipCallService.kt:50-56

@JvmStatic
fun stopService(context: android.content.Context) {
    val intent = Intent(context, VoipCallService::class.java).apply {
        action = ACTION_STOP
    }
    context.startService(intent)
}

When stopService is called and the service is not running, Android will still instantiate the service and call onCreate (which creates the notification channel), then onStartCommand with ACTION_STOP, then stopSelf(). This creates a brief, wasteful service lifecycle for a no-op.

Fix: Track service state externally and guard the call:

@JvmStatic
fun stopService(context: android.content.Context) {
    if (!isRunning) return
    val intent = Intent(context, VoipCallService::class.java).apply {
        action = ACTION_STOP
    }
    context.startService(intent)
}

(The isRunning flag in the companion object is already being used; it just needs to be moved out of the ACTION_START guard to be checked here too.)

---

Positive Observations

• API level guards are correct. FOREGROUND_SERVICE_TYPE_MICROPHONE gated behind Build.VERSION_CODES.Q (API 29+). FLAG_IMMUTABLE gated behind Build.VERSION_CODES.M (API 23+). Both match Android platform requirements.
• stopSelf() on ACTION_STOP is the correct self-managed shutdown pattern — no external coordination needed.
• onDestroy resets isRunning — prevents stale state if the service is force-killed and a pending intent is delivered.
• Notification channel uses IMPORTANCE_LOW — appropriate for a persistent service indicator that should not be intrusive.
• setOngoing(true) + setOnlyAlertOnce(true) — correct for a persistent call notification.
• Manifest service declaration is correct — enabled=\"true\", exported=\"false\", foregroundServiceType=\"microphone\".
• Pre-existing FOREGROUND_SERVICE_MICROPHONE permission at AndroidManifest.xml:17 — no regression.

---

Verdict: REQUEST CHANGES

The HIGH race condition is the blocking issue. The MEDIUM icon issue is worth fixing now for consistency. Once those two are addressed, this PR is ready to merge.

[diegolmello]

Follow-up review — partially dismissing the prior Opus review

Re: previous review. Re-evaluated each finding against the current tree and Android platform guarantees. Summary: one valid minor, one obsolete, one overstated.

[HIGH] isRunning race condition — overstated, not a bug

The review claims the read/write on isRunning at VoipCallService.kt:75-76 is non-atomic and that the service can be instantiated multiple times in parallel.

Platform guarantees contradict this:

• onStartCommand is invoked on the main thread (see Service docs). Back-to-back ACTION_START intents are serialized — no interleaved read/write is possible.
• Android guarantees at most one instance of a given Service class per process (Services overview). The "multiple instances share the companion flag" scenario does not occur.
• On process death the JVM class reloads and the companion field reinitializes to false — the explicit reset in onDestroy is belt-and-suspenders, not a correctness fix.

The companion-object flag is slightly ugly, but it is not a race. No change required.

[MEDIUM] Notification icon — valid, will address

getApplicationInfo().icon at line 125 resolves to the launcher icon, which on API 26+ is typically rendered as a grey silhouette because it isn't alpha-only. Sibling VoipNotification.kt already uses a ic_notification drawable which is monochrome-safe. Will switch to the same pattern.

[MEDIUM] ACTION_STOP via startService causing a no-op instantiation — obsolete

This finding was written against the original context.startService(intent) path. Commit 4d9feb2 (landed in response to the CodeRabbit review, before the Opus review was dismissed) already switched stopService() to context.stopService(intent), which does not instantiate the service when it isn't running. The cited code no longer exists.

Production risk

Independent of the review: VoipCallService has no caller in this PR. It's scaffolding for PR-4 in the VoIP Android series. Merging today has zero runtime effect on production — the service is declared in the manifest but never started.

Plan

1. Fix notification icon (cosmetic, one-line).
2. Optionally drop callId from Log.d on lines 74/104 (minor privacy hygiene).
3. Merge. Wiring lands in PR-4.