+ Engage users beyond chat with real-time and scheduled notifications across Push, Email, and SMS. +
++ Keep users informed and connected with CometChat's robust notification system, designed to enhance user engagement and retention. +
+
+ Real-time alerts for new messages, calls, and events routed through FCM or APNs.
+ +Fallback emails sent only when a chat message stays unread beyond your configurable wait window.
+ +SMS fallbacks fire only when a chat message remains unread after your configurable wait window.
+ ++ Show working experiences just like Chat & Calling: clones, payloads, and end-to-end journeys. +
+ +
+
+
+This is a simple 3 step process where:
+
+1. You give a name to your project
+2. Add Google Analytics to your project (Optional)
+3. Configure Google Analytics account (Optional)
+
+Click on Create and you are ready to go.
+
+### Step 2: Add Firebase to your Android App
+
+1. Click on the Android icon as shown on the screen below.
+
+
+ 
+
+
+2. Register your Android app by providing the following details:
+
+ 1. Android Package name
+ 2. App nickname (optional)
+ 3. Debug signing certificate SHA-1 (optional)
+
+
+ 
+
+
+3. Download the `google-services.json` file and place it in the required location in your project.
+
+
+ 
+
+
+4. Add Firebase SDK by copying and pasting the snippets in the Project-level `build.gradle` file.
+
+
+ 
+
+
+5. Add Firebase SDK by copying and pasting the snippets in the App-level `build.gradle` file.
+
+
+ 
+
+
+6. Click on 'Continue to Console' to finish the setup.
+
+### Step 3: Download the service account file
+
+
+ 
+
+
+## Extension settings
+
+### Step 1: Enable the extension
+
+1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
+2. Go to the Extensions section and Enable the Push Notifications extension.
+3. Open the settings for this extension and save the following.
+
+
+ 
+
+
+### Step 2: Save your settings
+
+On the Settings page you need to enter the following:
+
+1. **Set extension version**
+
+* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
+* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
+* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
+
+2. **Select the platforms that you want to support**
+
+* Select from Web, Android, Ionic, React Native, Flutter & iOS.
+
+3. **Notification payload settings**
+
+* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
+
+4. **Push payload message options**
+
+
+ 
+
+
+The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+
+* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+
+5. **Notification Triggers**
+
+
+ 
+
+
+* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+
+ 1. Message Notifications
+ 2. Call Notifications
+ 3. Group Notifications
+
+* These are pretty self-explanatory and you can toggle them as per your requirement.
+
+## Android App Setup
+
+In the Firebase Project setup, we did the following things:
+
+1. Added google-services.json file to the project.
+2. Added the required Firebase SDK snippets to the Project-level build.grade file.
+3. Added the required Firebase SDK snippets to the App-level build.gradle file.
+
+If you want more details, check the [Firebase Documentation](https://firebase.google.com/docs/cloud-messaging/android/client).
+
+### Step 1: Register the FCM Token on user login
+
+1. Initialize CometChat and then login your user.
+2. On successful login, you can register the obtained FCM Token using `CometChat.registerTokenForPushNotification()` function call. (You can see the process of getting the FCM Token in the next step)
+
+
+
+
+**Step 1. Process push notification payload and grab BaseMessage object**
+
+To open a chat view, firstly you will need a BaseMessage object. You can grab this from the push notification payload received in `onMessageReceived(RemoteMessage message)`. You need to call `CometChat.processMessage()` method to process push notification payload.
+
+
-
-
-This is a simple 3 step process where:
-
-1. You give a name to your project
-2. Add Google Analytics to your project (Optional)
-3. Configure Google Analytics account (Optional)
-
-Click on Create and you are ready to go.
-
-### Step 2: Add Firebase to your Android App
-
-1. Click on the Android icon as shown on the screen below.
-
-
-
-
+- FCM setup and CometChat provider wiring (credentials + Gradle + manifest).
+- Token registration/unregistration so CometChat routes pushes correctly.
+- Handling message pushes with grouped notifications and inline reply.
+- Handling call pushes with `ConnectionService` for native telecom UI.
+- Deep links/navigation from notifications and payload customization.
-2. Register your Android app by providing the following details:
+{/* ## What you need first
- 1. Android Package name
- 2. App nickname (optional)
- 3. Debug signing certificate SHA-1 (optional)
+- Firebase project with an Android app added, `google-services.json` downloaded, and Cloud Messaging enabled.
+- CometChat App ID, Region, Auth Key; **Push Notifications** enabled with an **FCM Android provider** and its Provider ID.
+- Android device with Play Services (sample uses `minSdk 26` because of `ConnectionService`).
+- Latest CometChat UI Kit + Calls SDK dependencies (see Gradle tabs below). */}
-
-
-
+## How FCM and CometChat fit together
-3. Download the `google-services.json` file and place it in the required location in your project.
+- **Why FCM?** Google issues device tokens and delivers raw push payloads to Android. You must add `google-services.json`, the Messaging SDK, and a service receiver (`FCMService`) so the device can receive pushes.
+- **Why a CometChat provider?** The Provider ID tells CometChat which FCM credentials to use when sending to your app. Without registering tokens against this ID, CometChat cannot target your device.
+- **Token registration bridge:** The app retrieves the FCM token and calls `CometChatNotifications.registerPushToken(pushToken, PushPlatforms.FCM_ANDROID, providerId, …)`. That binds the token to your logged-in user so CometChat can route message/call pushes to FCM on your behalf.
+- **Payload handling:** When FCM delivers a push, your `FCMService`/`FCMMessageBroadcastReceiver` parses CometChat’s payload, shows notifications (grouped, inline reply), and forwards intents to your activities. For calls, `CometChatVoIPConnectionService` surfaces a telecom-grade UI and uses the same payload to accept/reject server-side.
+- **Dashboard ↔ app contract:** The Provider ID in `AppConstants.FCMConstants.PROVIDER_ID` must match the dashboard provider you created. The package name in Firebase and the `applicationId` in Gradle must match, or FCM will reject the token.
-
-
-
+## 1. Prepare Firebase and CometChat
-4. Add Firebase SDK by copying and pasting the snippets in the Project-level `build.gradle` file.
+1. **Firebase Console**: Add your Android package, download `google-services.json` into the app module, and enable Cloud Messaging.
-
+ 
-5. Add Firebase SDK by copying and pasting the snippets in the App-level `build.gradle` file.
+2. **CometChat dashboard**: Go to **Notifications → Settings**, enable **Push Notifications**, click **Add Credentials** (FCM), upload the Firebase service account JSON (Project settings → Service accounts → Generate new private key), and copy the Provider ID.
-
+ 
-6. Click on 'Continue to Console' to finish the setup.
-
-### Step 3: Download the service account file
+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:
-
+ 
-## Extension settings
-
-### Step 1: Enable the extension
-
-1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
-2. Go to the Extensions section and Enable the Push Notifications extension.
-3. Open the settings for this extension and save the following.
-
-
-
-
+3. **App constants**:
+Note down your CometChat App ID, Auth Key, and Region from the CometChat dashboard and keep them available to be added to your project's AppCrendentials.kt.
+Similarly, note the FCM Provider ID generated in the CometChat dashboard and add the same in your AppConstants.kt; this will be when registering the FCM token with CometChat.
-### Step 2: Save your settings
+## 2. Add dependencies (Gradle)
-On the Settings page you need to enter the following:
+Use a version catalog and aliases (Update `applicationId`, package names, icons, and app name.). Also, if you are new to CometChat, please review the Maven repositories and related setup requirements before proceeding.
-1. **Set extension version**
+
-
+- Permissions cover notifications + telecom; services/receiver wire Firebase delivery (`FCMService`), notification actions (`FCMMessageBroadcastReceiver`), and telecom UI (`CometChatVoIPConnectionService`). Point `android:name` to your `MyApplication`.
-The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+- Set `android:name` on `
-
+**What the core pieces do**
-* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+- `FCMService` – receives FCM data/notification messages, parses CometChat payload, and hands off to `FCMMessageBroadcastReceiver`.
+- `FCMMessageBroadcastReceiver` – builds grouped notifications, inline reply actions, and routes taps/deeplinks to your `HomeActivity`.
+- `Repository.registerFCMToken` – fetches the FCM token and registers it with CometChat using `AppConstants.FCMConstants.PROVIDER_ID`; call after login.
+- `Repository.acceptCall/rejectCall/rejectCallWithBusyStatus` – performs server-side call actions so the caller sees the correct state even if your UI is backgrounded.
+- `MyApplication` – initializes UIKit, manages websocket connect/disconnect, tracks foreground state, and shows/dismisses incoming call overlays.
+- `CometChatVoIPConnectionService` – handles Android telecom integration so call pushes display a system-grade incoming call UI and cleanly end/busy on reject.
- 1. Message Notifications
- 2. Call Notifications
- 3. Group Notifications
+**Splash/entry deep link handler** (adapt activity targets):
-* These are pretty self-explanatory and you can toggle them as per your requirement.
+```kotlin lines
+// In your Splash/entry activity (e.g., SplashActivity)
+override fun onCreate(savedInstanceState: Bundle?) {
+ super.onCreate(savedInstanceState)
+ handleDeepLinking()
+}
-## Android App Setup
+private fun handleDeepLinking() {
+ NotificationManagerCompat.from(this)
+ .cancel(AppConstants.FCMConstants.NOTIFICATION_GROUP_SUMMARY_ID)
-In the Firebase Project setup, we did the following things:
+ val notificationType = intent.getStringExtra(AppConstants.FCMConstants.NOTIFICATION_TYPE)
+ val notificationPayload = intent.getStringExtra(AppConstants.FCMConstants.NOTIFICATION_PAYLOAD)
-1. Added google-services.json file to the project.
-2. Added the required Firebase SDK snippets to the Project-level build.grade file.
-3. Added the required Firebase SDK snippets to the App-level build.gradle file.
+ startActivity(
+ Intent(this, HomeActivity::class.java).apply {
+ putExtra(AppConstants.FCMConstants.NOTIFICATION_TYPE, notificationType)
+ putExtra(AppConstants.FCMConstants.NOTIFICATION_PAYLOAD, notificationPayload)
+ }
+ )
+ finish()
+}
+```
-If you want more details, check the [Firebase Documentation](https://firebase.google.com/docs/cloud-messaging/android/client).
+This reads the push extras, clears the summary notification, and forwards the payload to `HomeActivity` so taps or deep links land in the right screen.
-### Step 1: Register the FCM Token on user login
+**SplashViewModel (init UIKit + login check)**
-1. Initialize CometChat and then login your user.
-2. On successful login, you can register the obtained FCM Token using `CometChat.registerTokenForPushNotification()` function call. (You can see the process of getting the FCM Token in the next step)
+```kotlin lines
+class SplashViewModel : ViewModel() {
+ private val loginStatus = MutableLiveData
-
+- For `type == "call"`, `FCMService.handleCallFlow` parses [`FCMCallDto`](https://github.com/cometchat/cometchat-uikit-android/blob/v5/sample-app-kotlin%2Bpush-notification/src/main/java/com/cometchat/sampleapp/kotlin/fcm/fcm/FCMCallDto.kt) and routes to the `voip` package.
+- [`CometChatVoIP`](https://github.com/cometchat/cometchat-uikit-android/blob/v5/sample-app-kotlin%2Bpush-notification/src/main/java/com/cometchat/sampleapp/kotlin/fcm/voip/CometChatVoIP.kt) registers a `PhoneAccount` and triggers `TelecomManager.addNewIncomingCall` for native full-screen UI with Accept/Decline.
+- Busy logic: if already on a call, reject with busy (`Repository.rejectCallWithBusyStatus`). Cancel/timeout pushes end the active telecom call when IDs match.
+- Runtime VoIP checks: before handling call pushes, request `READ_PHONE_STATE`, `MANAGE_OWN_CALLS`, and `ANSWER_PHONE_CALLS` at runtime and ensure the phone account is enabled (`CometChatVoIP.hasEnabledPhoneAccountForVoIP`).
+- Foreground suppression: the sample ignores VoIP banners if `MyApplication.isAppInForeground()` is true; keep or remove based on your UX.
+- Cancel/unanswered handling: on `callAction` of `cancelled`/`unanswered`, end the active telecom call if the session IDs match.
-**Step 1. Process push notification payload and grab BaseMessage object**
+## 10. Customize notification text or parse payloads
-To open a chat view, firstly you will need a BaseMessage object. You can grab this from the push notification payload received in `onMessageReceived(RemoteMessage message)`. You need to call `CometChat.processMessage()` method to process push notification payload.
+Parse the push into a `BaseMessage` for deep links:
-
+
+
+#### How does it work?
+
+For one-on-one events, the custom provider fires once per recipient. For group events, it fires once per member so you receive one HTTP request per user who should be notified.
+
+Example: if a group has 100 members, your webhook receives 100 POSTs—one for each member.
+
+#### Payload reference
+
+Every request includes `trigger: "push-notification-payload-generated"` and `webhook: "custom"`. The notification content lives in `data.notificationDetails`; use that to decide how you deliver the push.
+
+Below are sample payloads for different events:
+
+
+
+
+## How delivery works
+
+For one-on-one events, CometChat calls your webhook once per recipient. For group events, it calls once per member—one HTTP request per user to notify.
+
+Example: if a group has 100 members, your webhook receives 100 POSTs.
+
+
1. Login to [CometChat](https://app.cometchat.com/login) dashboard and select your app.
-2. Navigate to **Notifications** > **Notifications** in the left-hand menu.
+2. Navigate to **Notifications** > **Settings** in the left-hand menu.
3. Enable Email notifications feature.
-### Save the SendGrid credentials
+### 6. Save the SendGrid credentials
@@ -391,7 +396,7 @@ The domain used in Sender's Email needs to be Authenticated. Refer to SendGrid's
-### Save user's timezone
+### 7. Save user timezones
A user's timezone is required to allow them to set a schedule for receiving notifications. In case the timezone is not registered, the default timezone for
@@ -414,7 +419,7 @@ This functionality is available in the following SDK versions:
-### Receive notifications
+### 8. Receive notifications
@@ -422,7 +427,7 @@ This functionality is available in the following SDK versions:
Send a message to any user and keep the conversation unread for the designated amount of time to receive an email notification.
-### Configure email replies
+### 9. Configure email replies (optional)
In the SendGrid provider settings, enable the email replies. Optionally, you can set a different sender's email address. Only ensure that the it doesn't contain any "+" symbol in it.
@@ -435,212 +440,21 @@ Before saving the Inbound Host and URL:
Once this setup is successful, users will be able to reply to an email notification and send messages in a particular conversation on CometChat. The parsing of the replies is heavily dependent on the Email client used and the content of the reply.
-## Custom Email provider
-
-Custom provider allows you to make use of providers apart from SendGrid for triggering Email notifications. This is implemented using webhook URL which gets all the required details that can be used to trigger Email notifications.
-
-#### Pre-requisite
-
-1. Your webhook endpoint must be accessible over `HTTPS`. This is essential to ensure the security and integrity of data transmission.
-2. This URL should be publicly accessible from the internet.
-3. Ensure that your endpoint supports the `HTTP POST` method. Event payloads will be delivered via `HTTP POST` requests in `JSON` format.
-4. Configure your endpoint to respond immediately to the CometChat server with a 200 OK response. The response should be sent within 2 seconds of receiving the request.
-5. For security, it is recommended to set up Basic Authentication that is usually used for server-to-server calls. This requires you to configure a username and password. Whenever your webhook URL is triggered, the HTTP Header will contain:
-
-```html
-Authorization: Basic
-
-
-#### How does it work?
-
-The Custom provider is triggered once for an event in one-on-one conversation. In case of notifying the members of a group, the custom provider is triggered once for each user present in that group.
-
-For example, if there are 100 members in the group, your webhook will receive 100 HTTP requests. Once for each member of the group.
-
-
+
+
+## Delivery preferences
+
+- **Notify for unread messages only** (default: on). When enabled, send only if the conversation has unread messages.
+- **Wait time before sending the next notification (per conversation, minutes)**: default 120; min 1; max 1440.
+- **Maximum emails per day**: default 20.
+- **Maximum emails per conversation per day**: default 2.
+- **Override**: when enabled, end users can change these settings in clients that expose preferences.
+
+## Email payload options
+
+All toggles default to off; enable per your privacy/performance needs.
+- **Include entire message object in payload**
+- **Include message metadata in payload**
+- **Include sender's metadata in payload**
+- **Include receiver's metadata in payload**
diff --git a/notifications/email-templates.mdx b/notifications/email-templates.mdx
new file mode 100644
index 00000000..664d38bd
--- /dev/null
+++ b/notifications/email-templates.mdx
@@ -0,0 +1,109 @@
+---
+title: "Email Templates"
+---
+
+Design the subject/body your users see in unread-message emails. No sounds apply to email. Providers like SendGrid can consume these fields—map them into Dynamic Template variables or assemble the subject/body in your service before sending.
+
+## What to customize
+
+- **Subjects and bodies** for 1:1 and group emails (default vs privacy-friendly).
+- **Preview content** from `messages[]` (unread list) and `senderDetails`/`groupDetails`.
+- **Deep links** back to the conversation (add in your provider template).
+
+## Payload shapes
+
+Field meanings:
+- `to`: recipient identifiers and optional email.
+- `messages[]`: the unread messages that triggered the notification (use for counts and previews).
+- `senderDetails`: most recent sender; map to subjects or hero text.
+- `groupDetails`: only present for group conversations.
+- `subject`: ready-to-use subject if you do not build it in the provider.
+
+### One-on-one
+```json
+{
+ "to": { "uid": "customer-123", "email": "andrew@example.com", "name": "Andrew Joseph" },
+ "messages": [
+ {
+ "sender": { "uid": "agent-42", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-4.webp", "name": "Susan Marie" },
+ "message": "Are we meeting this weekend?",
+ "messageObject": { "category": "message", "type": "text" }
+ },
+ {
+ "sender": { "uid": "agent-42", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-4.webp", "name": "Susan Marie" },
+ "message": "📷 Has shared an image"
+ }
+ ],
+ "senderDetails": { "uid": "agent-42", "name": "Susan Marie", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-4.webp" },
+ "subject": "New messages from Susan Marie"
+}
+```
+
+### Group
+```json
+{
+ "to": { "uid": "customer-123", "name": "Andrew Joseph" },
+ "messages": [
+ { "sender": { "uid": "mod-5", "name": "John Paul" }, "message": "Hello all! What's up?" },
+ { "sender": { "uid": "agent-42", "name": "Susan Marie" }, "message": "This is the place I was thinking about" }
+ ],
+ "groupDetails": { "guid": "community-1", "name": "Hiking Group" },
+ "subject": "New messages in Hiking Group"
+}
+```
+
+## Subject examples
+
+You can use the provided `subject` field or build your own using `senderDetails.name` and `groupDetails.name`. Here are default and privacy-focused subject templates:
+
+
+ 
+
+
+| Use case | Default subject | Privacy subject | Example result (default) |
+| --- | --- | --- | --- |
+| One-on-one notification | New messages from `{{senderDetails.name}}` | New messages from `{{senderDetails.name}}` | New messages from Susan Marie |
+| Group notification | New messages in `{{groupDetails.name}}` | New messages in `{{groupDetails.name}}` | New messages in Hiking Group |
+
+## Tips
+
+- Keep privacy variants generic to avoid leaking message content.
+- Use `messages[0].message` for a short preview; use the length for unread counts.
+- If you use SendGrid Dynamic Templates, map the payload into `dynamic_template_data` (subject, recipient name, sender name, unread count, preview, and the `messages` array).
+
+{/* ## Example: using with SendGrid API
+
+Pass payload fields into a SendGrid Dynamic Template. The template can reference variables like `{{subject}}`, `{{recipientName}}`, `{{previewMessage}}`, and loop over `messages`.
+
+```js
+import sgMail from '@sendgrid/mail';
+sgMail.setApiKey(process.env.SENDGRID_API_KEY);
+
+// payload from CometChat
+const payload = {
+ to: { email: 'andrew@example.com', name: 'Andrew Joseph' },
+ senderDetails: { name: 'Susan Marie' },
+ messages: [
+ { message: 'Are we meeting this weekend?' },
+ { message: '📷 Has shared an image' }
+ ],
+ subject: 'New messages from Susan Marie'
+};
+
+// Map payload into template data
+const msg = {
+ to: payload.to.email,
+ from: 'no-reply@yourdomain.com',
+ templateId: 'YOUR_DYNAMIC_TEMPLATE_ID',
+ dynamic_template_data: {
+ subject: payload.subject,
+ recipientName: payload.to.name,
+ senderName: payload.senderDetails.name,
+ unreadCount: payload.messages.length,
+ previewMessage: payload.messages[0]?.message || '',
+ messages: payload.messages
+ }
+};
+
+await sgMail.send(msg);
+``` */}
diff --git a/notifications/flutter-push-notifications-android.mdx b/notifications/flutter-push-notifications-android.mdx
new file mode 100644
index 00000000..d55a908e
--- /dev/null
+++ b/notifications/flutter-push-notifications-android.mdx
@@ -0,0 +1,211 @@
+---
+title: "Flutter Push Notifications (Android)"
+description: "CometChat push notifications in Flutter apps on Android using Firebase Cloud Messaging (FCM)."
+---
+
+
+
+
+2. Click **Add Credentials**, choose **FCM**, upload the Firebase service account JSON (Firebase → Project settings → Service accounts → Generate new private key), and copy the Provider ID.
+
+
+
+
+
+Keep the provider ID—you’ll use it in `AppCredentials.fcmProviderId`.
+
+## 2. Prepare Firebase and credentials
+
+### 2.1 Firebase Console
+
+1. Register your Android package name (the same as `applicationId` in `android/app/build.gradle`) and download `google-services.json` into `android/app`.
+2. Enable Cloud Messaging and copy the Server key if you want to send test messages manually.
+
+
+
+
+
+### 2.3 Local configuration file
+
+Update [`lib/app_credentials.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/app_credentials.dart) so it exposes your credentials and provider IDs:
+
+```dart lines
+class AppCredentials {
+ static String _appId = "YOUR_APP_ID";
+ static String _authKey = "YOUR_AUTH_KEY";
+ static String _region = "YOUR_REGION";
+ static String _fcmProviderId = "FCM-PROVIDER-ID";
+}
+```
+
+The sample persists these values to `SharedPreferences`; `saveAppSettingsToNative()` passes them to Android so `CallActionReceiver` can reject calls even if Flutter is not running.
+
+## 3. Bring the notification stack into Flutter
+
+### 3.1 Copy [`lib/notifications`](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app_push_notifications/lib/notifications)
+
+- Clone or download the sample once.
+- Copy the entire `lib/notifications` directory (models, Android/iOS services, helpers) into your app.
+- Update the import prefixes (for example replace `package:sample_app_push_notifications/...` with your own package name). Keeping the same folder names avoids manual refactors later.
+
+### 3.2 Wire the entry points
+
+**[`lib/main.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/main.dart)**
+
+- Initialize `SharedPreferencesClass`, `FlutterLocalNotificationsPlugin`, and Firebase before calling `runApp`.
+- Cache `NotificationLaunchHandler.pendingNotificationResponse` when the app is launched from a tapped notification while terminated.
+- Keep the `callMain` entrypoint; `CallActivity` uses it to render the ongoing-call UI over the lock screen.
+
+**[`lib/guard_screen.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/guard_screen.dart) / [`lib/dashboard.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/dashboard.dart) (or your first screen after login)**
+
+- Ensure `CometChatUIKit.init()` and `CometChatUIKit.login()` finish before rendering the dashboard.
+- On Android, instantiate `FirebaseService` and call `notificationService.init(context)` once; on iOS, keep `APNSService`.
+- Replay `NotificationLaunchHandler.pendingNotificationResponse` after the widget tree builds so taps from a killed app still navigate to `MessagesScreen`.
+- Forward lifecycle changes to `IncomingCallOverlay` / `BoolSingleton` to hide stale overlays when the app resumes.
+- `VoipNotificationHandler.handleNativeCallIntent(context)` runs after the first frame to act on accept/decline actions that were tapped from the Android notification before Flutter started.
+
+### 3.3 Align dependencies and configuration
+
+Mirror the sample `pubspec.yaml` versions (update as needed when newer releases ship):
+
+```yaml lines
+dependencies:
+ firebase_core: ^3.9.0
+ firebase_messaging: ^15.1.6
+ flutter_local_notifications: ^18.0.0
+ flutter_callkit_incoming:
+ path: ../sample_app_push_notifications/flutter_callkit_incoming
+ cometchat_chat_uikit: ^5.2.5
+ cometchat_calls_uikit: ^5.0.11
+ permission_handler: ^11.3.1
+ shared_preferences: ^2.2.1
+```
+
+Run `flutter pub get`, then `flutterfire configure` if you still need to generate `firebase_options.dart`.
+
+## 4. Configure the native Android layer
+
+### 4.1 Gradle + Firebase
+
+1. Add `google-services.json` to `android/app`.
+2. Ensure `android/app/build.gradle` applies the plugins used in the sample:
+
+```gradle lines
+plugins {
+ id "com.android.application"
+ id "com.google.gms.google-services"
+ id "kotlin-android"
+ id "dev.flutter.flutter-gradle-plugin"
+}
+```
+
+Set `applicationId` to your package name and keep `minSdk 24` or higher. `compileSdk 36` / `targetSdk 35` match the sample but can be raised if your project already targets a newer API.
+
+### 4.2 Manifest permissions and components
+
+Use the sample [`AndroidManifest.xml`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/android/app/src/main/AndroidManifest.xml) as a baseline:
+
+- Permissions for notifications, audio/video, and lock-screen call UI: `POST_NOTIFICATIONS`, `RECORD_AUDIO`, `CAMERA`, `FOREGROUND_SERVICE`, `USE_FULL_SCREEN_INTENT`, `WAKE_LOCK`, `SHOW_WHEN_LOCKED`, `TURN_SCREEN_ON`, and `SYSTEM_ALERT_WINDOW`.
+- `MainActivity` uses `launchMode="singleTask"` with `android:showWhenLocked="true"` / `android:turnScreenOn="true"` so incoming calls can wake the screen.
+- `CallActivity` is a dedicated entrypoint (uses `callMain`) to render the ongoing call over the lock screen and is excluded from recents.
+- `CallActionReceiver` listens to `flutter_callkit_incoming` actions (and mirrored app-specific actions) so Accept/Decline from the native notification reach Flutter.
+- Set `default_notification_icon` meta-data to your icon if you change the launcher asset.
+
+### 4.3 Kotlin bridge for call intents
+
+- [`MainActivity.kt`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/android/app/src/main/kotlin/com/cometchat/sampleapp/flutter/android/MainActivity.kt) exposes a `MethodChannel("com.cometchat.sampleapp")` that supports:
+ - `get_initial_call_intent` – read and clear any call intent extras so `VoipNotificationHandler.handleNativeCallIntent` in Dart can react after Flutter launches.
+ - `setupLockScreenForCall` / `restoreLockScreenAfterCall` – temporarily bypass and then restore the lock screen when a call is accepted.
+ - `saveAppSettings` – stores your App ID and Region for the broadcast receiver.
+- [`CallActionReceiver.kt`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/android/app/src/main/kotlin/com/cometchat/sampleapp/flutter/android/CallActionReceiver.kt) wakes the app for Accept/Decline actions. On decline, it can initialize the CometChat SDK headlessly (using the saved App ID/Region) to reject the call as busy even if Flutter is not running.
+- [`CallActivity.kt`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/android/app/src/main/kotlin/com/cometchat/sampleapp/flutter/android/CallActivity.kt) overrides `getDartEntrypointFunctionName` to `callMain`, letting the ongoing-call UI render in its own activity with lock-screen flags.
+
+If you change the MethodChannel name in Kotlin, update `voipPlatformChannel` inside [`lib/notifications/services/save_settings_to_native.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/notifications/services/save_settings_to_native.dart) to match.
+
+## 5. Token registration and runtime events
+
+### 5.1 FCM tokens
+
+`FirebaseService.init` requests notification permission, sets the background handler (`firebaseMessagingBackgroundHandler`), and registers tokens:
+
+```dart lines
+final token = await FirebaseMessaging.instance.getToken();
+if (token != null) {
+ PNRegistry.registerPNService(token, true, false); // platform: FCM_FLUTTER_ANDROID
+}
+FirebaseMessaging.instance.onTokenRefresh.listen(
+ (token) => PNRegistry.registerPNService(token, true, false),
+);
+```
+
+`PNRegistry` pulls the provider ID from `AppCredentials.fcmProviderId`. Call this only after `CometChatUIKit.login` succeeds.
+
+### 5.2 Local notifications and navigation
+
+- `LocalNotificationService.showNotification` renders a high-priority local notification when the incoming CometChat message does not belong to the currently open conversation.
+- `NotificationLaunchHandler.pendingNotificationResponse` caches taps triggered while the app is terminated; `dashboard.dart` replays it after navigation is ready.
+- `LocalNotificationService.handleNotificationTap` fetches the user/group and pushes `MessagesScreen` when a notification is tapped from foreground, background, or terminated states.
+
+### 5.3 Call events (VoIP-like pushes)
+
+- The top-level `firebaseMessagingBackgroundHandler` shows the incoming-call UI by calling `VoipNotificationHandler.displayIncomingCall`, which uses `flutter_callkit_incoming` to render a full-screen notification.
+- `FirebaseService.initializeCallKitListeners` binds `FlutterCallkitIncoming.onEvent` so Accept/Decline/Timeout actions map to `VoipNotificationHandler.acceptVoipCall`, `declineVoipCall`, or `endCall`.
+- `VoipNotificationHandler.handleNativeCallIntent` reads Accept/Decline extras passed from `CallActionReceiver` via the MethodChannel if the user acted before Flutter started.
+- `saveAppSettingsToNative()` runs during `FirebaseService.init` to persist App ID/Region for the native receiver; keep it in place or `CallActionReceiver` cannot initialize CometChat when rejecting a call from the lock screen.
+
+## 6. Testing checklist
+
+1. Run on a physical Android device. Grant notification, microphone, and camera permissions when prompted (Android 13+ requires `POST_NOTIFICATIONS`).
+2. Send a message from another user:
+ - Foreground: a local notification banner shows (unless you are in that chat).
+ - Background: FCM notification appears; tapping opens the right conversation.
+3. Force-quit the app, send another message push, tap it, and confirm `NotificationLaunchHandler` launches `MessagesScreen`.
+4. Trigger an incoming CometChat call. Ensure:
+ - The full-screen call UI shows caller name/type with Accept/Decline.
+ - Accepting on the lock screen notifies Flutter (`handleNativeCallIntent`), starts the call session, and dismisses the native UI when the call ends.
+ - Declining from the notification triggers `CallActionReceiver` to reject the call server-side.
+5. Rotate through Wi-Fi/cellular and reinstall the app to confirm token registration works after refresh events.
+
+## 7. Troubleshooting tips
+
+| Symptom | Quick checks |
+| --- | --- |
+| No notifications received | Confirm `google-services.json` is in `android/app`, the package name matches Firebase, and notification permission is granted (Android 13+). |
+| Token registration errors | Double-check `AppCredentials.fcmProviderId` and that `PNRegistry.registerPNService` runs after login. |
+| Call actions never reach Flutter | Ensure `CallActionReceiver` is declared in the manifest, MethodChannel names match `voipPlatformChannel`, and `VoipNotificationHandler.handleNativeCallIntent` is called from `dashboard.dart`. |
+| Full-screen call UI not showing | Verify `USE_FULL_SCREEN_INTENT`, `WAKE_LOCK`, and `SHOW_WHEN_LOCKED` permissions plus `android:showWhenLocked="true"` / `android:turnScreenOn="true"` on `MainActivity` and `CallActivity`. |
+| Tapping notification from killed app does nothing | Keep the `NotificationLaunchHandler` logic in `main.dart` and replay it after the navigator key is ready (post-frame callback). |
diff --git a/notifications/flutter-push-notifications-ios.mdx b/notifications/flutter-push-notifications-ios.mdx
new file mode 100644
index 00000000..bd262cde
--- /dev/null
+++ b/notifications/flutter-push-notifications-ios.mdx
@@ -0,0 +1,235 @@
+---
+title: "Flutter Push Notifications (iOS)"
+description: "CometChat push notifications in Flutter apps on iOS using Apple Push Notification service (APNs)."
+---
+
+
+
+
+2. Click **Add Credentials**, choose **APNs** (and **APNs VoIP** if you want in-call pushes), upload your `.p8` key or certificate, and copy each Provider ID.
+
+
+ 
+
+
+3. (Optional) Add an **FCM** provider if you plan to register FCM tokens on iOS.
+
+
+
+
+
+Keep the provider IDs—you’ll set them in `CometChatConfig`.
+
+## 2. Prepare Apple + Firebase credentials
+
+### 2.1 Apple Developer portal
+
+1. Generate an APNs Auth Key (`.p8`) and note the **Key ID** and **Team ID**.
+2. Enable Push Notifications plus Background Modes → *Remote notifications* and *Voice over IP* on the bundle ID.
+3. Create a VoIP Services certificate/key if you want separate credentials.
+
+### 2.2 Firebase Console
+
+1. Register the same bundle ID and download `GoogleService-Info.plist` into `ios/Runner`.
+2. Enable Cloud Messaging and upload the APNs key under *Project Settings → Cloud Messaging*.
+
+
+
+
+
+## 3. Local configuration file
+
+Update [`lib/cometchat_config.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/cometchat_config.dart) (or your own config file) so it exposes:
+
+```dart lines
+class CometChatConfig {
+ static const appId = "YOUR_APP_ID";
+ static const region = "YOUR_APP_REGION";
+ static const authKey = "YOUR_AUTH_KEY";
+ static const fcmProviderId = "FCM-PROVIDER-ID";
+ static const apnProviderId = "APNS-PROVIDER-ID";
+ static const apnVoipProviderId = "APNS-VOIP-PROVIDER-ID"; // optional but recommended
+}
+```
+
+## 4. Bring the notification stack into Flutter
+
+### 4.1 Copy [`lib/notifications`](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app_push_notifications/lib/notifications)
+
+- Clone or download the sample once.
+- Copy the entire [`lib/notifications`](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app_push_notifications/lib/notifications) directory (models, Android/iOS services, helpers) into your app.
+- Update the import prefixes (for example replace `package:flutter_application_demo/...` with your own package name). Keeping the same folder names avoids manual refactors later.
+
+### 4.2 Wire the entry points
+
+**[`lib/main.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/main.dart)**
+
+- Initialize `SharedPreferencesClass`, Firebase, and `FlutterLocalNotificationsPlugin` before calling `runApp`.
+- Store `NotificationLaunchHandler.pendingNotificationResponse` when the app is opened by tapping a notification while terminated.
+- On iOS, call `APNSService.setupNativeCallListener(context)` from `initState` so Flutter reacts when the native CallKit UI changes state.
+
+**[`lib/guard_screen.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/guard_screen.dart) / [`lib/dashboard.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/lib/dashboard.dart) (or your first screen after login)**
+
+- Ensure `CometChatUIKit.init()` and `CometChatUIKit.login()` finish before rendering the dashboard.
+- Instantiate `APNSService` (iOS only) and call `apnsService.init(context)` inside `initState`.
+- Register CometChat UI + Calls listeners (`CometChatUIEventListener`, `CometChatCallEventListener`, and `CallListener`) exactly once per session; the sample stores the listener IDs inside `APNSService`.
+- Replay `NotificationLaunchHandler.pendingNotificationResponse` after the widget tree builds so taps from a killed app still navigate to `MessagesScreen`.
+- Forward lifecycle changes to `IncomingCallOverlay` / `BoolSingleton` to hide stale overlays when the app resumes.
+
+### 4.3 Align dependencies and configuration
+
+Mirror the sample `pubspec.yaml` versions (update as needed when newer releases ship):
+
+```yaml lines
+dependencies:
+ firebase_core: ^3.0.0
+ firebase_messaging: ^15.0.0
+ flutter_apns_x: ^2.1.1
+ flutter_callkit_incoming: ^2.0.3+3
+ flutter_local_notifications: ^16.0.0
+ cometchat_chat_uikit: ^5.0.0
+ cometchat_calls_uikit: ^5.0.0
+ permission_handler: ^11.3.0
+```
+
+Run `flutter pub get`, then `flutterfire configure` if you still need to generate `firebase_options.dart`.
+
+## 5. Configure the native iOS layer
+
+### 5.1 Capabilities and Info.plist
+
+1. Open `ios/Runner.xcworkspace` in Xcode.
+2. Under *Signing & Capabilities*, enable **Push Notifications** and **Background Modes** (Remote notifications + Voice over IP).
+3. Add microphone, camera, bluetooth, and notification permission strings to `Info.plist`.
+4. Set the development team that has access to the APNs/VoIP keys you generated earlier.
+
+
+ 
+
+
+### 5.2 `AppDelegate.swift` bridge
+
+Start from the sample [`ios/Runner/AppDelegate.swift`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/ios/Runner/AppDelegate.swift) and keep these pieces intact:
+
+- **MethodChannel handshake** – create a channel that both Flutter and Swift know:
+
+```swift lines
+let appInfoChannel = FlutterMethodChannel(
+ name: "com.flutter_application_demo/ios",
+ binaryMessenger: controller.binaryMessenger
+)
+```
+
+Handle at least `getAppInfo`, `endCall`, `onCallAcceptedFromNative`, and `onCallEndedFromNative`, mirroring the Dart side (`APNSService.setupNativeCallListener`).
+
+- **Firebase + plugin registration** – call `FirebaseApp.configure()` before `GeneratedPluginRegistrant.register(with: self)`.
+- **PushKit** – instantiate `PKPushRegistry`, set `desiredPushTypes = [.voIP]`, and forward the token inside `pushRegistry(_:didUpdate:for:)` via `SwiftFlutterCallkitIncomingPlugin.sharedInstance?.setDevicePushTokenVoIP(tokenHex)`.
+- **CallKit** – configure `CXProviderConfiguration`, keep a `CXCallController`, and implement `provider(_:perform: CXAnswerCallAction)` / `provider(_:perform: CXEndCallAction)` so native actions propagate to Flutter.
+- **Incoming push handler** – inside `pushRegistry(_:didReceiveIncomingPushWith:)`, convert the CometChat payload into `flutter_callkit_incoming.Data`, set `extra` with the raw payload, and call `showCallkitIncoming(..., fromPushKit: true)`.
+- **UUID helper** – reuse `createUUID(sessionid:)` to produce valid `UUID`s from long CometChat session IDs; this lets CallKit correlate calls even if the payload string exceeds 32 characters.
+
+If you change the MethodChannel name in Swift, remember to update `APNSService.platform` in Dart to match.
+
+## 6. Token registration and runtime events
+
+### 6.1 Standard APNs tokens
+
+`APNSService` hooks into `FirebaseMessaging.instance.getAPNSToken()` (and `onTokenRefresh`) before calling:
+
+```dart lines
+await CometChatPushRegistry.register(
+ token: token,
+ isFcm: false,
+ isVoip: false,
+);
+```
+
+This registers the device token against the APNs provider selected in `CometChatConfig.apnProviderId`.
+
+### 6.2 VoIP tokens
+
+- Capture the PushKit token in `AppDelegate.pushRegistry(_:didUpdate:for:)`.
+- Forward it to Flutter via the MethodChannel or register it directly from Swift by invoking `CometChatPushRegistry` through `SwiftFlutterCallkitIncomingPlugin`.
+- If you keep the Dart implementation, emit a MethodChannel call named `onVoipToken` and handle it in `APNSService` by calling `CometChatPushRegistry.register(token: token, isFcm: false, isVoip: true);`.
+
+### 6.3 Local notifications and navigation
+
+- `APNSService._showNotification` displays a local notification when the incoming CometChat message does not belong to the currently open conversation.
+- `LocalNotificationService.handleNotificationTap` parses the payload, fetches the relevant user/group, and pushes `MessagesScreen`.
+- `NotificationLaunchHandler.pendingNotificationResponse` caches taps triggered while the app is terminated; replay it on the dashboard once the UI is ready.
+
+### 6.4 Call events
+
+- `FlutterCallkitIncoming.onEvent` is already wired inside `APNSService` to accept or end calls initiated by CallKit.
+- When native CallKit UI accepts/ends a call, Swift invokes `onCallAcceptedFromNative` / `onCallEndedFromNative` on the MethodChannel; `APNSService` then calls `FlutterCallkitIncoming.setCallConnected` or `CometChat.endCall()` to keep both stacks synchronized.
+
+## 7. Testing checklist
+
+1. Run the app on a physical device in debug first. Grant notification, microphone, camera, and Bluetooth permissions when prompted.
+2. Send a message from another user:
+ - Foreground: a local notification banner shows (unless you are in that chat).
+ - Background: APNs notification appears, tapping opens the right conversation.
+3. Force-quit the app, send another message push, tap it, and confirm `NotificationLaunchHandler` launches `MessagesScreen`.
+4. Trigger an incoming CometChat call. Ensure:
+ - CallKit UI shows contact name, call type, and Accept/Decline.
+ - Accepting on the lock screen notifies Flutter (`setupNativeCallListener`), starts the call session, and dismisses the native UI when the call ends.
+5. Decline the call and confirm both CallKit and Flutter clean up (`BoolSingleton` resets, overlays dismissed).
+6. Rotate through Wi-Fi/cellular and reinstall the app to confirm token registration works after refresh events.
+
+## 8. Troubleshooting tips
+
+| Symptom | Quick checks |
+| --- | --- |
+| No VoIP pushes | Entitlements missing? Ensure Push Notifications + Background Modes (VoIP) are enabled and the bundle ID matches the CometChat provider. |
+| CallKit UI never dismisses | Make sure `endCall(callUUID:)` reports to `CXProvider`, runs a `CXEndCallAction`, **and** calls `SwiftFlutterCallkitIncomingPlugin.sharedInstance?.endCall`. |
+| Flutter never receives native call events | Confirm the MethodChannel names match between Swift and Dart, and `APNSService.setupNativeCallListener` runs inside `initState`. |
+| Token registration errors | Double-check `CometChatConfig` provider IDs, and verify you call `registerPushToken` after `CometChatUIKit.login` succeeds. |
+| Notification taps ignored | Ensure you replay `NotificationLaunchHandler.pendingNotificationResponse` **after** the navigator key is ready (typically `WidgetsBinding.instance.addPostFrameCallback`). |
+
+{/* ## Additional resources
+
+
+
+
+2. The Certificate Information dialog box appears. Enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button.
+
+
+ 
+
+
+3. Specify the name of your CSR to save and choose the location to save the file on your local disk. Then your CSR file is created, which contains a public/private key pair.
+
+### Step 2: Create an SSL certificate
+
+1. Sign in to your account at the [Apple Developer Member Center](https://developer.apple.com/membercenter).
+2. Go to Certificates, Identifiers & Profiles.
+
+
+ 
+
+
+3. Create new Certificate by clicking on the + icon.
+
+
+ 
+
+
+4. Under Services, select - Apple Push Notification services SSL (Sandbox & Production)
+
+
+ 
+
+
+5. Select your App ID from the dropdown.
+
+
+ 
+
+
+6. Upload CSR file., upload the CSR file you created through the **Choose File** button. To complete the process, choose Continue. When the certificate is ready, choose Download to save it to your Mac.
+
+
+ 
+
+
+
+ 
+
+
+### Step 3: Export and update .p8 certificate
+
+1. To generate a .p8 key file, go to [Apple Developer Account](https://developer.apple.com/account/), then select Certificates, IDs & Profiles.
+2. Select Keys and click on the "+" button to add a new key.
+3. In the new key page, type in your key name and check the Apple Push Notification service (APNs) box, then click "Continue" and click "Register".
+4. Then proceed to download the key file by clicking Download.
+5. Make note of the `Key ID`, `Team ID` and your `Bundle ID` for saving in the Extension's settings.
+
+**If you wish to use the .p12 certificate instead, do the following:**
+
+1. Type a name for the .p12 file and save it to your Mac.
+2. Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in Certificates, Identifiers & Profiles in the Apple Developer Member Center) and export it.
+3. DO NOT provide an export password when prompted.
+4. The .p12 file will be required in the next step for uploading in the CometChat Dashboard.
+
+## Extension settings
+
+### Step 1: Enable the extension
+
+1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
+2. Go to the Extensions section and Enable the Push Notifications extension.
+3. Open the settings for this extension and save the following.
+
+### Step 2: Save your settings
+
+
+ 
+
+
+
+ 
+
+
+On the Settings page you need to enter the following:
+
+1. **Set extension version**
+
+ 1. The extension version has to be set to 'V2' or 'V1 & V2' in order to use APNs as the provider.
+
+2. **Select Platforms**
+
+ 1. You can select the platforms on which you wish to receive Push Notifications.
+
+3. **APNs Settings**
+
+ 1. You can turn off the Production mode when you create a development build of your application.
+ 2. Upload the .p8 or .p12 certificate exported in the previous step.
+
+4. **Push payload message options**
+
+
+
+
+
+The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+
+* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+
+5. **Notification Triggers**
+
+ 1. Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+
+ 1. Message Notifications
+ 2. Call Notifications
+ 3. Group Notifications
+
+ 2. These are pretty self-explanatory and you can toggle them as per your requirement.
+
+## iOS App Setup
+
+### Initial Setup
+
+1. Call `CometChat.init()` method to initialize CometChat in your application. This needs to be called only once.
+2. The user has to be logged in using `CometChat.login()` method. On the success callback, register the token with the extension. Two tokens need to be registered, out of which one is APNs token and other is CallKit token: a. `CometChat.registerTokenForPushNotification(token: apnsToken, settings: ["voip":false])`\
+ b. `CometChat.registerTokenForPushNotification(token: voipToken, settings: ["voip":true])`
+
+
-
-
-2. The Certificate Information dialog box appears. Enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button.
+## What this guide covers
-
-
-
-
-3. Specify the name of your CSR to save and choose the location to save the file on your local disk. Then your CSR file is created, which contains a public/private key pair.
-
-### Step 2: Create an SSL certificate
-
-1. Sign in to your account at the [Apple Developer Member Center](https://developer.apple.com/membercenter).
-2. Go to Certificates, Identifiers & Profiles.
+- CometChat dashboard setup (enable push, add APNs Device + APNs VoIP providers) with screenshots.
+- APNs + PushKit/CallKit wiring (tokens, delegates, CallKit).
+- Incoming message/call handling and deep links.
+- Payload customization and testing.
-
-
-
+{/* ## What you need first
-3. Create new Certificate by clicking on the + icon.
+- CometChat App ID, Region, Auth Key; Push Notifications with **APNs Device provider ID** and **APNs VoIP provider ID**.
+- Apple capabilities: Push Notifications, Background Modes (Remote notifications, Voice over IP), CallKit usage descriptions. Physical device required.
+- `.p8` APNs key (Key ID, Team ID, Bundle ID) or certificates. */}
-
-
-
+## How APNs + CometChat work together
-4. Under Services, select - Apple Push Notification services SSL (Sandbox & Production)
+- **APNs is the transport:** Apple issues the APNs device/VoIP tokens and delivers the payloads. No FCM bridge is involved.
+- **CometChat providers:** The APNs Device and APNs VoIP providers you add in the CometChat dashboard hold your APNs key/cert. When you call `CometChatNotifications.registerPushToken(..., .APNS_IOS_DEVICE / .APNS_IOS_VOIP, providerId)` after login, CometChat binds those tokens to the logged-in user and sends to APNs for you.
+- **Flow:** Permission prompt → APNs returns device + VoIP tokens → after `CometChat.login`, register both tokens with the matching provider IDs → CometChat sends to APNs → APNs delivers → `UNUserNotificationCenterDelegate` (and `PushKit`/`CallKit` for VoIP) surface the notification/tap.
-
-
-
+## 1. Enable push and add providers (CometChat Dashboard)
-5. Select your App ID from the dropdown.
+1) Go to **Notifications → Settings** and enable **Push Notifications**.
-
+
-6. Upload CSR file., upload the CSR file you created through the **Choose File** button. To complete the process, choose Continue. When the certificate is ready, choose Download to save it to your Mac.
+2) Click **Add Credentials**:
+ - Add an **APNs Device** provider (alerts) using your `.p8` key, Team ID, Key ID, and Bundle ID; copy the Provider ID.
+ - Add an **APNs VoIP** provider (calls) with the same `.p8` (recommended for CallKit reliability); copy the Provider ID.
-
+ 
-
-
-
-
-### Step 3: Export and update .p8 certificate
-
-1. To generate a .p8 key file, go to [Apple developer account page](https://developer.apple.com/account/), then select Certificates, IDs & Profiles.
-2. Select Keys and click on the "+" button to add a new key.
-3. In the new key page, type in your key name and check the Apple Push Notification service (APNs) box, then click "Continue" and click "Register".
-4. Then proceed to download the key file by clicking Download.
-5. Make note of the `Key ID`, `Team ID` and your `Bundle ID` for saving in the Extension's settings.
-
-**If you wish to use the .p12 certificate instead, do the following:**
-
-1. Type a name for the .p12 file and save it to your Mac.
-2. Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in Certificates, Identifiers & Profiles in the Apple Developer Member Center) and export it.
-3. DO NOT provide an export password when prompted.
-4. The .p12 file will be required in the next step for uploading in the CometChat Dashboard.
-
-## Extension settings
-
-### Step 1: Enable the extension
-
-1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
-2. Go to the Extensions section and Enable the Push Notifications extension.
-3. Open the settings for this extension and save the following.
+Keep the provider IDs—you’ll paste them into your app constants.
-### Step 2: Save your settings
+## 2. Apple setup
-
-
-
+1) Capabilities: Push Notifications, Background Modes → Remote notifications & Voice over IP, CallKit usage descriptions in `Info.plist` (mic/camera).
+2) APNs Auth Key: generate `.p8` (or use cert), note **Key ID**, **Team ID**, and **Bundle ID**; upload to CometChat providers.
-
+
-On the Settings page you need to enter the following:
-
-1. **Set extension version**
-
- 1. The extension version has to be set to 'V2' or 'V1 & V2' in order to use APNs as the provider.
-
-2. **Select Platforms**
+## 3. Wiring APNs + PushKit/CallKit
- 1. You can select the platforms on which you wish to receive Push Notifications.
-
-3. **APNs Settings**
-
- 1. You can turn off the Production mode when you create a development build of your application.
- 2. Upload the .p8 or .p12 certificate exported in the previous step.
-
-4. **Push payload message options**
-
-
-
-
-
-The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
-
-* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
-
-5. **Notification Triggers**
-
- 1. Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
-
- 1. Message Notifications
- 2. Call Notifications
- 3. Group Notifications
-
- 2. These are pretty self-explanatory and you can toggle them as per your requirement.
-
-## iOS App Setup
-
-### Initial Setup
-
-1. Call `CometChat.init()` method to initialize CometChat in your application. This needs to be called only once.
-2. The user has to be logged in using `CometChat.login()` method. On the success callback, register the token with the extension. Two tokens need to be registered, out of which one is APNs token and other is CallKit token: a. `CometChat.registerTokenForPushNotification(token: apnsToken, settings: ["voip":false])`\
- b. `CometChat.registerTokenForPushNotification(token: voipToken, settings: ["voip":true])`
+- From below code, copy `CometChatAPNsHelper.swift`, `CometChatPNHelper.swift`, and the two `AppDelegate` extensions (`AppDelegate+PN.swift` and `AppDelegate+VoIP.swift`) into your project.
+- These files implement APNs + PushKit/CallKit handling, notification presentation, tap and quick-reply actions, and call management.
+- Update bundle ID, team ID, and provider IDs (`AppConstants.PROVIDER_ID` etc.). Keep the `voip` push type.
+
+
+This is a simple 3 step process where:
+
+1. You give a name to your project
+2. Add Google Analytics to your project (Optional)
+3. Configure Google Analytics account (Optional)
+
+Click on Create and you are ready to go.
+
+### Step 2: Add Firebase to your iOS App
+
+1. Click on the iOS icon as shown on the screen below.
+
+
+ 
+
+
+2. Register your Android app by providing the following details: a. iOS bundle name b. App nickname (optional) c. App Store ID (optional)
+
+
+ 
+
+
+3. Download the GoogleService-Info.plist file and place it in the mentioned location of your project. Move your config file into the root of your Xcode project. If prompted, select to add the config file to all targets as follows.
+
+
+ 
+
+
+
+ 
+
+
+4. We will Add Firebase SDK and Initialisation code later. So, click on 'Next', 'Next', and 'Continue to the Console'.
+
+### Step 3: Download the service account file
+
+
+
+
+
+## Extension settings
+
+### Step 1: Enable the extension
+
+1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
+2. Go to the Extensions section and Enable the Push Notifications extension.
+3. Open the settings for this extension and save the following settings.
+
+
+
+
+
+### Step 2: Save your settings
+
+On the Settings page you need to enter the following:
+
+1. **Set extension version**
+
+* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
+* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
+* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
+
+2. **Select the platforms that you want to support**
+
+* Select from Web, Android, Ionic, React Native, Flutter & iOS.
+
+3. **Notification payload settings**
+
+* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
+
+4. **Push payload message options**
+
+
+
+
+
+The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+
+* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+
+5. **Notification Triggers**
+
+
+
+
+
+* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+
+ 1. Message Notifications
+ 2. Call Notifications
+ 3. Group Notifications
+
+* These are pretty self-explanatory and you can toggle them as per your requirement.
+
+## Get APNS Credentials
+
+The following steps in this section are written on the assumption that you already have an app ID assigned to your client app.
+
+### Step 1: Create a Certificate Signing Request
+
+To obtain a signing certificate required to sign apps for installation on iOS devices, you should first create a certificate signing request (CSR) file through Keychain Access on your Mac.
+
+1. Open the Keychain Access from the utility folder, go to Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority, and then click.
+
+
+ 
+
+
+2. The Certificate Information dialog box appears. Enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button.
+
+
+ 
+
+
+3. Specify the name of your CSR to save and choose the location to save the file on your local disk. Then your CSR file is created, which contains a public/private key pair.
+
+### Step 2: Create an SSL certificate
+
+1. Sign in to your account at the [Apple Developer Member Center](https://developer.apple.com/membercenter).
+2. Go to Certificates, Identifiers & Profiles. In the Identifiers > App IDs and select the Push Notifications service under Application Services
+3. Click the Edit button.
+
+
+ 
+
+
+4. Under the Push Notifications service, choose which SSL certificate to create either Development or Production.
+
+
+ 
+
+
+5. In the Generate your certificate pane that appears after the selection, under Upload CSR file., upload the CSR file you created through the Choose File... button. To complete the process, choose Continue. When the certificate is ready, choose Download to save it to your Mac.
+
+
+ 
+
+
+6. In order to install the downloaded certificate to the KeyChain Access on your Mac, double-click it. You can find the certificate in the KeyChain Access > login > Certificates.
+
+### Step 3: Export and update .p12 file to Firebase
+
+1. Type a name for the .p12 file and save it to your Mac.
+2. Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in Certificates, Identifiers & Profiles in the Apple Developer Member Center) and export it.
+
+
+ 
+
+
+### Step 4: Upload your APNs Certificates
+
+1. Go to Firebase console and open your project.
+2. Inside your iOS project in the Firebase console, select settings and then select the `Cloud Messaging` tab.
+3. Scroll down to iOS app configuration, click the Upload button for APNS certificate.
+4. Browse to the location where you saved your APNs Certificates, select it, and click Open.
+
+
+ 
+
+
+## iOS App Setup
+
+### Step 1: Initial Firebase Cloud Messaging client setup
+
+1. Add the Firebase SDK, Add the firebase pods that you want to install. You can include a Pod in your Podfile like this:
+
+
-
+- CometChat App ID, Region, Auth Key; Push Notifications with **FCM iOS provider ID** (and APNs device/VoIP provider IDs if you deliver via APNs/PushKit).
+- Firebase project with an iOS app; `GoogleService-Info.plist` downloaded; APNs key uploaded to Firebase Cloud Messaging.
+- Xcode capabilities: Push Notifications, Background Modes (Remote notifications, Voice over IP), CallKit usage descriptions. Physical device for push testing. */}
-This is a simple 3 step process where:
+## How FCM + CometChat work together
-1. You give a name to your project
-2. Add Google Analytics to your project (Optional)
-3. Configure Google Analytics account (Optional)
+- **FCM’s role:** Firebase issues the iOS FCM registration token and delivers the push payload. On iOS, FCM hands off to APNs using the APNs key/cert you upload in Firebase.
+- **CometChat Notifications’ role:** The FCM iOS provider you create in the CometChat dashboard holds your Firebase service account. When you call `CometChatNotifications.registerPushToken(..., .FCM_IOS, providerId)`, CometChat binds that FCM token to the logged-in user and sends pushes to FCM on your behalf.
+- **Flow (same bridge used in `android-push-notifications.mdx`):** Request permission → register for remote notifications → FCM returns the registration token → after `CometChat.login` succeeds, register that token with `CometChatNotifications` using the FCM provider ID → CometChat sends payloads to FCM → FCM hands to APNs → `UNUserNotificationCenterDelegate` surfaces the notification/tap.
-Click on Create and you are ready to go.
+## 1. Enable push and add providers (CometChat Dashboard)
-### Step 2: Add Firebase to your iOS App
-
-1. Click on the iOS icon as shown on the screen below.
+1) Go to **Notifications → Settings** and enable **Push Notifications**.
-
+
-2. Register your Android app by providing the following details: a. iOS bundle name b. App nickname (optional) c. App Store ID (optional)
+2) On Firebase:
+ - Go to **Project Settings → Service accounts** and generate a new private key; download the JSON file.
-
+
-3. Download the GoogleService-Info.plist file and place it in the mentioned location of your project. Move your config file into the root of your Xcode project. If prompted, select to add the config file to all targets as follows.
-
-
-
-
+3) On CometChat Dashboard:
+ - Add an **FCM iOS provider** and upload your Firebase service account JSON; copy the Provider ID.
-
+ 
-4. We will Add Firebase SDK and Initialisation code later. So, click on 'Next', 'Next', and 'Continue to the Console'.
+ ## 2. Upload your APNs Certificates
-### Step 3: Download the service account file
+1) In the **Firebase Console**, go to **Project Settings → Cloud Messaging**.
+2) Under **iOS app configuration**, upload your APNs authentication key or certificates.
-
+ 
-## Extension settings
-
-### Step 1: Enable the extension
+## 3. Prepare Firebase and CometChat
-1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
-2. Go to the Extensions section and Enable the Push Notifications extension.
-3. Open the settings for this extension and save the following settings.
+1) Firebase Console: download and add `GoogleService-Info.plist` to your target.
-
+ 
-### Step 2: Save your settings
-
-On the Settings page you need to enter the following:
-
-1. **Set extension version**
-
-* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
-* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
-* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
-
-2. **Select the platforms that you want to support**
-
-* Select from Web, Android, Ionic, React Native, Flutter & iOS.
-
-3. **Notification payload settings**
-
-* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
-
-4. **Push payload message options**
+2) Xcode capabilities: Push Notifications, Background Modes → Remote notifications.
-
+ 
-The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
-
-* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
-
-5. **Notification Triggers**
-
-
-
-
+## 4. Add dependencies (Podfile)
-* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
-
- 1. Message Notifications
- 2. Call Notifications
- 3. Group Notifications
-
-* These are pretty self-explanatory and you can toggle them as per your requirement.
-
-## Get APNS Credentials
-
-The following steps in this section are written on the assumption that you already have an app ID assigned to your client app.
-
-### Step 1: Create a Certificate Signing Request
-
-To obtain a signing certificate required to sign apps for installation on iOS devices, you should first create a certificate signing request (CSR) file through Keychain Access on your Mac.
-
-1. Open the Keychain Access from the utility folder, go to Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority, and then click.
-
-
-
-
-
-2. The Certificate Information dialog box appears. Enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button.
-
-
-
-
-
-3. Specify the name of your CSR to save and choose the location to save the file on your local disk. Then your CSR file is created, which contains a public/private key pair.
-
-### Step 2: Create an SSL certificate
-
-1. Sign in to your account at the [Apple Developer Member Center](https://developer.apple.com/membercenter).
-2. Go to Certificates, Identifiers & Profiles. In the Identifiers > App IDs and select the Push Notifications service under Application Services
-3. Click the Edit button.
-
-
-
-
-
-4. Under the Push Notifications service, choose which SSL certificate to create either Development or Production.
-
-
-
-
+```ruby lines
+target 'YourApp' do
+ use_frameworks!
-5. In the Generate your certificate pane that appears after the selection, under Upload CSR file., upload the CSR file you created through the Choose File... button. To complete the process, choose Continue. When the certificate is ready, choose Download to save it to your Mac.
-
-
-
-
-
-6. In order to install the downloaded certificate to the KeyChain Access on your Mac, double-click it. You can find the certificate in the KeyChain Access > login > Certificates.
-
-### Step 3: Export and update .p12 file to Firebase
-
-1. Type a name for the .p12 file and save it to your Mac.
-2. Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in Certificates, Identifiers & Profiles in the Apple Developer Member Center) and export it.
-
-
-
-
-
-### Step 4: Upload your APNs Certificates
-
-1. Go to Firebase console and open your project.
-2. Inside your iOS project in the Firebase console, select settings and then select the `Cloud Messaging` tab.
-3. Scroll down to iOS app configuration, click the Upload button for APNS certificate.
-4. Browse to the location where you saved your APNs Certificates, select it, and click Open.
-
-
-
-
-
-## iOS App Setup
-
-### Step 1: Initial Firebase Cloud Messaging client setup
-
-1. Add the Firebase SDK, Add the firebase pods that you want to install. You can include a Pod in your Podfile like this:
-
-
+
+
+**How it flows**
+- Admin sets defaults and override rules in the dashboard.
+- Users inherit those defaults until they change a setting the admin allows.
+- `CometChatNotifications.fetchPreferences()` returns the current merged view.
+- `CometChatNotifications.updatePreferences()` saves allowed changes and returns the updated snapshot.
+
+**Key SDK helpers**
+- `CometChatNotifications.fetchPreferences()` / `updatePreferences()`
+- `CometChatNotifications.getMutedConversations()` / `muteConversations()` / `unmuteConversations()`
+- `CometChatNotifications.resetPreferences()` to restore dashboard defaults
+
+Each section pairs the dashboard defaults with matching client-side snippets so you can mirror the same behavior in your app.
+
+## Push payload message options
+
+These control what CometChat includes in push payloads. All are optional toggles:
+
+- Include entire message object in payload (largest footprint)
+- Include message metadata in payload
+- Include sender's metadata in payload
+- Include receiver's metadata in payload
+- Trim CometChat message object (strip down to stay within provider limits)
+- Additional data in payload (JSON you add)
+
+Use a minimal combination to stay under ~4 KB for FCM/APNs.
### Group preferences
@@ -38,6 +66,8 @@ Push notifications should be triggered for the message edited and message delete
#### Client-side implementation
+The fetch/update pattern shown here applies to group, one-on-one, mute, and schedule preferences; only the preference classes change.
+
**1. Fetch group preferences**
`CometChatNotifications.fetchPreferences()` method retrieves the notification preferences as an instance of `NotificationPreferences` class. If the user has not configured any preferences, the default preferences defined by the CometChat administrator via the dashboard will be returned.
@@ -151,7 +181,7 @@ CometChatNotifications.fetchPreferences(
`CometChatNotifications.updatePreferences()` method is used to update a user's notification preferences. The "**override**" toggle defined in the dashboard is crucial when updating preferences. If any preference is non-overridable, the method doesn't generate an error; it instead returns the `NotificationPreferences` object with the updated values where overrides are allowed.
-This functionality can be beneficial for temporarily superseding certain user preferences to ensure notifications for a specific event are delivered. Nonetheless, it is advisable to use this approach temporarily to avoid confusing users with unexpected changes to their notification settings.
+Use this sparingly, only when you must temporarily override preferences for a critical event, so users are not surprised by unexpected notification changes.
It is unnecessary to specify all values; only set and save the preferences that have been changed.
@@ -190,7 +220,7 @@ groupPreferences.setMemberScopeChangedPreference(
// Load the updates in the NotificationPreferences instance.
updatedPreferences.setGroupPreferences(groupPreferences);
-// Update the preferences and receive the udpated copy.
+// Update the preferences and receive the updated copy.
const preferences = await CometChatNotifications.updatePreferences(
updatedPreferences
);
@@ -319,8 +349,8 @@ As the name suggests, these preferences help you to configure Notifications for
| --------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| Conversations | New messages | • Don't notify
-
-
-| Payload setting | Available preferences |
-| -------------------------------- | ----------------------------------------------------------------- |
-| Include CometChat message object | • **false (Default)**
1. Login to [CometChat](https://app.cometchat.com/login) dashboard and select your app.
-2. Navigate to **Notifications** > **Notifications** in the left-hand menu.
+2. Navigate to **Notifications** > **Settings** in the left-hand menu.
3. Enable the Push notifications feature.
-4. Continue to configure Push notifications by clicking on "Configure".
-
-## Add Providers
+4. Continue to configure Push notifications.
+
+## Step 2: Add Providers
Firebase Cloud Messaging (FCM) and Apple Push Notification Service (APNS) are the two primary supported providers for sending push notifications.
@@ -32,7 +32,7 @@ Generate a service account key for your Firebase application by navigating to th
1. Select the "+ Add Credentials" button.
2. In the dialogue that appears, provide a unique, memorable identifier for your provider.
3. Upload the service account JSON file you previously acquired.
-4. Specify whether the push payload should include the "notification" key. Additional information on this configuration is available in FCM's documentation - [About FCM messages](https://firebase.google.com/docs/cloud-messaging/concept-options).
+4. Specify whether the push payload should include the "notification" key. Additional information on this configuration is available in FCM's documentation - [About FCM messages](https://firebase.google.com/docs/cloud-messaging/get-started).
Similarly, you can add multiple FCM Credentials in case you have multiple FCM projects for your apps.
@@ -44,7 +44,7 @@ Similarly, you can add multiple FCM Credentials in case you have multiple FCM pr
#### Pre-requisite
-1. To generate a .p8 key file, go to [Apple developer account](https://developer.apple.com/account), then select "Certificates, IDs & Profiles".
+1. To generate a .p8 key file, go to [Apple Developer Account](https://developer.apple.com/account), then select "Certificates, IDs & Profiles".
2. Select Keys and click on the "+" button to add a new key.
3. In the new key page, type in your key name and check the Apple Push Notification service (APNs) box, then click "Continue" and click "Register".
4. Then proceed to download the key file by clicking Download.
@@ -68,291 +68,11 @@ Similarly, you can add multiple APNS Credentials in case you have multiple apps
-### Add Custom provider credentials
-
-Custom providers allow you to make use of providers apart from FCM and APNs. This is implemented using webhook URL which gets all the required details that can be used to trigger Push notifications.
-
-#### Pre-requisite
-
-1. Your webhook endpoint must be accessible over `HTTPS`. This is essential to ensure the security and integrity of data transmission.
-2. This URL should be publicly accessible from the internet.
-3. Ensure that your endpoint supports the `HTTP POST` method. Event payloads will be delivered via `HTTP POST` requests in `JSON` format.
-4. Configure your endpoint to respond immediately to the CometChat server with a 200 OK response. The response should be sent within 2 seconds of receiving the request.
-5. For security, it is recommended to set up Basic Authentication that is usually used for server-to-server calls. This requires you to configure a username and password. Whenever your webhook URL is triggered, the HTTP Header will contain:
-
-```html
-Authorization: Basic
-
-
-#### How does it work?
-
-The Custom provider is triggered once for an event in one-on-one conversation. In case of notifying the members of a group, the custom provider is triggered once for each user present in that group.
-
-For example, if there are 100 members in the group, your webhook will receive 100 HTTP requests. Once for each member of the group.
+### Custom providers
-Below are the sample payloads for different events:
+For webhook-based providers and payload samples, see [Custom Providers](/notifications/custom-providers).
-
-
+- **Providers + tokens**: Add FCM/APNs (and APNs VoIP) providers in the CometChat dashboard. Register device tokens in your app after login; unregister on logout.
+- **Templates + payloads**: Customize notification text and sounds per message/call type (see Templates & Sounds). CometChat builds the payload and ships it to your provider.
+- **Delivery guardrails**: Routing, retries, quiet hours, and DND/mutes are honored automatically; logs help you trace delivery.
+- **Navigation**: Deep links open the right user/group/thread; call pushes can surface native call UI on supported platforms.
-## Key Features
+## Key capabilities
-1. **Support for multiple providers**:
+- Multi-platform coverage: Android, iOS (APNs or FCM), Flutter, React Native, and Web.
+- Message and call notifications with grouping, inline replies (where supported), and native call surfaces via CallKit/ConnectionService.
+- Preferences: per-user/per-conversation mutes, quiet hours, and global DND.
+- Timezone-aware scheduling for delayed/quiet-hour delivery.
+- Logging and troubleshooting from the dashboard.
- CometChat provides support for **Firebase Cloud Messaging (FCM)** and **Apple Push Notification Service (APNS)**. This approach, involving multiple providers, provides flexibility in notification delivery, independent of the recipient's platform. It also enables CometChat to respond effectively to the evolving push notification landscape, maintaining consistent delivery across Android, iOS, and web platforms.
+## Common triggers
-2. **Support for multiple platforms**:
+- New messages (1:1 and group), thread replies, mentions, and reactions (if enabled).
+- Message edits/deletes and admin/moderation actions (when you include them in templates).
+- Group membership changes (join/leave/ban).
+- Call invites, missed calls, and ongoing call updates.
- CometChat provides multi-platform support, compatible with an extensive array of mobile and web platforms. This includes native mobile platforms such as Android and iOS, web frameworks like React, Angular, and Vue.js, and hybrid environments including React Native and Flutter.
+## Before you integrate
-3. **Tokens management**:
+1. **Dashboard setup**: Enable Push Notifications, add providers (FCM for Android/iOS, APNs + optional APNs VoIP for iOS), and copy Provider IDs.
+2. **Credentials**: Keep App ID, Region, Auth Key handy. Upload the Firebase service account JSON and APNs `.p8` key (Team ID + Key ID).
+3. **Client wiring**: Register tokens after login and unregister on logout. Follow the platform guide below for Gradle/Info.plist/CallKeep specifics.
- CometChat's Push Notification service provides developers with functions and APIs for easy tokens management, ensuring that push notifications are delivered reliably to intended user's devices.
+## Choose your platform
-4. **Preferences management**:
+
+
+
+This is a simple 3 step process where:
+
+1. You give a name to your project
+2. Add Google Analytics to your project (Optional)
+3. Configure Google Analytics account (Optional)
+
+Click on Create and you are ready to go.
+
+### Step 2: Add Firebase to your App
+
+React native setup will require 2 files for Android and iOS:
+
+1. For Android, you need to download the google-services.json file from the Firebase console.
+2. For iOS, you need to download the GoogleService-Info.plist file from the Firebase console.
+
+### Step 3: Download the service account file
+
+
+
+
+
+## Extension settings
+
+### Step 1: Enable the extension
+
+1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
+2. Go to the Extensions section and Enable the Push Notifications extension.
+3. Open up the settings and save the following settings.
+
+
+
+
+
+### Step 2: Save your settings
+
+On the Settings page you need to enter the following:
+
+1. **Set extension version**
+
+* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
+* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
+* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
+
+2. **Select the platforms that you want to support**
+
+* Select from Web, Android, Ionic, React Native, Flutter & iOS.
+
+3. **Notification payload settings**
+
+* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
+
+4. **Push payload message options**
+
+
+
+
+
+The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+
+* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+
+5. **Notification Triggers**
+
+
+
+
+
+* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+
+ 1. Message Notifications
+ 2. Call Notifications
+ 3. Group Notifications
+
+* These are pretty self-explanatory and you can toggle them as per your requirement.
+
+## App Setup
+
+### Step 1: Initial plugin setup
+
+1. For React Native, there are numerous plugins available via NPM which can be used to set up push notifications for your apps. [react-native-firebase](https://www.npmjs.com/package/react-native-firebase) and [react-native-notifications](https://www.npmjs.com/package/react-native-notifications) are just the two out of many available.
+2. To setup Push Notification, you need to follow the steps mentioned in the Plugin's Documentation.
+
+At this point, you will have:
+
+1. Two separate apps created on the Firebase console. (For Android and iOS).
+2. Plugin setup completed as per the respective documentation and our reference.
+
+### Step 2: Register FCM Token
+
+1. This step assumes that you already have a React Native app setup with CometChat installed. Make sure that the CometChat object is initialized and user has been logged in.
+2. On the success callback of user login, you can fetch the FCM Token and register it with the extension as shown below:
+
+
+
+
+
+ 
+
+
+
+
+
+2. The Certificate Information dialog box appears. Enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button. \
\
+
+
+3. Create new Certificate by clicking on the + icon.
+
+
+ 
+
+
+4. Under Services, select - Apple Push Notification services SSL (Sandbox & Production)
+
+
+ 
+
+
+5. Select your App ID from the dropdown.
+
+
+ 
+
+
+6. Upload CSR file., upload the CSR file you created through the **Choose File** button. To complete the process, choose Continue. When the certificate is ready, choose Download to save it to your Mac.
+
+
+ 
+
+
+
+ 
+
+
+#### Step 3: Export and update .p8 certificate
+
+1. To generate a .p8 key file, go to [Apple Developer Account](https://developer.apple.com/account/), then select Certificates, IDs & Profiles.
+2. Select Keys and click on the "+" button to add a new key.
+3. In the new key page, type in your key name and check the Apple Push Notification service (APNs) box, then click "Continue" and click "Register".
+4. Then proceed to download the key file by clicking Download.
+5. Make note of the `Key ID`, `Team ID` and your `Bundle ID` for saving in the Extension's settings.
+
+**If you wish to use the .p12 certificate instead, do the following:**
+
+1. Type a name for the .p12 file and save it to your Mac.
+2. Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in Certificates, Identifiers & Profiles in the Apple Developer Member Center) and export it.
+3. DO NOT provide an export password when prompted.
+4. The .p12 file will be required in the next step for uploading in the CometChat Dashboard.
+
+#### Extension settings
+
+#### Step 1: Enable the extension
+
+1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
+2. Go to the Extensions section and Enable the Push Notifications extension.
+3. Open the settings for this extension and save the following.
+
+
+
+
+
+#### Step 2: Save your settings
+
+On the Settings page you need to enter the following:
+
+
+
+
+
+1. **Set extension version**
+
+ The extension version has to be set to 'V2' or 'V1 & V2' in order to use APNs as the provider.
+
+2. **Select Platforms**
+
+ You can select the platforms on which you wish to receive Push Notifications.
+
+3. **Firebase Cloud Messaging Settings**
+
+ This includes the FCM Server key that you can fetch from the Firebase Dashboard.
+
+4. **APNs Settings**
+
+ You can turn off the Production mode when you create a development build of your application. Upload the .p12 certificate exported in the previous step.
+
+5. **Push Notifications Title**
+
+ This is usually the name of your app.
+
+6. **Notification Triggers**
+
+ Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+
+ 1. Message Notifications
+ 2. Call Notifications
+ 3. Group Notifications
+
+ These are pretty self-explanatory and you can toggle them as per your requirement.
+
+#### Installation
+
+We need to add two packages for this
+
+* React-native-CallKeep
+
+This package also require some additional installation steps. Follow [this](https://github.com/react-native-webrtc/react-native-callkeep) link to install react-native-callkeep
+
+
-
+- CometChat Dashboard setup (enable push, add FCM + APNs providers).
+- Platform credentials (Firebase for Android/iOS, Apple entitlements).
+- Copying the sample notification stack and aligning IDs/provider IDs.
+- Native glue for Android (manifest permissions) and iOS (PushKit).
+- Token registration, navigation from pushes, testing, and troubleshooting.
-This is a simple 3 step process where:
+## What you need first
-1. You give a name to your project
-2. Add Google Analytics to your project (Optional)
-3. Configure Google Analytics account (Optional)
+- CometChat app credentials (App ID, Region, Auth Key) and Push Notifications enabled with an **FCM provider (React Native Android)** and **APNs provider** for iOS.
+- Firebase project with an Android app (`google-services.json` in `android/app`) and Cloud Messaging enabled; optional iOS app if you use FCM on iOS.
+- Apple push setup: APNs `.p8` key/cert in CometChat, iOS project with Push Notifications + Background Modes (Remote notifications) permissions.
+- React Native 0.81+, Node 18+, physical Android + iOS devices for reliable push/call testing.
-Click on Create and you are ready to go.
+## How FCM/APNs + CometChat work together
-### Step 2: Add Firebase to your App
+- **FCM (Android) and APNs (iOS) are the transports:** Firebase issues the Android FCM token; Apple issues the APNs token. They deliver the payloads to devices.
+- **CometChat providers hold your credentials:** The FCM provider you add (for React Native Android) stores your Firebase service account; the APNs provider stores your `.p8` key/cert.
+- **Registration flow:** Request permission → platform returns token → after `CometChat.login`, register with `CometChatNotifications.registerPushToken(token, platform, providerId)` using `FCM_REACT_NATIVE_ANDROID` on Android and `APNS_REACT_NATIVE_DEVICE` on iOS → CometChat sends pushes to FCM/APNs on your behalf → the app handles taps/foreground events via Notifee/PushNotificationIOS.
-React native setup will require 2 files for Android and iOS:
+## 1. Enable push and add providers (CometChat Dashboard)
-1. For Android, you need to download the google-services.json file from the Firebase console.
-2. For iOS, you need to download the GoogleService-Info.plist file from the Firebase console.
-
-### Step 3: Download the service account file
+1. Go to **Notifications → Settings** and enable **Push Notifications**.
-
+
-## Extension settings
-
-### Step 1: Enable the extension
-
-1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
-2. Go to the Extensions section and Enable the Push Notifications extension.
-3. Open up the settings and save the following settings.
+2. Add an **FCM** provider for React Native Android; upload the Firebase service account JSON and copy the Provider ID.
-
+
-### Step 2: Save your settings
-
-On the Settings page you need to enter the following:
-
-1. **Set extension version**
-
-* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
-* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
-* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
-
-2. **Select the platforms that you want to support**
-
-* Select from Web, Android, Ionic, React Native, Flutter & iOS.
-
-3. **Notification payload settings**
-
-* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
-
-4. **Push payload message options**
+3. Add an **APNs** provider for iOS and copy the Provider ID.
-
+
-The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+## 2. Prepare platform credentials
-* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+### 2.1 Firebase Console
-5. **Notification Triggers**
+1. Register your Android package name (same as `applicationId` in `android/app/build.gradle`) and download `google-services.json` into `android/app`.
+2. Enable Cloud Messaging.
-
+ 
-* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
-
- 1. Message Notifications
- 2. Call Notifications
- 3. Group Notifications
+### 2.2 Apple Developer portal
-* These are pretty self-explanatory and you can toggle them as per your requirement.
+1. Generate an APNs Auth Key (`.p8`) and note the **Key ID** and **Team ID**.
+2. Enable Push Notifications plus Background Modes → *Remote notifications* on the bundle ID.
-## App Setup
-
-### Step 1: Initial plugin setup
+
+
+
-1. For React Native, there are numerous plugins available via NPM which can be used to set up push notifications for your apps. [react-native-firebase](https://www.npmjs.com/package/react-native-firebase) and [react-native-notifications](https://www.npmjs.com/package/react-native-notifications) are just the two out of many available.
-2. To setup Push Notification, you need to follow the steps mentioned in the Plugin's Documentation.
+## 3. Local configuration
-At this point, you will have:
+- Update `src/utils/AppConstants.tsx` with `appId`, `authKey`, `region`, `fcmProviderId`, and `apnProviderId`.
+- Keep `app.json` name consistent with your bundle ID / applicationId.
-1. Two separate apps created on the Firebase console. (For Android and iOS).
-2. Plugin setup completed as per the respective documentation and our reference.
+```ts lines
+const APP_ID = "";
+const AUTH_KEY = "";
+const REGION = "";
+const DEMO_UID = "cometchat-uid-1";
+```
-### Step 2: Register FCM Token
+### 3.1 Dependencies snapshot (from Sample App)
-1. This step assumes that you already have a React Native app setup with CometChat installed. Make sure that the CometChat object is initialized and user has been logged in.
-2. On the success callback of user login, you can fetch the FCM Token and register it with the extension as shown below:
+Install these dependencies in your React Native app:
-
+
-customMessage.setMetadata(metadata);
+### 5.2 Install dependencies:
-CometChat.sendCustomMessage(customMessage).then(
- (message) => {
- // Message sent successfully.
- console.log('custom message sent successfully', message);
- },
- (error) => {
- console.log('custom message sending failed with error', error);
- // Handle exception.
- }
-);
+Install the required packages for iOS push notifications:
+```bash lines
+npm install react-native-push-notification@^8.1.1
+npm install @react-native-community/push-notification-ios@^1.12.0
```
-
-
-
-
-
-
-
-
-
-
-2. The Certificate Information dialog box appears. Enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button. \ \
-
-
-3. Create new Certificate by clicking on the + icon.
-
-
-
-
-
-4. Under Services, select - Apple Push Notification services SSL (Sandbox & Production)
-
-
-
-
-
-5. Select your App ID from the dropdown.
-
-
-
-
-
-6. Upload CSR file., upload the CSR file you created through the **Choose File** button. To complete the process, choose Continue. When the certificate is ready, choose Download to save it to your Mac.
-
-
-
-
-
-
-
-
-
-#### Step 3: Export and update .p8 certificate
-
-1. To generate a .p8 key file, go to [Apple developer account page](https://developer.apple.com/account/), then select Certificates, IDs & Profiles.
-2. Select Keys and click on the "+" button to add a new key.
-3. In the new key page, type in your key name and check the Apple Push Notification service (APNs) box, then click "Continue" and click "Register".
-4. Then proceed to download the key file by clicking Download.
-5. Make note of the `Key ID`, `Team ID` and your `Bundle ID` for saving in the Extension's settings.
-
-**If you wish to use the .p12 certificate instead, do the following:**
-
-1. Type a name for the .p12 file and save it to your Mac.
-2. Browse to the location where you saved your key, select it, and click Open. Add the key ID for the key (available in Certificates, Identifiers & Profiles in the Apple Developer Member Center) and export it.
-3. DO NOT provide an export password when prompted.
-4. The .p12 file will be required in the next step for uploading in the CometChat Dashboard.
-
-#### Extension settings
-
-#### Step 1: Enable the extension
-
-1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
-2. Go to the Extensions section and Enable the Push Notifications extension.
-3. Open the settings for this extension and save the following.
-
-
-
-
-
-#### Step 2: Save your settings
-
-On the Settings page you need to enter the following:
-
-
-
-
-
-1. **Set extension version**
-
- The extension version has to be set to 'V2' or 'V1 & V2' in order to use APNs as the provider.
-
-2. **Select Platforms**
-
- You can select the platforms on which you wish to receive Push Notifications.
-
-3. **Firebase Cloud Messaging Settings**
-
- This includes the FCM Server key that you can fetch from the Firebase Dashboard.
-
-4. **APNs Settings**
-
- You can turn off the Production mode when you create a development build of your application. Upload the .p12 certificate exported in the previous step.
-
-5. **Push Notifications Title**
-
- This is usually the name of your app.
+Add the following methods to handle push notification events:
+```swift lines
+func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+ print("APNs device token received: \(deviceToken)")
+ RNCPushNotificationIOS.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
+}
-6. **Notification Triggers**
+func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
+ print("APNs registration failed: \(error)")
+ RNCPushNotificationIOS.didFailToRegisterForRemoteNotificationsWithError(error)
+}
- Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
+ RNCPushNotificationIOS.didReceiveRemoteNotification(userInfo, fetchCompletionHandler: completionHandler)
+}
- 1. Message Notifications
- 2. Call Notifications
- 3. Group Notifications
+func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
+ completionHandler([.banner, .sound, .badge])
+}
+
+func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
+ RNCPushNotificationIOS.didReceive(response)
+ completionHandler()
+}
+```
- These are pretty self-explanatory and you can toggle them as per your requirement.
+Add the following to `Podfile` to avoid framework linkage issues:
+```ruby
+use_frameworks! :linkage => :static
+```
-#### Installation
+You might have to remove below code if already present in your Podfile:
+```ruby lines
+linkage = ENV['USE_FRAMEWORKS']
+if linkage != nil
+ Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
+ use_frameworks! :linkage => linkage.to_sym
+end
+```
-We need to add two packages for this
+Then lets install pods and open the workspace:
+```bash lines
+cd ios
+pod install
+open YourProjectName.xcworkspace
+```
-* React-native-CallKeep
+### 5.4 App.tsx modifications:
-This package also require some additional installation steps. Follow [this](https://github.com/react-native-webrtc/react-native-callkeep) link to install react-native-callkeep
+Import CometChatNotifications:
-
+
+
+## How delivery works
+
+The Custom provider is triggered once for an event in one-on-one conversation. In case of notifying users in a group, the custom provider is triggered once for each user present in that group.
+
+
1. Login to [CometChat](https://app.cometchat.com/login) dashboard and select your app.
-2. Navigate to **Notifications** > **Notifications** in the left-hand menu.
+2. Navigate to **Notifications** > **Settings** in the left-hand menu.
3. Enable SMS notifications feature.
-### Save Twilio credentials
+### 4. Save Twilio credentials
@@ -41,7 +43,7 @@ Save the following details:
* Twilio Auth token
* Twilio sender phone number
-### Save user's timezone
+### 5. Save user timezones
A user's timezone is required to allow them to set a schedule for receiving notifications. In case the timezone is not registered, the default timezone for
@@ -64,7 +66,7 @@ This functionality is available in the following SDK versions:
@@ -72,210 +74,22 @@ This functionality is available in the following SDK versions:
Send a message to any user and keep the conversation unread for the designated amount of time to receive an SMS notification.
-## Custom SMS provider
-
-Custom provider allows you to make use of providers apart from Twilio for triggering SMS notifications. This is implemented using webhook URL which gets all the required details that can be used to trigger SMS notifications.
-
-#### Pre-requisite
-
-1. Your webhook endpoint must be accessible over `HTTPS`. This is essential to ensure the security and integrity of data transmission.
-2. This URL should be publicly accessible from the internet.
-3. Ensure that your endpoint supports the `HTTP POST` method. Event payloads will be delivered via `HTTP POST` requests in `JSON` format.
-4. Configure your endpoint to respond immediately to the CometChat server with a 200 OK response. The response should be sent within 2 seconds of receiving the request.
-5. For security, it is recommended to set up Basic Authentication that is usually used for server-to-server calls. This requires you to configure a username and password. Whenever your webhook URL is triggered, the HTTP Header will contain:
-
-```html
-Authorization: Basic
-
-
-#### How does it work?
-
-The Custom provider is triggered once for an event in one-on-one conversation. In case of notifying users in a group, the custom provider is triggered once for each user present in that group.
-
-
+
+
+## Delivery preferences
+
+- **Notify for unread messages only** (default: on). When enabled, send only if the conversation has unread messages.
+- **Wait time before sending the next notification (per conversation, minutes)**: default 120; min 1; max 1440.
+- **Maximum SMSes per day**: default 20.
+- **Maximum SMSes per conversation per day**: default 2.
+- **Override**: when enabled, end users can change these settings in clients that expose preferences.
+
+## SMS payload options
+
+All toggles default to off; enable per your privacy/performance needs.
+- **Include entire message object in payload**
+- **Include message metadata in payload**
+- **Include sender's metadata in payload**
+- **Include receiver's metadata in payload**
+
+Keep SMS payloads concise to avoid exceeding downstream provider limits.
+
+{/* ## Related setup
+
+- Configure templates/privacy: [Templates](/notifications/sms-templates)
+- Connect providers: [Integration](/notifications/sms-integration) or [Custom Providers](/notifications/sms-custom-providers)
+- Programmatic overrides: [Preferences](/notifications/sms-preferences) */}
\ No newline at end of file
diff --git a/notifications/sms-templates.mdx b/notifications/sms-templates.mdx
new file mode 100644
index 00000000..3db530d7
--- /dev/null
+++ b/notifications/sms-templates.mdx
@@ -0,0 +1,90 @@
+---
+title: "SMS Templates"
+---
+
+Design the SMS body users receive for unread-message alerts. Sounds do not apply to SMS. Map these payload fields into your provider template or assemble the text in your service before sending.
+
+## What to customize
+
+- **Body text** for 1:1 and group SMS (default vs privacy-friendly).
+- **Preview and counts** from `messages[]` plus `senderDetails`/`groupDetails`.
+- **Link back** to your app (add in your template).
+
+## Payload shapes
+
+Field meanings:
+- `to`: recipient identifier and phone number.
+- `messages[]`: unread messages that triggered the SMS; use for counts and previews.
+- `senderDetails`: most recent sender; helpful for subject-style copy.
+- `groupDetails`: present for group conversations.
+- `smsContent`: an optional, ready-to-send string if you want to use it directly.
+
+### One-on-one
+```json
+{
+ "to": { "uid": "cometchat-uid-1", "phno": "+919299334134", "name": "Andrew Joseph" },
+ "messages": [
+ { "sender": { "uid": "cometchat-uid-4", "name": "Susan Marie" }, "message": "Are we meeting on this weekend?" },
+ { "sender": { "uid": "cometchat-uid-4", "name": "Susan Marie" }, "message": "📷 Has shared an image" }
+ ],
+ "senderDetails": { "uid": "cometchat-uid-4", "name": "Susan Marie" },
+ "smsContent": "You've received new messages from Susan Marie! Read them at https://your-website.com/chat."
+}
+```
+
+### Group
+```json
+{
+ "to": { "uid": "cometchat-uid-1", "phno": "+919299334134", "name": "Andrew Joseph" },
+ "messages": [
+ { "sender": { "uid": "cometchat-uid-5", "name": "John Paul" }, "message": "Hello all! What's up?" },
+ { "sender": { "uid": "cometchat-uid-4", "name": "Susan Marie" }, "message": "📷 Has shared an image" }
+ ],
+ "groupDetails": { "guid": "cometchat-guid-1", "name": "Hiking Group" }
+}
+```
+
+## Template examples
+
+You can use the provided `smsContent` field or build your own using `senderDetails`, `groupDetails`, and `messages.length`. Here are default and privacy-focused templates:
+
+
+ 
+
+
+| Use case | Default template | Privacy template | Example result (default) |
+| --- | --- | --- | --- |
+| One-on-one notification | You've received `{{messages.length}}` message(s) from `{{senderDetails.name}}`! Read them at https://your-website.com. | You've received `{{messages.length}}` message(s) from `{{senderDetails.name}}`! Read them at https://your-website.com. | You've received 2 message(s) from Susan Marie! Read them at https://your-website.com. |
+| Group notification | You've received `{{messages.length}}` message(s) in `{{groupDetails.name}}`! Read them at https://your-website.com. | You've received `{{messages.length}}` message(s) in `{{groupDetails.name}}`! Read them at https://your-website.com. | You've received 2 message(s) in Hiking Group! Read them at https://your-website.com. |
+
+## Tips
+
+- Keep bodies short to respect SMS length/carrier rules; consider removing URLs in privacy mode.
+- Use `messages.length` for counts and `senderDetails.name`/`groupDetails.name` for context.
+- Add your app link in the template; ensure it is trackable and domain-verified per provider.
+
+{/* ## Example: using with your SMS gateway
+
+Pass payload fields into your SMS provider. Keep messages concise to respect SMS length limits and carrier rules.
+
+```js
+// payload from CometChat
+const payload = {
+ to: { phno: '+15551234567', name: 'Andrew Joseph' },
+ senderDetails: { name: 'Susan Marie' },
+ groupDetails: { name: 'Hiking Group' },
+ messages: [
+ { message: 'Are we meeting this weekend?' },
+ { message: '📷 Has shared an image' }
+ ]
+};
+
+// Build the SMS body using the default template
+const body = `You've received ${payload.messages.length} message(s) from ${payload.senderDetails.name}! Read them at https://your-website.com.`;
+
+// Example send with a generic gateway client
+await smsClient.send({
+ to: payload.to.phno,
+ body
+});
+``` */}
diff --git a/notifications/templates-and-sounds.mdx b/notifications/templates-and-sounds.mdx
new file mode 100644
index 00000000..8166ea0c
--- /dev/null
+++ b/notifications/templates-and-sounds.mdx
@@ -0,0 +1,308 @@
+---
+title: "Templates & Sounds"
+---
+
+Use this guide to configure **push** notification templates, understand placeholders, and set sounds.
+
+### Quick flow
+- Pick privacy mode (default, privacy, or default with user override).
+- Edit templates for each event type (titles/bodies for default and privacy).
+- Save sounds (chat/call).
+
+### How templates work
+
+- Templates define the push title/body per event type.
+- Placeholders map to event payload fields and are resolved before delivery.
+- Configure in **Dashboard → Notifications → Templates and Sounds**; privacy toggle is under **Preferences**.
+
+**Example payload (new message)**
+
+Key paths you can reference in placeholders are shown in this sample:
+
+```json theme={null}
+{
+ "data": {
+ "id": "17",
+ "conversationId": "group_cometchat-guid-1",
+ "sender": "cometchat-uid-2",
+ "receiverType": "group",
+ "receiver": "cometchat-guid-1",
+ "category": "message",
+ "type": "text",
+ "data": {
+ "text": "Hello! How are you?",
+ "entities": {
+ "sender": {
+ "entity": {
+ "uid": "cometchat-uid-2",
+ "name": "George Alan",
+ "role": "default",
+ "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp",
+ "status": "available",
+ "lastActiveAt": 1707901272
+ },
+ "entityType": "user"
+ },
+ "receiver": {
+ "entity": {
+ "guid": "cometchat-guid-1",
+ "icon": "https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp",
+ "name": "Hiking Group",
+ "type": "public",
+ "owner": "cometchat-uid-1",
+ "createdAt": 1706014061,
+ "conversationId": "group_cometchat-guid-1",
+ "onlineMembersCount": 3
+ },
+ "entityType": "group"
+ }
+ },
+ },
+ "sentAt": 1707902030,
+ "updatedAt": 1707902030
+ }
+}
+```
+
+The sender's name lives at `message.data.entities.sender.entity.name`, so use `{{message.data.entities.sender.entity.name}}` in templates.
+
+### Templates
+
+#### 1. Text message templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body | `{{message.data.text}}` | New message |
+
+#### 2. Media message templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body for Image | 📷 Has sent an image | New image message |
+| Body for Audio | 🔈 Has sent an audio | New audio message |
+| Body for Video | 🎥 Has sent a video | New video message |
+| Body for File | 📄 Has sent a file | New file message |
+
+#### 3. Custom message templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body | `{{message.data.text}}` | `{{message.data.text}}` |
+| Body (Fallback) | New message | New message |
+
+**Note:** The "Body (Fallback)" value is utilized when any placeholders within the "Body" fail to resolve to an appropriate substitution value.
+
+**For example**, if `{{message.data.text}}` in the aforementioned scenario evaluates to `null` or `undefined`, the "Body (Fallback)" value will be utilized.
+
+Ideally, the "Body (Fallback)" value should not contain any placeholders to prevent additional resolution failures.
+
+#### 4. Interactive form templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body | `{{data.interactiveData.title}}` | New message |
+
+#### 5. Interactive card templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body | `{{message.data.interactiveData.text}}` | New message |
+
+#### 6. Interactive scheduler templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body | New invite | New invite |
+
+#### 7. Custom Interactive message templates
+
+| Template for | Default template values | Privacy template values |
+| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Title (One-on-one) | `{{message.data.entities.sender.entity.name}}` | `{{message.data.entities.sender.entity.name}}` |
+| Title (Group) | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` | `{{message.data.entities.sender.entity.name}}` @ `{{message.data.entities.receiver.entity.name}}` |
+| Body | New message | New message |
+
+
+### Dashboard configuration
+
+Choose how templates apply to users: **default, privacy, or default with user override** (Privacy Setting dropdown in the dashboard).
+
+#### Client-side implementation
+
+**1. Fetch privacy setting**
+
+Fetch/update the privacy toggle so users can opt in when allowed.
+
+
+
+
+This is a simple 3 step process where:
+
+1. You give a name to your project
+2. Add Google Analytics to your project (Optional)
+3. Configure Google Analytics account (Optional)
+
+Click on Create and you are ready to go.
+
+### Step 2: Add Firebase to your Web App
+
+1. Click on the Web icon on the below screen and Register your app with a nickname.
+2. Once done, click on Continue to Console.
+
+
+ 
+
+
+### Step 3: Download the service account file
+
+
+
+
+
+## Extension settings
+
+### Step 1: Enable the extension
+
+1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
+2. Go to the Extensions section and Enable the Push Notifications.
+3. Open the settings for the extension and add all the mentioned settings and hit save.
+
+
+
+
+
+### Step 2: Save your settings
+
+On the Settings page you need to enter the following:
+
+1. **Set extension version**
+
+* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
+* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
+* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
+
+2. **Select the platforms that you want to support**
+
+* Select from Web, Android, Ionic, React Native, Flutter & iOS.
+
+3. **Notification payload settings**
+
+* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
+
+4. **Push payload message options**
+
+
+
+
+
+* The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
+
+* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+
+5. **Notification Triggers**
+
+
+
+
+
+* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
+
+ 1. Message Notifications
+ 2. Call Notifications
+ 3. Group Notifications
+
+* These are pretty self-explanatory and you can toggle them as per your requirement.
+
+## Web App Setup
+
+### Step 1: Folder and files setup
+
+Create a folder with the following three files:
+
+| Files | Description |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| index.html | Displays a simple User Login Form. |
+| PushNotification.js | File with the logic to initialize CometChat and Firebase. |
+| firebase-messaging-sw\.js | Service worker shows Push Notifications when the tab is either in the background or closed. |
+
+### Step 2: Add the Firebase Config to the HTML File
+
+1. Go to the Firebase Console and click on the Web app and open up the Settings page.
+2. Go to the "General" tab on the Settings page.
+3. Scroll down and copy the Firebase SDK snippet and paste in the \ tag of your index.html file.
+
+
+ 
+
+
+### Step 3: Setup index.html file
+
+1. Include the latest CometChat library using CDN.
+
+2. Register the service worker file.
+
+3. Also, include the `PushNotification.js`.
+
+4. The \ has a simple form:
+
+ 1. Text input for UID.
+ 2. Login button.
+ 3. Logout button.
+
+Once done, your `index.html` file should look like this:
+
+
-
-
-This is a simple 3 step process where:
-
-1. You give a name to your project
-2. Add Google Analytics to your project (Optional)
-3. Configure Google Analytics account (Optional)
-
-Click on Create and you are ready to go.
-
-### Step 2: Add Firebase to your Web App
+## What this guide covers
-1. Click on the Web icon on the below screen and Register your app with a nickname.
-2. Once done, click on Continue to Console.
+- CometChat dashboard setup (FCM provider + Provider ID) and Firebase web config + VAPID key.
+- Service worker + Firebase Messaging wiring for foreground/background pushes.
+- Token registration/unregistration with `CometChatNotifications` and navigation on notification click.
+- Testing and troubleshooting tips for web push.
-
-
-
+{/* ## What you need first
-### Step 3: Download the service account file
+- CometChat App ID, Region, Auth Key; Push Notifications enabled with an **FCM provider** (copy the Provider ID).
+- Firebase project with a **Web app** registered; Firebase config object; **VAPID key** from Cloud Messaging.
+- Node 18+ and a modern browser that supports service workers/notifications. */}
-
-
-
+## How CometChat + FCM work on web
-## Extension settings
+- **Provider ID**: Tells CometChat which Firebase credentials to use when sending to your web app.
+- **Tokens**: `getToken` returns a browser token (per origin/device). Register it after login:
+ `CometChatNotifications.registerPushToken(token, CometChatNotifications.PushPlatforms.FCM_WEB, providerId)`.
+- **Handlers**: Foreground messages come via `messaging.onMessage`; background uses `firebase-messaging-sw.js` with `onBackgroundMessage`.
+- **Navigation**: Service worker sends a postMessage or focuses the client; the app routes to the right view.
-### Step 1: Enable the extension
+## 1. Dashboard: enable push + add FCM provider
-1. Login to [CometChat](https://app.cometchat.com/login) and select your app.
-2. Go to the Extensions section and Enable the Push Notifications extension.
-3. Open the settings for the extension and add all the mentioned settings and hit save.
+1. Go to **Notifications → Settings** and enable **Push Notifications**.
+2. Add/configure an **FCM** provider and copy the **Provider ID** (used in code).
-
+
-### Step 2: Save your settings
-
-On the Settings page you need to enter the following:
-
-1. **Set extension version**
-
-* If you are setting it for the first time, Select `V2` to start using the token-based version of the Push Notification extension.
-* If you already have an app using `V1` and want to migrate your app to use `V2`, then Select `V1 & V2` option. This ensures that the users viewing the older version of your app also receive Push Notifications.
-* Eventually, when all your users are on the latest version of your app, you can change this option to `V2`, thus turning off `V1` (Topic-based) Push Notifications completely.
+## 2. Firebase setup (web app + VAPID)
-2. **Select the platforms that you want to support**
-
-* Select from Web, Android, Ionic, React Native, Flutter & iOS.
-
-3. **Notification payload settings**
-
-* You can control if the notification key should be in the Payload or not. Learn more about the FCM Messages [here](https://firebase.google.com/docs/cloud-messaging/concept-options).
-
-4. **Push payload message options**
+1. In Firebase Console, create/select a project.
+2. Add a **Web** app (``), copy the **Firebase config** object.
+3. In **Project settings → Cloud Messaging**, generate/copy the **VAPID key** under Web Push certificates.
-
+ 
-* The maximum payload size supported by FCM and APNs for push notifications is approximately 4 KB. Due to the inclusion of CometChat's message object, the payload size may exceed this limit, potentially leading to non-delivery of push notifications for certain messages. The options provided allow you to remove the sender's metadata, receiver's metadata, message metadata and trim the content of the text field.
-
-* The message metadata includes the outputs of the Thumbnail Generation, Image Moderation, and Smart Replies extensions. You may want to retain this metadata if you need to customize the notification displayed to the end user based on these outputs.
+## 3. Install dependencies
-5. **Notification Triggers**
+Install firebase SDK:
-
-
-
-
-* Select the triggers for sending Push Notifications. These triggers can be classified into 3 main categories:
-
- 1. Message Notifications
- 2. Call Notifications
- 3. Group Notifications
-
-* These are pretty self-explanatory and you can toggle them as per your requirement.
-
-## Web App Setup
-
-### Step 1: Folder and files setup
-
-Create a folder with the following three files:
+```bash
+npm install firebase@^10.3.1
+```
-| Files | Description |
-| ------------------------- | ------------------------------------------------------------------------------------------- |
-| index.html | Displays a simple User Login Form. |
-| PushNotification.js | File with the logic to initialize CometChat and Firebase. |
-| firebase-messaging-sw\.js | Service worker shows Push Notifications when the tab is either in the background or closed. |
+## 4. Constants
-### Step 2: Add the Firebase Config to the HTML File
+File: `src/AppConstants.js` (or equivalent)
-1. Go to the Firebase Console and click on the Web app and open up the Settings page.
-2. Go to the "General" tab on the Settings page.
-3. Scroll down and copy the Firebase SDK snippet and paste in the \ tag of your index.html file.
+Set the CometChat Constants from your dashboard and Firebase config + VAPID key.
-
-
-
+```js lines highlight={2-5, 9-15, 18}
+export const COMETCHAT_CONSTANTS = {
+ APP_ID: "",
+ REGION: "",
+ AUTH_KEY: "",
+ FCM_PROVIDER_ID: "",
+};
-### Step 3: Setup index.html file
+export const FIREBASE_CONFIG = {
+ apiKey: "",
+ authDomain: "",
+ projectId: "",
+ storageBucket: "",
+ messagingSenderId: "",
+ appId: "",
+ measurementId: ""
+};
-1. Include the latest CometChat library using CDN.
+export const FIREBASE_VAPID_KEY = "";
+```
-2. Register the service worker file.
+## 4. Configure Firebase (frontend)
-3. Also, include the `PushNotification.js`.
+File: `src/firebase.js` (or equivalent)
-4. The \ has a simple form:
+This code:
+- Initializes Firebase app and messaging.
+- Requests notification permission, fetches FCM token, and registers it with CometChat after login.
+- Sets up foreground message handler to show notifications.
- 1. Text input for UID.
- 2. Login button.
- 3. Logout button.
+```js lines
+import { initializeApp } from "firebase/app";
+import { getMessaging, getToken, onMessage } from "firebase/messaging";
+import { CometChatNotifications } from "@cometchat/chat-sdk-javascript";
+import { COMETCHAT_CONSTANTS, FIREBASE_CONFIG, FIREBASE_VAPID_KEY } from "./AppConstants";
-Once done, your `index.html` file should look like this:
+let messagingInstance = null;
-