Templates & Sounds

Configure CometChat push notification templates, privacy modes, placeholders, and chat or call notification 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. User mention templates

User mention templates are used when a text message contains an @mention of a specific user. Only the mentioned user receives the notification using these templates — other recipients of the same message continue to receive the standard text message template.

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 (One-on-one)	{{message.data.entities.sender.entity.name}} mentioned you: {{message.data.text}}	New mention
Body (Group)	{{message.data.entities.sender.entity.name}} mentioned you in {{message.data.entities.receiver.entity.name}}: {{message.data.text}}	New mention
Body (Fallback)	New mention	New mention

Applies to text messages (category: "message", type: "text") where the recipient is specifically @mentioned. If a message contains both @user and @all, the specifically mentioned user gets the user mention template (higher priority).

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.

3. @all mention templates

@all mention templates are used when a text message contains an @all mention in a group conversation.

Group members who are not individually @mentioned receive notifications using these templates. Individually mentioned users receive notifications using the user mention templates instead.

Template for	Default template values	Privacy template values
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.entities.sender.entity.name}} mentioned everyone: {{message.data.text}}	New mention
Body (Fallback)	New mention	New mention

Applies to text messages (category: "message", type: "text") where the message contains @all in a group conversation.

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

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

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

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

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

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

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

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

Group call notifications

Group call notifications (e.g., “User started a group call”) are sent as custom messages (category: "custom"), not as group action messages. This means they are governed by the custom message templates above, and the GROUP_ACTIONS_PREFERENCE setting does not affect group call notifications.

If you want to suppress or customize group call notifications independently, configure the custom message template or handle them in your client-side notification logic.

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