Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(dashboard): render @<digits> mentions as @FirstName

Tanmay Chachra6f22c8da4e38
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7c26c57f6..0870f7207 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- The dashboard Chats thread renders an `@<digits>` mention as `@FirstName` when that participant has posted in the loaded thread; an unmatched mention is left as WhatsApp sent it.
- Baileys sessions list the saved address book again after a process restart. WhatsApp sends neither history nor an app-state snapshot to a device that has synced once, and the contact store is in memory, so a restarted gateway answered `GET /api/sessions/:sessionId/contacts` with only the peers it had seen since. A reconnect that finds the store empty now re-pulls the snapshot of the app-state collection that carries saved contacts. The list is also the address book only: a peer known by pushname alone is no longer listed, while `GET .../contacts/:contactId` still resolves it with `isMyContact: false`, and a chat title from history sync no longer overwrites a saved name. Thanks @gabrielmmoraes1999.
- whatsapp-web.js sessions send media again on the WhatsApp Web builds rolled out on 2026-09-17: the library spread the media model into the outgoing message after its id, and the model's private `__x_id` clobbered it, so every image, video, audio, document, sticker and status media send failed with `Data passed to getter must include an id property` while text kept working. An install-time patch carries upstream's one-line fix until a whatsapp-web.js release ships it ([#1643](https://github.com/rmyndharis/OpenWA/issues/1643), [#1636](https://github.com/rmyndharis/OpenWA/issues/1636)). Thanks @15874611923 and @Magnarks for the reports.
- An ingress route can declare `dedupOn: "body"` to key provider retries on the raw body instead of the delivery-id header. A provider that mints a fresh delivery id on every retry attempt, as supabase/auth does inside its hook retry loop, was never deduplicated when an ack was lost, so the contact received the message twice; routes that do not declare it keep the header ([#1641](https://github.com/rmyndharis/OpenWA/issues/1641)).
diff --git a/dashboard/src/components/chats/ChatThread.tsx b/dashboard/src/components/chats/ChatThread.tsx
index 079e99fe0..278f078a1 100644
--- a/dashboard/src/components/chats/ChatThread.tsx
+++ b/dashboard/src/components/chats/ChatThread.tsx
@@ -1,8 +1,8 @@
-import { useCallback, useEffect, useState, type RefObject } from 'react';
+import { useCallback, useEffect, useMemo, useState, type RefObject } from 'react';
import { useTranslation } from 'react-i18next';
import { AlertCircle, ChevronDown, CornerUpLeft, Loader2, MessageSquare, Smile, Trash2 } from 'lucide-react';
import { sessionApi, type Chat } from '../../services/api';
-import { getMediaSrc, senderKey, type ChatMessageView } from '../../utils/chatMessages';
+import { buildMentionNameMap, getMediaSrc, resolveMentions, senderKey, type ChatMessageView } from '../../utils/chatMessages';
import { shouldFetchOlderMessages } from '../../utils/scrollDecision';
import MessageBody from './MessageBody';
@@ -63,6 +63,11 @@ function ChatThread({
}: ChatThreadProps) {
const { t } = useTranslation();
+ // "@<digits>" in a message body only ever means something once resolved against a participant
+ // this thread has already seen post (see buildMentionNameMap) — recomputed only when the message
+ // list itself changes, not per-render.
+ const mentionNames = useMemo(() => buildMentionNameMap(messages), [messages]);
+
// Media the message list did not inline. The route serves the bytes as an attachment
// (Content-Disposition), and the list only carries payloads up to
// MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES — past that a row arrives as `{ omitted: true }`. Without
@@ -389,7 +394,10 @@ function ChatThread({
{/* Quoted message display */}
{msg.metadata?.quotedMessage && (
<div className="message-quote-box">
- <MessageBody text={msg.metadata.quotedMessage.body} className="quote-body" />
+ <MessageBody
+ text={resolveMentions(msg.metadata.quotedMessage.body, mentionNames)}
+ className="quote-body"
+ />
</div>
)}
@@ -403,7 +411,9 @@ function ChatThread({
msg.body &&
(!mediaInfo || msg.body !== mediaInfo.filename) &&
msg.type !== 'location' &&
- msg.type !== 'call' && <MessageBody text={msg.body} className="message-text" />
+ msg.type !== 'call' && (
+ <MessageBody text={resolveMentions(msg.body, mentionNames)} className="message-text" />
+ )
)}
{/* Inbound business prompt choices — tap calls POST .../messages/click-button. */}
diff --git a/dashboard/src/utils/chatMessages.test.ts b/dashboard/src/utils/chatMessages.test.ts
index 01cb0fbba..b32ff0142 100644
--- a/dashboard/src/utils/chatMessages.test.ts
+++ b/dashboard/src/utils/chatMessages.test.ts
@@ -1,6 +1,8 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
+ buildMentionNameMap,
+ resolveMentions,
mapEngineHistoryMessage,
mergeChatMessages,
mergeReactionSnapshot,
@@ -439,3 +441,39 @@ test('mergeReactionSnapshot treats an EMPTY snapshot as an answer, not as absenc
test('mergeReactionSnapshot stays undefined when neither side knows anything', () => {
assert.equal(mergeReactionSnapshot(undefined, undefined), undefined);
});
+
+test('buildMentionNameMap keys on the author JID\'s local part, stripped of a :device suffix', () => {
+ const map = buildMentionNameMap([
+ msg({ author: '166868170059932@lid', chatName: 'Sneha Desai' }),
+ msg({ author: '[email protected]:7', chatName: 'Group Admin' }),
+ ]);
+ assert.equal(map.get('166868170059932'), 'Sneha Desai');
+ assert.equal(map.get('628111'), 'Group Admin');
+});
+
+test('buildMentionNameMap skips a row with no author or no resolved name', () => {
+ const map = buildMentionNameMap([msg({ author: undefined, chatName: 'Sneha Desai' }), msg({ author: '[email protected]', chatName: undefined })]);
+ assert.equal(map.size, 0);
+});
+
+test('resolveMentions replaces a matched @<digits> token with @<FirstName>', () => {
+ const names = buildMentionNameMap([msg({ author: '166868170059932@lid', chatName: 'Sneha Desai' })]);
+ assert.equal(
+ resolveMentions('Hi @166868170059932, any update?', names),
+ 'Hi @Sneha, any update?',
+ );
+});
+
+test('resolveMentions leaves an unmatched @<digits> token exactly as WhatsApp sent it', () => {
+ const names = buildMentionNameMap([msg({ author: '166868170059932@lid', chatName: 'Sneha Desai' })]);
+ assert.equal(resolveMentions('Hi @999999999, who is this?', names), 'Hi @999999999, who is this?');
+});
+
+test('resolveMentions does not touch a short @-token that is not a real mention (below the digit floor)', () => {
+ const names = buildMentionNameMap([msg({ author: '166868170059932@lid', chatName: 'Sneha Desai' })]);
+ assert.equal(resolveMentions('see item @42', names), 'see item @42');
+});
+
+test('resolveMentions is a no-op with an empty name map (skips the regex pass entirely)', () => {
+ assert.equal(resolveMentions('Hi @166868170059932', new Map()), 'Hi @166868170059932');
+});
diff --git a/dashboard/src/utils/chatMessages.ts b/dashboard/src/utils/chatMessages.ts
index f7f8bf60c..c4b649fe2 100644
--- a/dashboard/src/utils/chatMessages.ts
+++ b/dashboard/src/utils/chatMessages.ts
@@ -111,6 +111,39 @@ export function capMediaPayloads(list: ChatMessageView[], keep = MEDIA_PAYLOAD_C
*/
export const senderKey = (m: Pick<ChatMessage, 'author' | 'chatName'>): string | undefined => m.author ?? m.chatName;
+/**
+ * Maps a group participant's numeric id (the local part of their `author` JID, `:device` suffix
+ * stripped) to their resolved display name — built from every message in the thread that carries
+ * both. An @mention in a message body is just "@<digits>" (WhatsApp never sends a resolved name in
+ * the text itself), and those digits are the same id a mentioned participant's OWN messages carry
+ * as `author` — so any thread where the mentioned person has posted at least once already has
+ * everything needed to resolve the mention, with no separate contact lookup.
+ */
+export function buildMentionNameMap(messages: Pick<ChatMessage, 'author' | 'chatName'>[]): Map<string, string> {
+ const map = new Map<string, string>();
+ for (const m of messages) {
+ if (!m.author || !m.chatName) continue;
+ const local = m.author.split('@')[0].split(':')[0];
+ if (/^\d+$/.test(local) && !map.has(local)) map.set(local, m.chatName);
+ }
+ return map;
+}
+
+/**
+ * Replace "@<digits>" mention tokens with "@<FirstName>" wherever the digits match a known
+ * participant (see buildMentionNameMap). An unmatched token is left exactly as WhatsApp sent it —
+ * the same fallback WhatsApp's own official clients show for a participant they can't resolve
+ * either, rather than guessing. First name only, matching WhatsApp's own mention convention (a
+ * bare "@FirstName Last Name" reads as the mention swallowing following prose).
+ */
+export function resolveMentions(text: string, names: Map<string, string>): string {
+ if (names.size === 0 || !text.includes('@')) return text;
+ return text.replace(/@(\d{7,})/g, (full: string, digits: string) => {
+ const name = names.get(digits);
+ return name ? `@${name.split(' ')[0]}` : full;
+ });
+}
+
// ChatMessageView extends ChatMessage with the view-only fields the chat page renders.
// Lifted from Chats.tsx so hooks/utils can share the same shape.
export type MessageMedia = {