Android

What this guide covers

Adding the push-notifications-android SDK and initializing it.
Wiring your own Firebase Messaging service to forward payloads to the SDK.
Requesting permission and registering the FCM token after login.
Letting the SDK render chat notifications (grouped, inline reply) and full-screen VoIP calls.
Handling notification taps and call events, and suppressing notifications for the open chat.
Testing and troubleshooting.

The push-notifications-android SDK replaces the previous approach of copying the UI Kit sample’s fcm/ and voip/ packages (FCMService, FCMMessageNotificationUtils, FCMMessageBroadcastReceiver, CometChatVoIP, CometChatVoIPConnectionService, and related helpers). Token registration, notification channels, stacking, avatars, inline reply, delivery receipts, the VoIP ConnectionService, the incoming-call screen, ring timeout, call-collision handling, and SDK auto-init on a killed-app wake are all handled inside the SDK. Your app keeps only a ~5-line Firebase Messaging service and three facade calls.

How it works

FCM’s role: Firebase issues the registration token and delivers the CometChat payload as a data message. The SDK does not depend on firebase-messaging — your app owns Firebase and passes the payload as a Map<String, String>.
CometChat’s role: The FCM provider you add in the dashboard binds your registered token to the logged-in user so CometChat can route pushes on your behalf.
The SDK’s role: CometChatPushNotifications parses the payload and decides chat vs call. Chat → builds/stacks notifications. Call → drives a full-screen incoming-call experience over an Android Telecom SELF_MANAGED ConnectionService (the same approach WhatsApp/Signal use — no READ_PHONE_STATE/ANSWER_PHONE_CALLS and no phone-account toggle in Settings).
Killed-app wake: When FCM starts your process, init() in Application.onCreate() runs first and stores your credentials; handlePushNotification(...) then auto-initializes the Chat SDK before routing, so calls connect even from a terminated state.

Prerequisites

The FCM provider, Firebase project, and google-services.json from Getting Started (this guide assumes those are done).
The CometChat Chat SDK / UI Kit already integrated (you call CometChatUIKit.init() / login() yourself).
minSdk 24+, compileSdk 36, Java 11, and a Gradle/AGP version matching your UI Kit project.
A physical device — background delivery and full-screen calls are unreliable on emulators.

Complete the Getting Started guide first — enable Push Notifications, add your FCM provider, and configure Firebase (google-services.json + service account JSON). This guide covers only the Android app wiring.

1. Add the dependency

Add the CometChat Maven repository (the same one that serves the Chat and Calls SDKs) in settings.gradle.kts:

settings.gradle.kts

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")
  }
}

Add the SDK plus your own Firebase Messaging dependency in the app module. Apply the google-services plugin so google-services.json is picked up:

app/build.gradle.kts

plugins {
  id("com.android.application")
  id("org.jetbrains.kotlin.android")
  id("com.google.gms.google-services")
}

dependencies {
  implementation("com.cometchat:push-notifications-android:1.0.0")

  // Your app owns Firebase — the SDK does not depend on it.
  implementation(platform("com.google.firebase:firebase-bom:34.15.0"))
  implementation("com.google.firebase:firebase-messaging")
}

You do not need to add notification, full-screen-intent, foreground-service, WAKE_LOCK, or MANAGE_OWN_CALLS permissions, or declare the incoming-call activity / VoIP services in your AndroidManifest.xml. The SDK’s manifest declares everything it needs and Gradle merges it into your app automatically.

2. Store your credentials

Keep the values from Getting Started where your app can read them:

AppCredentials.kt

object AppCredentials {
    const val APP_ID = "YOUR_APP_ID"
    const val REGION = "YOUR_REGION"
    const val AUTH_KEY = "YOUR_AUTH_KEY"
    const val FCM_PROVIDER_ID = "FCM-PROVIDER-ID"
}

3. Initialize the SDK

Initialize in Application.onCreate() so the SDK is ready before any push arrives (including killed-app wakes). Build the config with PNConfiguration.Builder(appId, region):

MyApplication.kt

import android.app.Application
import com.cometchat.pushnotification.CometChatPushNotifications
import com.cometchat.pushnotification.PNConfiguration

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize the CometChat UI Kit / Chat SDK first (your existing setup) …

        val config = PNConfiguration.Builder(AppCredentials.APP_ID, AppCredentials.REGION)
            .setNotificationSmallIcon(R.drawable.ic_notification)
            .setVoIPEnabled(true)
            .build()

        CometChatPushNotifications.init(this, config)
    }
}

Point <application android:name> at MyApplication in your manifest.

4. Forward FCM payloads to the SDK

Create your own FirebaseMessagingService. Forward each data message to handlePushNotification(...) and each token to handleTokenRefresh(...):

AppFCMService.kt

import com.cometchat.pushnotification.CometChatPushNotifications
import com.cometchat.pushnotification.models.PushPlatform
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class AppFCMService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        CometChatPushNotifications.handlePushNotification(this, data = message.data)
    }

    override fun onNewToken(token: String) {
        // Re-binds a rotated token when a user is logged in; no-op otherwise.
        CometChatPushNotifications.handleTokenRefresh(
            PushPlatform.FCM_ANDROID,
            token,
            AppCredentials.FCM_PROVIDER_ID,
        )
    }
}

AndroidManifest.xml

<service
    android:name=".AppFCMService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

handlePushNotification also accepts optional title, body, icon, uid, and guid overrides — pass uid/guid if you want to control the notification grouping key. For the default experience, just pass data.

5. Request permission and register the token

Request POST_NOTIFICATIONS (Android 13+) early using the SDK helper, and register the token after login so it binds to the session:

import com.cometchat.pushnotification.helpers.CometChatPNHelper

