Templates & Sounds

Common templates and sounds

Templates are designed to specify the content displayed in notifications on the user’s device for different events.

Templates incorporate placeholders, which reference specific pieces of information determined by properties from the event.

For example, New message event has the following structure:

{
  "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 is accessible via data.entities.sender.name, so the placeholder for the sender’s name will be {{message.data.entities.sender.name}}. This placeholder is substituted within the template with the actual name of the sender aka the substitution value.

As an administrator, you can configure:

1. Default templates - Use these templates to display previews by leveraging the information contained in the event.
2. Privacy templates - Employ these templates to present generic content in the notification.

Privacy setting

Dashboard configuration

Configure which template will be used for displaying the content of the notifications displayed on user’s devices. The available preferences are:

1. Use default template - Enforces the use of default templates for all the users.
2. Use privacy template - Enforces the use of privacy templates for all the users.
3. Use default templates with user privacy override (Default) - Uses default templates by default, but allows the users to enable privacy to hide the previews.

Client-side implementation

1. Fetch privacy setting

The method CometChatNotifications.fetchPreferences() retrieves the notification preferences saved by the user 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 utilized.

JavaScript

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

// Display a toggle for use privacy option TODO
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.

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.

It is unnecessary to specify all values; only set and save the preferences that have been changed.

JavaScript

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

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

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

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.

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

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	{{data.interactiveData.title}}	New message

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

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

Sounds

The sound files must be included within the app’s bundle. These values are set within the notification payload as values of the “sound” field.

Sound for Call Notifications: Specify the name of the sound file you wish to play for call notifications.

Sound for Chat Notifications: Specify the name of the sound file you wish to play for chat notifications.

Field	Default
Calls	default
Sounds	default