Mentions and Notifications

Use @mentions to grab attention and manage your notification preferences

Mentions in New Expensify help you direct messages to specific people, ensuring important communications don’t get lost in busy chat threads. Combined with smart notification preferences, you stay informed without being overwhelmed.

Using @Mentions

Basic Mentions

Mention someone by typing @ followed by their name:

1. Start Typing

   Type @ in the message composer

2. Select Person

   A list of participants appears. Start typing their name to filter, then select from the list.

3. Complete Message

   Continue your message. The mention is highlighted in the text.

4. Send

   Press Enter to send. The mentioned person receives a notification.

Mentioned users receive a push notification and see the message highlighted in their chat list, even if they have notifications muted for that conversation.

Mention Rendering

Mentions are stored as markdown and rendered as clickable elements:

// Mention parsing from contributingGuides/MENTIONS_HIGHLIGHTING_IN_CHAT.md
// Example markdown format:
"@[e-mail]"

// Rendered as clickable user profile link
<Mention 
  accountID={user.accountID}
  displayName="User Name"
  onPress={() => Navigation.navigate(ROUTES.PROFILE.getRoute(accountID))}
/>

Mention Types

User Mentions

Mention specific people by their name or email:

@[e-mail] can you review this?

The mention links to their profile and sends them a notification.

Room Mentions

Mention entire chat rooms (not yet fully implemented):

@#announce important update for everyone

Notifies all room participants.

Here Mention

Notify all active participants:

@here quick question for whoever is online

Only sends to currently active users.

Be thoughtful with broad mentions like @here or room mentions—they notify many people simultaneously.

Mention Suggestions

The mention autocomplete intelligently suggests users based on:

• Current conversation participants
• Recent chat contacts
• Workspace members
• Email domain matches
• Display name and email fuzzy matching

// Mention search from src/libs/actions/Report/index.ts
function searchForUsers(searchInput: string) {
    const parameters: SearchForUsersParams = {
        searchInput: searchInput.trim(),
    };
    
    API.read(
        READ_COMMANDS.SEARCH_FOR_USERS,
        parameters,
        {
            optimisticData,
            successData,
            failureData,
        }
    );
}

Notification System

Notification Preferences

Control how you’re notified for each conversation:

Always

Always: Receive notifications for every message

Best for:

• Important 1-on-1 conversations
• Critical project chats
• Direct reports or manager chats

Mentions Only

Mentions Only: Only notify when you’re @mentioned

Best for:

• Large group chats
• General team channels
• Workspace rooms you monitor occasionally

Hidden

Hidden: No notifications, chat hidden from main list

Best for:

• Archived conversations
• Old projects
• Chats you don’t need to follow

Setting Preferences

// Update notification preference from src/libs/actions/Report/index.ts
function updateNotificationPreference(
    reportID: string,
    previousValue: NotificationPreference,
    newValue: NotificationPreference,
) {
    const optimisticData: OnyxUpdate[] = [
        {
            onyxMethod: Onyx.METHOD.MERGE,
            key: `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
            value: {
                participants: {
                    [currentUserAccountID]: {
                        notificationPreference: newValue,
                    },
                },
            },
        },
    ];
    
    const parameters: UpdateReportNotificationPreferenceParams = {
        reportID,
        notificationPreference: newValue,
    };
    
    API.write(
        WRITE_COMMANDS.UPDATE_REPORT_NOTIFICATION_PREFERENCE,
        parameters,
        {optimisticData, successData, failureData}
    );
}

1. Open Chat Settings

   Click the chat name or avatar at the top of the conversation.

2. Change Preference

   Select Notification Preference and choose your preferred setting.

3. Save

   The preference saves automatically and applies immediately.

Notification Channels

Push Notifications

Receive alerts on your device even when the app is closed:

Mobile

Native push notifications on iOS and Android via Firebase Cloud Messaging

Desktop

System notifications on macOS and Windows desktop apps

Web

Browser notifications when granted permission

Email

Email summaries for important activity (configurable)

In-App Notifications

See notifications within the app:

• Badge counts on chat list items
• Unread indicators for new messages
• Mention highlights for @mentions
• Red dot for priority notifications

Mention Resolving

For actionable mentions, you can resolve them to mark as handled:

// Resolve actionable mention from src/libs/actions/Report/index.ts
function resolveActionableMentionWhisper(
    reportID: string,
    reportAction: ReportAction,
    resolution: Decision,
) {
    const optimisticData: OnyxUpdate[] = [
        {
            onyxMethod: Onyx.METHOD.MERGE,
            key: `${ONYXKEYS.COLLECTION.REPORT_ACTIONS}${reportID}`,
            value: {
                [reportAction.reportActionID]: {
                    originalMessage: {
                        resolution,
                    },
                },
            },
        },
    ];
    
    const parameters: ResolveActionableMentionWhisperParams = {
        reportActionID: reportAction.reportActionID,
        resolution,
    };
    
    API.write(
        WRITE_COMMANDS.RESOLVE_ACTIONABLE_MENTION_WHISPER,
        parameters,
        {optimisticData, failureData}
    );
}

Managing Unread Messages

Mark as Read

Manually mark conversations as read:

1. Select Conversation

   Right-click (or long-press on mobile) the conversation in your chat list.

2. Mark as Read

   Select Mark as Read from the context menu.

3. Confirmation

   The unread badge disappears immediately.

// Mark as read from src/libs/actions/Report/index.ts
function readNewestAction(reportID: string) {
    const lastReadTime = DateUtils.getDBTime();
    
    const optimisticData: OnyxUpdate[] = [
        {
            onyxMethod: Onyx.METHOD.MERGE,
            key: `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
            value: {
                lastReadTime,
            },
        },
    ];
    
    const parameters: ReadNewestActionParams = {
        reportID,
        lastReadTime,
    };
    
    API.write(
        WRITE_COMMANDS.READ_NEWEST_ACTION,
        parameters,
        {optimisticData}
    );
}