// In your entry activity, before/at login:
if (!CometChatPNHelper.hasNotificationPermission(this)) {
    CometChatPNHelper.requestNotificationPermission(this, REQUEST_CODE_NOTIFICATIONS)
}

import com.cometchat.pushnotification.CometChatPushNotifications
import com.cometchat.pushnotification.models.PushPlatform
import com.google.firebase.messaging.FirebaseMessaging

// After CometChatUIKit.login(...) succeeds:
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    CometChatPushNotifications.registerToken(
        PushPlatform.FCM_ANDROID,
        token,
        AppCredentials.FCM_PROVIDER_ID,
        onSuccess = { /* token registered */ },
        onError = { e -> /* log e */ },
    )
}

Unregister before logout so the device stops receiving pushes for that user:

CometChatPushNotifications.unregisterToken(
    onSuccess = { /* then CometChatUIKit.logout(...) */ },
    onError = { e -> /* log e */ },
)

6. Notification taps and call events

Suppress notifications for the chat that is currently open, and set the tap listener so you can navigate when a chat notification is tapped:

import com.cometchat.pushnotification.CometChatPushNotifications
import com.cometchat.pushnotification.listeners.NotificationTapListener

// When a chat screen opens (clear it on exit):
CometChatPushNotifications.setCurrentOpenChatId(conversationId)

CometChatPushNotifications.setOnNotificationTapListener(object : NotificationTapListener {
    override fun onNotificationTapped(
        context: Context,
        user: User?,
        group: Group?,
        message: BaseMessage?,
    ) {
        // Build your own Intent to open the conversation for `user` / `group`.
    }
})

By default the SDK shows its built-in full-screen incoming-call screen and launches the CometChat Calls UI on accept — you don’t need to write any call UI. Optionally, observe foreground call events to drive your own in-app UI:

import com.cometchat.pushnotification.listeners.CallEventListener
import com.cometchat.pushnotification.models.PNCallInfo

CometChatPushNotifications.setCallEventListener(object : CallEventListener {
    override fun onIncomingCall(callInfo: PNCallInfo) { /* callInfo.sessionId, callerName, callType … */ }
    override fun onCallCancelled(sessionId: String) { /* tear down UI */ }
})

To fully replace the built-in call screen with your own, set setOnIncomingCallHandler(...) (override the ringing screen) and/or setOnCallAnsweredHandler(...) (override the post-accept ongoing-call screen). The SDK still manages ringtone, ring timeout, and cleanup.

7. Badge count

CometChat’s Enhanced Push Notification payload includes an unreadMessageCount field (a string, total unread across all conversations). Enable it once on the dashboard: CometChat Dashboard → Notification Engine → Settings → Preferences → Push Notification Preferences → Unread Badge Count. Parse it from the payload and set the app-icon badge with a launcher badge library such as ShortcutBadger:

val count = message.data["unreadMessageCount"]?.toIntOrNull() ?: 0
ShortcutBadger.applyCount(applicationContext, count) // 0 clears the badge

Clear the badge when the app resumes (onResume of your main activity).

8. Testing checklist

Install on a physical device and grant notification + mic permissions (Android 13+ needs POST_NOTIFICATIONS).
Log in and confirm token registration succeeds (check the registerToken success callback / Logcat).
Send a message from another user:
- App open in a different chat: notification appears (grouped, with inline reply).
- App backgrounded/killed: notification appears; tapping opens the right conversation via onNotificationTapped.
- No notification for the chat currently open (via setCurrentOpenChatId).
Trigger an incoming CometChat call and confirm the full-screen call UI shows the caller with Accept/Decline, even on the lock screen; Accept joins the call, Decline rejects it.
Toggle Wi-Fi/cellular and reinstall to confirm token registration survives refreshes (onNewToken → handleTokenRefresh).

9. Troubleshooting

Symptom	Quick checks
No notifications received	Confirm `google-services.json` is in the app module, the package name matches Firebase, `POST_NOTIFICATIONS` is granted (Android 13+), and your `FirebaseMessagingService` calls `handlePushNotification(this, data = message.data)`.
Token registration errors	Verify `FCM_PROVIDER_ID` matches the dashboard exactly and that `registerToken` runs after `login` succeeds.
Nothing happens on a killed-app push	Ensure `CometChatPushNotifications.init(...)` runs in `Application.onCreate()` and `<application android:name>` points at your `Application` subclass.
Full-screen call UI not showing	Test on a physical device; on aggressive OEM skins (MIUI/Redmi/POCO), grant autostart/lock-screen/overlay permissions for the app.
Pushes stop after some time	Make sure `onNewToken` forwards to `handleTokenRefresh` (or re-`registerToken`) — FCM rotates tokens.

Overview

Platform Integrations

Settings

What this guide covers

How it works

Prerequisites

1. Add the dependency

2. Store your credentials

3. Initialize the SDK

4. Forward FCM payloads to the SDK

5. Request permission and register the token

6. Notification taps and call events

7. Badge count

8. Testing checklist

9. Troubleshooting

Resources

push-notifications-android

SDK source

​What this guide covers

​How it works

​Prerequisites

​1. Add the dependency

​2. Store your credentials

​3. Initialize the SDK

​4. Forward FCM payloads to the SDK

​5. Request permission and register the token

​6. Notification taps and call events

​7. Badge count

​8. Testing checklist

​9. Troubleshooting

​Resources

push-notifications-android

SDK source

What this guide covers

How it works

Prerequisites

1. Add the dependency

2. Store your credentials

3. Initialize the SDK

4. Forward FCM payloads to the SDK

5. Request permission and register the token

6. Notification taps and call events

7. Badge count

8. Testing checklist

9. Troubleshooting

Resources