Android Push Notifications

Set up FCM and the CometChat Push Notifications SDK 2.0 on Android for message notifications with inline reply and call ringing.

​

What this guide covers

• FCM setup and the CometChat provider (credentials, Gradle, manifest).
• Initialising the Push Notifications SDK; the SDK registers and unregisters the device token itself.
• Message pushes: grouped notifications, inline reply, delivered receipts and taps, all handled by the SDK.
• Call pushes: ringing through the SDK’s calls module, with the app in any state.
• App icon badge count from the unreadMessageCount field.

​

How FCM and CometChat fit together

• Why FCM? Google issues device tokens and delivers raw push payloads to Android. You add google-services.json, the Messaging SDK and a FirebaseMessagingService so the device can receive pushes. The CometChat SDK never compiles against Firebase; you own it and hand payloads in.
• Why a CometChat provider? The Provider ID tells CometChat which FCM credentials to use when sending to your app. The SDK registers each device token against it on login.
• What the SDK does with a push. handlePushNotification parses the payload and, for type = chat, posts a grouped notification with inline reply and marks the message delivered; for type = call, the calls module rings the device. It returns false for pushes that are not CometChat’s, so your own handling can take over.

​

1. Prepare Firebase and CometChat

1. Firebase Console: Add your Android package, download google-services.json into the app module, and enable Cloud Messaging.

2. CometChat dashboard: Go to Notifications → Settings, enable Push Notifications, click Add Credentials (FCM), enter a Provider ID (a unique identifier you choose), and upload the Firebase service account JSON (Project settings → Service accounts → Generate new private key).

From the same screen, click Add Provider to upload the Firebase service account JSON. This is how you can Generate a new private key from Firebase:

3. App constants: note your CometChat App ID, Auth Key and Region, and the FCM Provider ID you chose. The Provider ID goes into PNConfiguration.setProviderId, and it is required: the SDK registers the device token under it, and without it no token is registered.

​

2. Add dependencies (Gradle)

Two CometChat artifacts, published in lockstep. The calls one is optional: add it to make incoming calls ring.

TOML (libs.versions.toml)

[versions]
minSdk = "26"           # the Calls SDK's floor; 24 for the core push artifact alone
compileSdk = "36"
targetSdk = "36"
cometChatSdk = "5.0.7"
cometChatCalls = "5.1.0"
cometChatPush = "2.0.0"
firebaseBom = "33.7.0"

[libraries]
cometchat-sdk = { group = "com.cometchat", name = "chat-sdk-android", version.ref = "cometChatSdk" }
cometchat-calls = { group = "com.cometchat", name = "calls-sdk-android", version.ref = "cometChatCalls" }
cometchat-push = { group = "com.cometchat", name = "push-notifications-android", version.ref = "cometChatPush" }
cometchat-push-calls = { group = "com.cometchat", name = "push-notifications-calls-android", version.ref = "cometChatPush" }
firebase-bom = { group = "com.google.firebase", name = "firebase-bom", version.ref = "firebaseBom" }
firebase-messaging = { group = "com.google.firebase", name = "firebase-messaging" }

Kotlin DSL (app/build.gradle.kts)

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

android {
    defaultConfig { minSdk = 26 }   // the Calls SDK's floor
}

dependencies {
    implementation(libs.cometchat.sdk)          // chat; optional for a calls-only app
    implementation(libs.cometchat.calls)        // needed with the calls module
    implementation(libs.cometchat.push)
    implementation(libs.cometchat.push.calls)   // only if you want incoming calls to ring

    implementation(platform(libs.firebase.bom))
    implementation(libs.firebase.messaging)
}

• Apply the google-services plugin and place google-services.json in the same module.
• minSdk: the calls module needs 26, the Calls SDK’s floor; the core artifact alone works from 24.
• compileSdk 36 and Android Gradle Plugin 8.9.1 or later: the Push Notifications SDK 2.0 depends on androidx.core 1.18, which requires them.
• The Chat SDK is optional for the push SDK: a calls-only app ships without it. Chat pushes are still shown without it; delivery receipts, inline reply and tap deep links need it.

​

3. Manifest permissions and services

<!-- Chat-only apps. With the calls module, this and the microphone and camera
     permissions already merge in from the Calls SDK and the calls module. -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

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

Everything else the ringer needs is declared by the SDK and merges in.

​

4. Initialise the SDK

In Application.onCreate, on every app start, after the Chat and Calls SDKs are initialised and before the user logs in. Token registration on login and logout only runs in a process where init ran. The configuration is also saved, so a push that wakes a killed app can still be shown before your code runs.

import com.cometchat.pushnotification.CometChatPushNotifications
import com.cometchat.pushnotification.PNConfiguration

