Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Stop Shouting Into the Group Chat: @Mentions That People Actually Answer

Mentions turn broadcast notifications into calling names — but only when they are done right. Triggers, permissions, notification tiers, and a three-table data model: a practical guide with a worked funnel of 1,000 mentions.

Three colleagues collaborating around a laptop in an office (real photo)

Mentions are not a small feature — they are where collaboration products split apart

Almost every product with collaboration eventually grows @mentions. Mention someone in a comment, in a doc, in a task — that small @ solves the most basic problem in collaboration: who is this message actually for?

Before mentions, notifications could only broadcast: a message goes to a group channel, everyone receives it, most people do not need it. The result is two bad extremes at once: the people who should see it miss it, and the people who should not be bothered get bothered every day. Mentions turn broadcast into calling names: the message still lives in a public place, but only the named person gets a strong alert, and everyone else can catch up later. That single split brings the noise level of the whole collaboration down.

But mentions done badly become a new source of noise. Mention too freely and nobody takes it seriously; mention too rarely and key people keep missing things; mention someone but drop them into a page with no context and the mention was wasted. This guide is about doing mentions right: triggers, permissions, notification policy, and data model — a playbook you can follow directly. The example product "Ivy Docs" and the people "A-Yuan" and "Xiao-Man" are fictional, used only to illustrate flows, and the numbers are sample calculations.

Draw the line first: mentions are not a comment system, and not a notification center

Before building, separate three things. The comment system answers "where does discussion live," the notification center answers "where do messages pile up," and mentions answer "whose name is being called in this message." The three often grow together, but they have different design goals, and building them as one blob means none of them gets done well.

The comment system cares about organizing content: can comments nest, can resolved threads collapse, can they sort by time? The notification center cares about aggregation: can all notification types sit in one place, filter by read and unread, clear with one click? Mentions care about connecting people with context: when you type @, can you find the right person fast, and when you tap the notification, can you immediately see what was happening around the mentioned sentence?

The practical point of drawing the line: do not expect mentions to fix comments and notifications on the side. Do not build full read receipts into mentions — that belongs to messaging. Do not stuff the notification center with every mentions-related rule — that is the notification center's own roadmap. Mentions should do one thing well: get the right person, at the right time, with the right context, called by name accurately.

Another common boundary question: mentions versus direct messages. A DM is a closed one-to-one conversation; a mention is calling a name in a public place. When a user mentions a colleague in a public doc, the expectation is "everyone can see this discussion, but Xiao-Man especially needs to notice." If they wanted a private word, they would send a DM. Do not design mentions as a shortcut into DMs, or the atmosphere of public discussion breaks down.

Triggers: the moment you type @ decides most of the experience

Half of the mentions experience is decided the instant you type @. The candidate list that pops up must be fast and accurate. Half a second slow and it feels laggy; cannot find the person and the feature feels decorative.

The ordering of candidates matters. First tier: people you have recently worked with — those who recently commented in the same doc, active members of the same project. In Ivy Docs' early measurements, putting recent collaborators first raised the share of users picking the right person on the first try from 61% to 84%. Second tier: name matches, supporting Chinese names, pinyin initials, and English names — in a Chinese product, matching Chinese characters alone is not enough, because many people type pinyin initials to find someone. Third tier: the full member list, sorted by recent activity, as a fallback.

There are details in the matching logic too. What about duplicate names? Show avatar plus department or role in the list, such as "Xiao-Man (Design)" and "Xiao-Man (Backend)" — names alone make people afraid to click. Should someone already mentioned in the same input appear again? They should be greyed out or excluded, to avoid duplicate mentions. If the user types @ and then deletes it, should a half-finished state linger? Deleted means deleted — do not leave ghost state behind.

Mobile is another trap. The @ symbol is buried deep in phone keyboards, and many users never find it. The fix is an obvious @ button in the comment box toolbar: tap it and the candidate list opens directly, no symbol-hunting needed. After Ivy Docs added that button, mentions usage on mobile more than tripled. That is not deep design — it is paving the road right to the user's feet.

Permissions and visibility: mentioning someone who cannot see the content is the same as not mentioning them

The easiest place for mentions to break is permissions. A user mentions a colleague in a doc, the colleague taps the notification, and sees: "You do not have permission to view this content." That is worse than no mention at all: they were called over, blocked at the door, and bothered for nothing.

The right approach works in two layers. First, warn at input time. In the candidate list, people without view permission for the current doc get a small "no access" label next to their name, and selecting them triggers one more confirmation: "Xiao-Man does not currently have permission for this doc. Mentioning them will send a notification, but they will need to request access before they can read it. Continue?" Give the choice to the user instead of letting the mentioned person hit a wall later.

