Mentions and Notifications

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:

Start Typing

Type @ in the message composer

Select Person

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

Complete Message

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

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:
"@user@example.com"

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

Mention Types

User Mentions
Room Mentions
Here Mention

Mention specific people by their name or email:

@john.doe@company.com can you review this?

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

Mention entire chat rooms (not yet fully implemented):

@#announce important update for everyone

Notifies all room participants.

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
Mentions Only
Hidden

Always: Receive notifications for every messageBest for:

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

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}
    );
}

Open Chat Settings

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

Change Preference

Select Notification Preference and choose your preferred setting.

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:

Select Conversation

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

Mark as Read

Select Mark as Read from the context menu.

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

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

Too Many Notifications

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

Mentions Not Working

Ensure you’re typing @ followed by the exact email or selecting from the dropdown
Verify the mentioned person has access to the conversation
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

Expenses

Reports

Chat & Collaboration

Workspaces

Subscription

Search

Mentions and Notifications

Using @Mentions

Basic Mentions

Mention Rendering

Mention Types

Mention Suggestions

Notification System

Notification Preferences

Setting Preferences

Notification Channels

Push Notifications

Mobile

Desktop

Web

Email

In-App Notifications

Mention Resolving

Managing Unread Messages

Mark as Read

Mark as Unread

Email Digests

Notification Best Practices

Troubleshooting

Advanced: Mention Implementation

Next Steps

Chat Overview

Task Management

Messaging

Mobile Features

​Using @Mentions

​Basic Mentions

​Mention Rendering

​Mention Types

​Mention Suggestions

​Notification System

​Notification Preferences

​Setting Preferences

​Notification Channels

​Push Notifications

Mobile

Desktop

Web

Email

​In-App Notifications

​Mention Resolving

​Managing Unread Messages

​Mark as Read

​Mark as Unread

​Email Digests

​Notification Best Practices

​Troubleshooting

​Advanced: Mention Implementation

​Next Steps

Chat Overview

Task Management

Messaging

Mobile Features

Using @Mentions

Basic Mentions

Mention Rendering

Mention Types

Mention Suggestions

Notification System

Notification Preferences

Setting Preferences

Notification Channels

Push Notifications

In-App Notifications

Mention Resolving

Managing Unread Messages

Mark as Read

Mark as Unread

Email Digests

Notification Best Practices

Troubleshooting

Advanced: Mention Implementation

Next Steps