val config = PNConfiguration.Builder(APP_ID, REGION)
    .setProviderId(PROVIDER_ID)                                   // the FCM provider you created
    .setNotificationSmallIcon(R.drawable.ic_notification)
    .setInlineReplyEnabled(true)                                  // default true; needs the Chat SDK
    .setAnswerActivity(CallAnswerActivity::class.java)            // calls: the screen opened on Answer
    .build()

CometChatPushNotifications.init(this, config)

Setter	Default	What it does
setProviderId(id)	none; required	Provider the device token is registered under. Without it no token is registered
setNotificationSmallIcon(res)	a system mail icon	Status-bar icon for chat notifications. Call notifications use the drawables cometchat_pn_ic_notification_call and cometchat_pn_ic_notification_call_missed; override those by name
setInlineReplyEnabled(bool)	true	Reply action on chat notifications
setAnswerActivity(Class)	none; required with the calls module	Opened when the user answers a call, with the call in its extras; it joins the session. See Join from the answer activity
setIncomingCallActivity(Class?)	the SDK’s screen	Your own incoming-call screen
setIncomingCallTheme(theme?)	none	Colours of the SDK’s incoming-call screen and call notifications, light and dark. Change it later with CometChatPushNotifications.setIncomingCallTheme(context, theme); see Theming the SDK’s incoming-call screen
setMissedCallActivity(Class?)	none	Opened when a missed-call notification is tapped
setDefaultRingTimeoutMs(ms), setShowMissedCallNotification(bool), setRequestCallPermissions(bool)	45 000, true, true	Ring behaviour; see Push Ringing

Deep links from chat notifications. Set the listener in Application.onCreate: a tap that starts a killed app is dropped if no listener is set yet.

CometChatPushNotifications.setOnNotificationTapListener(object : NotificationTapListener {
    override fun onNotificationTapped(context: Context, user: User?, group: Group?, message: BaseMessage?) {
        // Open the conversation with `user` or `group`; `message` is the tapped message when present
        context.startActivity(Intent(context, MessagesActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP
            user?.let { putExtra("user", Gson().toJson(it)) }
            group?.let { putExtra("group", Gson().toJson(it)) }
        })
    }
})

Suppress notifications for the chat that is on screen:

// In your messages screen
override fun onResume() { super.onResume(); CometChatPushNotifications.setCurrentOpenChatId(user?.uid ?: group?.guid) }
override fun onPause() { super.onPause(); CometChatPushNotifications.setCurrentOpenChatId(null) }

​

5. Hand every push to the SDK

class AppFCMService : FirebaseMessagingService() {

    override fun onMessageReceived(message: RemoteMessage) {
        val handled = CometChatPushNotifications.handlePushNotification(
            context = this,
            data = message.data,
            sentTimeMs = message.sentTime
        )
        if (!handled) { /* not a CometChat push: your own handling */ }
    }

    override fun onNewToken(token: String) {
        CometChatPushNotifications.handleTokenRefresh(token)
    }
}

• Pass sentTimeMs: Firebase holds pushes while a device dozes, and without it a late push rings for a call that is already over.
• Do not skip pushes while the app is in the foreground. The SDK suppresses a chat notification for the open chat itself (setCurrentOpenChatId), and a call push is the only signal that a call is coming in, in every app state.
• Call pushes must be sent at high FCM priority, or Android refuses the ringer’s foreground service and the process can die between the ring and the answer.

​

6. Tokens, login and logout

You do not register the device token. The SDK fetches it from Firebase and registers it when the user logs in, re-registers it when Firebase rotates it, and unregisters it on logout.

Log out of both the Chat SDK and the Calls SDK. Only a Calls SDK logout stops a call still ringing for the old user; a Chat SDK logout unregisters the token but leaves the ring and the Calls SDK session alone.

​

Permissions and ring readiness

After sign-in, check what could silence a notification or a ring. ensureRingReady asks for POST_NOTIFICATIONS itself on Android 13+ when it is missing. It is for apps with the calls module: a chat-only app always gets FSI_REVOKED on Android 14+, because only the calls module declares the full-screen-intent permission. A chat-only app should check the notification permission only.

CometChatPushNotifications.ensureRingReady(this) { result ->
    val readiness = result.valueOrNull() ?: return@ensureRingReady
    if (readiness != RingReadiness.READY) {
        // NOTIFICATIONS_OFF, CHANNEL_MUTED, FSI_REVOKED, DND_BLOCKING, MICROPHONE_DENIED
        CometChatPushNotifications.settingsIntentFor(this, readiness)?.let(::startActivity)
    }
}

​

7. Badge count

CometChat’s Enhanced Push Notification payload includes an unreadMessageCount field (a string) representing the total unread messages across all conversations for the logged-in user. You can use this to set the app icon badge and enrich local notifications.

