Templates & Sounds - CometChat Docs

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.

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.

JavaScript
Android
iOS
Flutter

// This is applicable for web, React native, Ionic cordova
const preferences = await CometChatNotifications.fetchPreferences();

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

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
  }
});

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)");
}

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
Android
iOS
Flutter

// This is applicable for web, React native, Ionic cordova
// 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
);

// 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
    }
});

// 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)")
}

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

Getting Started

​Quick flow

​How templates work

​Templates

​1. Text message templates

​2. Media message templates

​3. Custom message templates

​4. Interactive form templates

​5. Interactive card templates

​6. Interactive scheduler templates

​7. Custom Interactive message templates

​Dashboard configuration

​Client-side implementation

​Template tips

​Sounds