Skip to content

Add user mention and @all mention notification templates docs and API… #332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Afroz-Cometchat wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add user mention and @all mention notification templates docs and API… #332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
46d5265
Add user mention and @all mention notification templates docs and API…
Afroz-Cometchat Apr 13, 2026
7aab77c
Remove unnecessary group-only explanation from @all mention templates
Afroz-Cometchat Apr 14, 2026
eaafe65
Improve @all mention description and add hyperlink to user mention te…
Afroz-Cometchat Apr 15, 2026
a6488b9
Move @all mention routing note into Note component
Afroz-Cometchat Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions chat-apis.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16916,6 +16916,18 @@
"textMessageTemplatePrivacy": {
"$ref": "#/components/schemas/Template"
},
"userMentionTemplateDefault": {
"$ref": "#/components/schemas/UserMentionTemplate"
},
"userMentionTemplatePrivacy": {
"$ref": "#/components/schemas/UserMentionTemplate"
},
"groupMentionTemplateDefault": {
"$ref": "#/components/schemas/GroupMentionTemplate"
},
"groupMentionTemplatePrivacy": {
"$ref": "#/components/schemas/GroupMentionTemplate"
},
"mediaMessageTemplateDefault": {
"$ref": "#/components/schemas/MediaMessageTemplate"
},
Expand Down Expand Up @@ -17031,6 +17043,50 @@
},
"type": "object"
},
"UserMentionTemplate": {
"description": "Push notification template for user @mentions. User mentions can occur in both one-on-one and group conversations.",
"properties": {
"titleOneOnOne": {
"type": "string",
"example": "{{message.data.entities.sender.entity.name}}"
},
"titleGroup": {
"type": "string",
"example": "{{message.data.entities.sender.entity.name}} @ {{message.data.entities.receiver.entity.name}}"
},
"bodyOneOnOne": {
"type": "string",
"example": "{{message.data.entities.sender.entity.name}} mentioned you: {{message.data.text}}"
},
"bodyGroup": {
"type": "string",
"example": "{{message.data.entities.sender.entity.name}} mentioned you in {{message.data.entities.receiver.entity.name}}: {{message.data.text}}"
},
"body_fallback": {
"type": "string",
"example": "New mention"
}
},
"type": "object"
},
"GroupMentionTemplate": {
"description": "Push notification template for @all mentions.",
"properties": {
"titleGroup": {
"type": "string",
"example": "{{message.data.entities.sender.entity.name}} @ {{message.data.entities.receiver.entity.name}}"
},
"body": {
"type": "string",
"example": "{{message.data.entities.sender.entity.name}} mentioned everyone: {{message.data.text}}"
},
"body_fallback": {
"type": "string",
"example": "New mention"
}
},
"type": "object"
},
"TimeRange": {
"required": [
"from",
Expand Down
2 changes: 1 addition & 1 deletion fundamentals/polls.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,6 @@ A sample response for the results is as follows:

## Notifications

<Card title="Notification templates" href="/notifications/templates-and-sounds#4-poll-message-templates">
<Card title="Notification templates" href="/notifications/templates-and-sounds#6-poll-message-templates">
Customize the push, email, and SMS notification templates for poll messages.
</Card>
2 changes: 1 addition & 1 deletion fundamentals/reminders.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,6 @@ Learn more about [Custom messages listener](/sdk/javascript/receive-message#real

## Notifications

<Card title="Notification templates" href="/notifications/templates-and-sounds#5-reminder-message-templates">
<Card title="Notification templates" href="/notifications/templates-and-sounds#7-reminder-message-templates">
Customize the push, email, and SMS notification templates for reminder messages.
</Card>
58 changes: 50 additions & 8 deletions notifications/templates-and-sounds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,49 @@ The sender's name lives at `message.data.entities.sender.entity.name`, so use `{
| 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
#### 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.

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

| 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 |
| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
Expand All @@ -87,7 +129,7 @@ The sender's name lives at `message.data.entities.sender.entity.name`, so use `{
| Body for Video | 🎥 Has sent a video | New video message |
| Body for File | 📄 Has sent a file | New file message |

#### 3. Custom message templates
#### 5. Custom message templates

| Template for | Default template values | Privacy template values |
| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
Expand All @@ -113,7 +155,7 @@ By default, messages with `category: "custom"` do not trigger any notifications
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.
</Note>

#### 4. Poll message templates
#### 6. Poll message templates

| Template for | Default template values | Privacy template values |
| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
Expand All @@ -130,7 +172,7 @@ Applies to messages with `category: "custom"` and `type: "extension_poll"`. Poll

Ideally, the "Body (Fallback)" value should not contain any placeholders to prevent additional resolution failures.

#### 5. Reminder message templates
#### 7. Reminder message templates

| Template for | Default template values | Privacy template values |
| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
Expand All @@ -147,31 +189,31 @@ Applies to messages with `category: "custom"` and `type: "extension_reminders"`.

Ideally, the "Body (Fallback)" value should not contain any placeholders to prevent additional resolution failures.

#### 6. Interactive form templates
#### 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 |

#### 7. Interactive card templates
#### 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 |

#### 8. Interactive scheduler templates
#### 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 |

#### 9. Custom Interactive message templates
#### 11. Custom Interactive message templates

| Template for | Default template values | Privacy template values |
| ------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
Expand Down