Second, a mentioned person should automatically get minimum permission. Many products do this by default: one mention grants view access to that piece of content. It is debated — some call it a permission leak — but from a collaboration standpoint, the named person is there to join the discussion, and mentioning them is pointless if they cannot read it. The compromise: the mention grants view-only access, scoped to that one piece of content, and logged in the permission log, where an admin can revoke it at any time. Ivy Docs does exactly this and has received zero permission-related complaints in six months since launch.

One more special case: mentioning someone who has left or been removed from the project. The candidate list should filter out departed members in real time, while old mentions in existing content keep their original text but stop sending new notifications. Do not erase people from history — the record is a fact, and erasing it makes past discussions unreadable later.

Notification policy: the power of @ comes from restraint

If mention notifications fire too freely, users quickly learn to ignore them. Restraint does not mean sending fewer — it means sending accurately: strong where it should be strong, weak where it should be weak, merged where it should be merged.

Start with tiers. A direct mention is top priority: push notification, red dot, and unread count all on. A group mention (say, @design-team) drops one tier: it lands in the notification center with a red dot, but no phone push. Being part of a thread where nobody was mentioned sends no personal notification at all — it only appears in the activity feed. Those three tiers are the skeleton of a mentions notification policy.

Then merging. If the same person is mentioned three times in one doc within a short window, do not send three pushes. The reasonable approach: merge mentions within a window (say, 10 minutes) into one: "A-Yuan mentioned you 3 times in the November plan doc" — tap to see the details. Ivy Docs' sample data shows that merging cut total mention notifications by 41%, while the share of users who responded after opening a notification rose from 52% to 63%. Fewer notifications, more responses — that is the value of merging.

Then quiet hours. Being mentioned late at night is a miserable experience. The fix is a "working hours" switch for mention notifications: mentions sent between 10 p.m. and 8 a.m. have their pushes delayed and batched for 8 a.m., while remaining visible in real time in the notification center. What about emergencies? Keep an explicit "urgent mention" path — for example, @ followed by an exclamation mark, or a separate "urgent call" button — that asks for a second confirmation and tells the sender clearly that "the other person will be pushed immediately." The existence of an urgent channel is precisely what lets the normal channel stay quietly silent.

Finally, read and response states. When the mentioned person opens the notification and reads the content, mark the mention as read; if they reply, the sender should see "Xiao-Man replied." That loop is small, but it reassures the sender enormously: their mention did not vanish into the void. Without that loop, users start doubting whether the feature works at all after a few tries.

Data model: three tables are enough to run it

The data model for mentions does not need to be complicated — three tables run it. The first is the mentions table, with fields including: mention ID, content ID, content type (doc, comment, task), mentioner ID, mentioned ID, position in the text (start and end character offsets), creation time, and status (unread, read, responded). The position field is critical: when a user taps a notification, they should scroll straight to the mentioned sentence, not just to the top of the doc.

The second is the delivery table, recording every notification actually sent for each mention: notification ID, mention ID, channel (push, email, in-app), delivery status (pending, sent, delivered, failed), and delivery time. Keeping delivery records in their own table pays off when something goes wrong: a user says they never got the notification — check this table first to see whether it was never sent, sent but undelivered, or delivered but unopened.

The third is the settings table, storing per-user preferences: whether to receive pushes, quiet-hours windows, whether to receive email digests, and whether group mentions should be downgraded. This table is user-controlled, with sensible defaults, changeable at any time. Do not bury the settings three menus deep — the @-related switches should be visible on the first screen of the notification settings page.

One easily missed point: deletion and editing of mentioned content. A user mentions someone and then deletes the original text — what happens to the mention record? The reasonable approach: keep the record, but change its status to "original content deleted," so the mentioned person sees "this content has been deleted" instead of an error. If the user edits the text and changes the mentioned sentence, the position offsets in the mention record must update along with it, or tapping the notification will land in the wrong place. Both details belong in the test cases.

The funnel: of 1,000 mentions, how many turn into responses?

Judging mentions by how many were sent is the wrong metric — look at the funnel instead. Here is a sample set of numbers, from Ivy Docs' internal calculations three months after launch (a fictional example, used only to show the method): of 1,000 mentions sent, 982 were delivered successfully — a 98.2% delivery rate; of those, 641 were opened within 24 hours — a 65.3% open rate; of the opened ones, 408 clicked through to the original context — 63.7%; and finally 257 got a response (a reply or direct handling of the issue) — 63.0%, for an overall conversion rate of 25.7%.

The most useful part of this funnel is not the final 257 but the two drops in the middle. The first drop is from delivery to open: of 982 deliveries, only 641 were opened, and 341 sank without a trace. The room to improve here is in the notification itself: should the title include the first 20 characters of the original text? Should the push title say clearly who mentioned you and why? Ivy Docs tried adding a text snippet to push titles, and the open rate rose from 58% to 65.3% — an immediate, visible effect.

