Skip to main content
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:
"@[email protected]"

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

​
Mention Types

Mention specific people by their name or email:
@[email protected] can you review this?
The mention links to their profile and sends them a notification.
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: 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}
    );
}
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

Only @mention people when you specifically need their attention. Overusing mentions can lead to notification fatigue.
Configure notification preferences for each conversation type:
  • Always for your direct reports
  • Mentions Only for large team channels
  • Hidden for completed project chats
Review your notification center daily to ensure you don’t miss important mentions, especially in “mentions only” chats.
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.
You might want different notification settings on mobile (fewer) vs. desktop (more) based on how you use each platform.

​
Troubleshooting

  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
  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
  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

Build docs developers (and LLMs) love

Get started for freeTalk to us