> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Templates & Sounds
> Templates & Sounds — CometChat documentation.
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} 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. 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](#2-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.
```js theme={null} theme={null}
// 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();
```
```kotlin theme={null} theme={null}
CometChatNotifications.fetchPreferences(new CometChat.CallbackListener() {
@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
}
});
```
```swift theme={null} theme={null}
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)");
}
```
```dart theme={null} theme={null}
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.
```js theme={null} theme={null}
// 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
);
```
```kotlin theme={null} theme={null}
// 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() {
@Override
public void onSuccess(NotificationPreferences notificationPreferences) {
// Updated notificationPreferences
}
@Override
public void onError(CometChatException e) {
// Something went wrong
}
});
```
```swift theme={null} theme={null}
// 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)")
}
```
```dart theme={null} theme={null}
// 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](#5-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 |