​

7.1 Enable unread badge count on the CometChat Dashboard

1. Go to CometChat Dashboard → Notifications → Settings → Preferences → Push Notification Preferences.
2. Scroll to the bottom and enable the Unread Badge Count toggle.

This ensures CometChat includes the unreadMessageCount field in every push payload sent to your app.

​

7.2 Add the ShortcutBadger dependency

Add the ShortcutBadger library to your app-level build.gradle:

dependencies {
    implementation 'me.leolin:ShortcutBadger:1.1.22@aar'
}

​

7.3 Expected payload format

CometChat sends FCM data messages with this structure (relevant fields):

{
  "data": {
    "unreadMessageCount": "5",
    "title": "New Message",
    "alert": "John: Hello!",
    "conversationId": "user_abc123",
    "parentId": "176001", // Optional - parent message ID; sent only for threaded notifications
    "conversationType": "user"
  }
}

unreadMessageCount is a string representing the total unread messages across all conversations for the logged-in user.

​

7.4 Update the app badge from the push payload

The Push SDK posts the notification; the badge stays yours. In onMessageReceived, read unreadMessageCount from the same payload you hand to the SDK:

import me.leolin.shortcutbadger.ShortcutBadger

// Inside onMessageReceived, next to handlePushNotification:
val unreadCountStr: String? = message.data["unreadMessageCount"]
unreadCountStr?.toIntOrNull()?.let { count ->
    if (count >= 0) {
        ShortcutBadger.applyCount(applicationContext, count)
    } else {
        Log.w(TAG, "Invalid badge count: $count")
    }
} ?: Log.d(TAG, "No unreadMessageCount in payload")

ShortcutBadger uses launcher-specific APIs (Samsung, Huawei, Xiaomi, etc.) to display a badge number on the app icon. Passing 0 clears the badge.

​

7.5 Clear badge when the app opens

Clear the badge count when the app launches and every time it resumes from the background. Override onResume() in your main activity:

override fun onResume() {
    super.onResume()
    ShortcutBadger.removeCount(this)
}

This keeps the badge in sync with the actual unread state.

​

8. Message pushes

Handled by the SDK: one grouped notification per conversation with the sender’s name and avatar, an inline Reply action that sends the reply through the Chat SDK and refreshes the notification, a delivered receipt sent for the message, and a tap that calls your NotificationTapListener. Nothing to build; customise the small icon and the reply action through PNConfiguration.

To change the body text of a push before it is sent, set pushNotification in the message’s metadata:

val meta = JSONObject().put("pushNotification", "Custom notification body")
customMessage.metadata = meta
CometChat.sendCustomMessage(customMessage, object : CometChat.CallbackListener<CustomMessage>() { /* … */ })

​

9. Call pushes

Handled by the calls module: it shows a call-style notification with Answer and Decline and a full-screen screen over the lock screen, plays the ringtone, asks for the microphone and camera on Answer, opens your answer activity, sends declines and timeouts, and posts missed-call notifications.

Configuration, your own ring screen and theming are on Push Ringing. Starting and ending calls is on Ringing.

​

10. Testing checklist

1. Install on a physical device and grant notifications (Android 13+ needs POST_NOTIFICATIONS).
2. Log in so the SDK registers the push token.
3. Send a message from another user:
   • Foreground: a grouped notification shows unless that chat is open.
   • Background or killed: the tap opens the right conversation.
4. Inline reply from the shade delivers the message and updates the notification.
5. Call from another user:
   • The call-style notification and, on a locked phone, the full-screen screen appear with the caller’s name.
   • Answer opens the call screen and joins; Decline ends the ring and the caller sees “declined”.
   • Let it ring out: a missed-call notification appears and the caller sees “unanswered”.
   • Kill the app and call again: it still rings.
6. Log out and confirm no further pushes arrive; log in as another user and confirm theirs do.

​

Troubleshooting

Symptom	Quick checks
No notifications	Package name matches the Firebase app, google-services.json present, notification permission granted, Provider ID correct and Push Notifications enabled in the dashboard, user logged in (the token registers on login)
Pushes stop after a while	onNewToken not forwarded to handleTokenRefresh
Chat notification tap does nothing	setOnNotificationTapListener not set, or the activity’s launch mode drops extras
Calls do not ring	push-notifications-calls-android missing, setAnswerActivity not set, push sent at normal priority, or ensureRingReady not READY
Ringing continues after logout	Logged out of the Chat SDK only; log out of the Calls SDK too (CometChatCalls.logout)
Inline reply crashes	Do not strip FCM or RemoteInput classes in ProGuard/R8
Badge count not showing	Unread Badge Count enabled in the dashboard, ShortcutBadger added, launcher supports badges (Samsung, Huawei, Xiaomi)