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:

{
  "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.

By default, messages with category: "custom" do not trigger any notifications (push, email, or SMS). To opt in, set sendNotification: true in the message’s data payload.

sendNotification value	Behavior
true	Notifications are processed normally across all channels
false or not set	The message is silently skipped — no notifications are sent

Set sendNotification: true for custom messages that represent user-facing activity (e.g., polls, payments, shared locations). Omit the flag for background or system-level custom messages that should not interrupt the recipient.

4. Poll 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	Poll: {{message.data.text}}	New message
Body (Fallback)	New message	New message

Applies to messages with category: "custom" and type: "extension_poll". Poll templates use the same structure as custom message templates and can be customized independently — for example, setting the privacy body to “New poll” instead of the generic fallback.

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.

5. Reminder 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
Body (Fallback)	New message	New message

Applies to messages with category: "custom" and type: "extension_reminders". Reminder templates use the same structure as custom message templates and can be customized independently — for example, setting the privacy body to “New reminder” instead of the generic fallback.

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.

6. 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

7. 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

8. 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

9. 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.

JavaScript

// This is applicable for web, React native, Ionic cordova (Ionic Cordova is deprecated - use JavaScript SDK)
const preferences = await CometChatNotifications.fetchPreferences();

// Display a toggle for use privacy option
const usePrivacyTemplate = preferences.getUsePrivacyTemplate();

Android

CometChatNotifications.fetchPreferences(new CometChat.CallbackListener<NotificationPreferences>() {
  @Override
  public void onSuccess(NotificationPreferences notificationPreferences) {
      // Display a toggle for use privacy option
      boolean usePrivacyTemplate = notificationPreferences.getUsePrivacyTemplate();
  }

  @Override
  public void onError(CometChatException e) {
      // Something went wrong while fetching notification preferences
  }
});

iOS

CometChatNotifications.fetchPreferences { notificationPreferences in
  // Display a toggle for use privacy option
  let usePrivacyTemplate = notificationPreferences.usePrivacyTemplate;

} onError: { error in
  // Something went wrong while fetching notification preferences.
  print("fetchPreferences: \(error.errorCode) \(error.errorDescription)");
}

Flutter

CometChatNotifications.fetchPreferences(
    onSuccess: (notificationPreferences) {
      // Display a toggle for use privacy option
      bool? usePrivacyTemplate = notificationPreferences.usePrivacyTemplate;

    },
    onError: (e) {
      debugPrint("fetchPreferences:error ${e.toString()}");
    });

2. Update privacy setting

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.

Use this sparingly to avoid surprising users. Set only the preferences that changed.

JavaScript

// This is applicable for web, React native, Ionic cordova (Ionic Cordova is deprecated - use JavaScript SDK)
// The example demonstrates modifying all values; however, modifying only the changed values is sufficient.

// Instantiate the NotificationPreferences.
const updatedPreferences = new NotificationPreferences();

// To update the preference for privacy template
updatedPreferences.setUsePrivacyTemplate(true);

// Update the preferences and receive the updated copy.
const notificationPreferences = await CometChatNotifications.updatePreferences(
  updatedPreferences
);

Android

// The example demonstrates modifying all values; however, modifying only the changed values is sufficient.
// Instantiate the NotificationPreferences.
NotificationPreferences updatedPreferences = new NotificationPreferences();

// To update the preference for privacy template
updatedPreferences.setUsePrivacyTemplate(true);

// Update the preferences.
CometChatNotifications.updatePreferences(updatedPreferences, new CometChat.CallbackListener<NotificationPreferences>() {
    @Override
    public void onSuccess(NotificationPreferences notificationPreferences) {
        // Updated notificationPreferences
    }

    @Override
    public void onError(CometChatException e) {
        // Something went wrong
    }
});

iOS

// The example demonstrates modifying all values; however, modifying only the changed values is sufficient.

// Instantiate the NotificationPreferences.
let updatedPreferences = CometChatNotifications.NotificationPreferences();

// To update the preference for privacy template
updatedPreferences.set(usePrivacyTemplate: true)

// Update the preferences.
CometChatNotifications.updatePreferences(updatedPreferences) { prefs in
    print("updatePreferences: \(prefs)")
} onError: { error in
    print("updatePreferences: \(error.errorCode) \(error.errorDescription)")
}

Flutter

// The example demonstrates modifying all values; however, modifying only the changed values is sufficient.

// Instantiate the NotificationPreferences
NotificationPreferences updatedPreferences = NotificationPreferences();

// To update the preference for privacy template
updatedPreferences.usePrivacyTemplate = true;

// Update the preferences.
CometChatNotifications.updatePreferences(updatedPreferences,
    onSuccess: (preferencesAfterUpdate) {
  debugPrint("updatePreferences:success");
  // Use the preferencesAfterUpdate
}, onError: (e) {
  debugPrint("updatePreferences:error: ${e.toString()}");
});

Template tips

• Keep privacy variants generic to avoid leaking message content.
• Use sender@group style for group titles to disambiguate conversations.
• Avoid placeholders in fallback text to prevent unresolved values.

Sounds

Include sound files in your app bundle and set the sound field in the push payload to the filename (omit extension if your platform expects that).

Field	Default
Calls	default
Sound	default