Mark as Unread

Flag a conversation for follow-up:

// Mark as unread from src/libs/actions/Report/index.ts  
function markAsUnread(
    reportID: string,
    lastReadTime: string,
) {
    const optimisticData: OnyxUpdate[] = [
        {
            onyxMethod: Onyx.METHOD.MERGE,
            key: `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
            value: {
                lastReadTime,
            },
        },
    ];
    
    const parameters: MarkAsUnreadParams = {
        reportID,
        lastReadTime,
    };
    
    API.write(
        WRITE_COMMANDS.MARK_AS_UNREAD,
        parameters,
        {optimisticData, failureData}
    );
}

Email Digests

Receive periodic email summaries:

• Immediate: Email for every mention (not recommended)
• Hourly: Summary every hour
• Daily: Once-daily digest
• Never: No email notifications

Email preferences are managed in your account settings under Preferences > Notifications.

Notification Best Practices

Use Mentions Sparingly

Only @mention people when you specifically need their attention. Overusing mentions can lead to notification fatigue.

Set Smart Defaults

Configure notification preferences for each conversation type:

• Always for your direct reports
• Mentions Only for large team channels
• Hidden for completed project chats

Check Notifications Regularly

Review your notification center daily to ensure you don’t miss important mentions, especially in “mentions only” chats.

Use Do Not Disturb

Enable Do Not Disturb mode during focused work time. You’ll still see messages when you open the app, but won’t receive push notifications.

Customize Per Platform

You might want different notification settings on mobile (fewer) vs. desktop (more) based on how you use each platform.

Troubleshooting

Not Receiving Notifications

1. Check app notification permissions in device settings
2. Verify notification preference isn’t set to “Hidden”
3. Ensure you’re not in Do Not Disturb mode
4. Check that the app is updated to the latest version

Too Many Notifications

1. Change busy chats to “Mentions Only”
2. Use Do Not Disturb during focused work hours
3. Mute non-urgent conversations
4. Adjust email digest frequency

Mentions Not Working

1. Ensure you’re typing @ followed by the exact email or selecting from the dropdown
2. Verify the mentioned person has access to the conversation
3. Check that mention syntax is correct (no spaces after @)

Advanced: Mention Implementation

For developers, here’s how mentions work under the hood:

// From contributingGuides/MENTIONS_HIGHLIGHTING_IN_CHAT.md

// 1. Mention detection in input
const mentionRegex = /@([\w.\-+]+@[\w.\-]+\.\w+)/g;

// 2. Convert to markdown for storage  
const markdownText = text.replace(
    mentionRegex,
    '@$1'
);

// 3. Render with styling
const renderMention = (accountID: number) => (
    <Text 
        style={styles.mention}
        onPress={() => navigateToProfile(accountID)}
    >
        @{displayName}
    </Text>
);

// 4. Send notification to mentioned user
function notifyMentionedUsers(reportAction: ReportAction) {
    const mentions = extractMentions(reportAction.message);
    mentions.forEach(accountID => {
        sendPushNotification(accountID, reportAction);
    });
}

Next Steps

Chat Overview

Back to chat features overview

Task Management

Learn about creating and managing tasks

Messaging

Master message formatting and threads

Mobile Features

Platform-specific notification settings