The second drop is from clicking through to responding: of 408 click-throughs, only 257 responded, and 151 read and left. The room to improve here is in how context is presented: when users land, is the mentioned sentence the first thing they see? Is the surrounding discussion complete enough? Can they reply right on the notification page without jumping elsewhere? Every extra jump loses another batch of people. Putting the reply box directly on the notification detail page can lift the response rate by 8 to 10 percentage points — a cheap change worth prioritizing.

Mentions funnel: 1,000 sent → 982 delivered → 641 opened → 408 clicked into context → 257 responded

@everyone, @groups, @bots: three special ways to call a name

Beyond mentioning a person, there are three special forms of mention, each with its own rules.

@everyone is the easiest to abuse. The right approach adds friction: only doc admins or project owners can @everyone; ordinary members tapping @everyone get a confirmation stating "this will notify all 128 members," and every @everyone is logged with who did it and when. Ivy Docs adds one more rule: at most 3 @everyone mentions per project per day — beyond that, a message says "you have used today's quota, please try tomorrow." The limit looks stingy, but it forces the sender to think: is this really worth bothering everyone for?

@groups (say, @design-team or @backend-team) suit cross-functional work. Keeping groups up to date is the key: membership should update automatically when people change, and departed members should drop out on their own. Group mention notifications should sit one tier below personal mentions: notification center yes, phone push no — unless the sender explicitly marks it urgent. And group members should be able to opt out of that group's @ notifications with one click, instead of just enduring them.

@bots are the newer pattern: mention a deploy bot in a doc and it runs the tests; mention a data bot and it pastes the latest report. In essence, @bots extend "calling a name" into "giving an instruction." Two things matter when building them: the bot's response must be visible right where it was mentioned, not somewhere the user has to jump to; and when the bot fails, a failure record must stay under the original text rather than silently disappearing.

Launch checklist: tick every box before shipping

Before shipping mentions, check each item on this list. Triggers: the candidate list pops up within 200 ms; Chinese names, pinyin initials, and English names all match; duplicate names show role distinctions; the mobile @ button is visible and works. Permissions: users without access get a clear prompt; being mentioned auto-grants view access and logs it; departed members are filtered automatically. Notifications: the three tiers — direct, group, incidental — are correct; multiple mentions within 10 minutes merge into one; quiet hours work; the urgent channel asks for a second confirmation. Data: mention position offsets are correct; deleted originals show the right status; editing the text updates the landing position. Performance: candidate queries use indexes and return within 100 ms for a team of a hundred; failed deliveries retry and get logged.

One check is most often forgotten: gradual rollout and rollback. Ship mentions to 10% of users first and watch for three days: did notification volume spike abnormally, did the open rate drop, did anyone complain about being harassed? Only then roll out fully. And if something goes wrong, there must be a one-click kill switch for the push channel that leaves records in the notification center, so nobody gets woken up at night. A rollback switch is not a "do it later" feature — it must exist on launch day.

Summary

Mentions look like a small feature but amount to a whole collaboration logic: triggers decide how fast you find people, permissions decide whether a mention can be read, notification policy decides whether mentions annoy, and the data model decides whether problems can be traced. Judge it by the funnel: of 1,000 mentions sent, how many become real responses? Ivy Docs' sample funnel is 1,000 → 982 → 641 → 408 → 257, a 25.7% overall conversion rate, with the two biggest drops between "delivered and opened" and "clicked through and responded" — the two places most worth optimizing first. Remember one principle: the power of @ comes from restraint. The more precisely you call names, the more willing people are to respond; the more freely you call them, the faster the feature dies.

Views 8Comments 0

Comments (0)

ME
0/1000
Loading comments...
Browse projectsPublish your project

Related articles

Real photo: a laptop, tablet, and phone on a wooden table showing the same green-leaf website, the phone view with navigation in one column, a potted plant nearby
Guide
Squashed on phones? Responsive layout and media queries, explained plainly

One page should stand up on a phone, a tablet, and a computer. This guide follows MDN's Responsive web design, Using media queries, and the viewport meta reference: fluid HTML, the viewport tag, fluid grids and max-width, images that never burst their container, media query syntax, breakpoints set by content, mobile first, responsive type, testing capability instead of width, and a pre-launch checklist.

Mobile AppsDesign ExperienceFrontend Engineering
Real photo: a bank of light gray metal filing cabinets with one drawer pulled open, revealing rows of hanging file folders inside
Guide
A real database inside the browser: IndexedDB local storage, explained plainly

localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.

Tool TipsData WorkflowsFrontend Engineering
Real photo: hands typing on a MacBook Pro showing JavaScript code that changes HTML content, with a white mouse, papers, and binders on a white desk
Guide
Functions without the confusion: JavaScript functions, parameters, and arrow functions, explained plainly

You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.

Tool TipsFrontend EngineeringAI Coding