Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(baileys): sync saved contacts on reconnect and hide unsaved peers

Gabriel Moraes39d0db125397
diff --git a/src/engine/adapters/baileys-history.spec.ts b/src/engine/adapters/baileys-history.spec.ts
index fcb0a4c71..71a267708 100644
--- a/src/engine/adapters/baileys-history.spec.ts
+++ b/src/engine/adapters/baileys-history.spec.ts
@@ -11,16 +11,27 @@ import { BaileysHistory, BaileysHistoryHost } from './baileys-history';
* promise that does not settle, with the clock advanced past the budget.
*/
-function history(sock: Record<string, jest.Mock>) {
+const PATCH_NAMES = ['critical_block', 'regular'] as const;
+
+function history(sock: Record<string, unknown> = {}, opts: { contactCount?: number } = {}) {
const logger = { warn: jest.fn(), debug: jest.fn(), info: jest.fn(), error: jest.fn() };
const upsertChats = jest.fn();
+ const socket = {
+ authState: {
+ creds: { accountSyncCounter: 0 },
+ keys: { set: jest.fn().mockResolvedValue(undefined) },
+ },
+ resyncAppState: jest.fn().mockResolvedValue(undefined),
+ ...sock,
+ };
const host = {
- getSocket: () => sock as unknown as WASocket,
+ getSocket: () => socket as unknown as WASocket,
logger,
upsertChats,
- loadLib: () => Promise.resolve({ ALL_WA_PATCH_NAMES: [] }),
+ contactCount: () => opts.contactCount ?? 0,
+ loadLib: () => Promise.resolve({ ALL_WA_PATCH_NAMES: [...PATCH_NAMES] }),
} as unknown as BaileysHistoryHost;
- return { history: new BaileysHistory(host), logger, upsertChats };
+ return { history: new BaileysHistory(host), logger, upsertChats, socket };
}
const groupWarnCount = (logger: { warn: jest.Mock }): number =>
@@ -101,5 +112,67 @@ describe('hydrateNames', () => {
await settled;
expect(resyncAppState).toHaveBeenCalledTimes(1);
+ expect(resyncAppState).toHaveBeenCalledWith([...PATCH_NAMES], false);
+ });
+
+ it('re-pulls the address-book snapshot on reconnect when the in-memory store is empty', async () => {
+ // Baileys skips history + app-state snapshot once accountSyncCounter > 0. The gateway store is
+ // in-memory, so a process restart would otherwise leave GET /contacts empty forever.
+ const set = jest.fn().mockResolvedValue(undefined);
+ const resyncAppState = jest.fn().mockResolvedValue(undefined);
+ const { history: h } = history(
+ {
+ groupFetchAllParticipating: jest.fn().mockResolvedValue({}),
+ resyncAppState,
+ authState: { creds: { accountSyncCounter: 1 }, keys: { set } },
+ },
+ { contactCount: 0 },
+ );
+
+ await h.hydrateNames();
+
+ expect(set).toHaveBeenCalledWith({
+ 'app-state-sync-version': { critical_block: null, regular: null },
+ });
+ expect(resyncAppState).toHaveBeenCalledWith([...PATCH_NAMES], true);
+ expect(resyncAppState).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps the incremental resync on reconnect when contacts are already in memory', async () => {
+ const set = jest.fn().mockResolvedValue(undefined);
+ const resyncAppState = jest.fn().mockResolvedValue(undefined);
+ const { history: h } = history(
+ {
+ groupFetchAllParticipating: jest.fn().mockResolvedValue({}),
+ resyncAppState,
+ authState: { creds: { accountSyncCounter: 3 }, keys: { set } },
+ },
+ { contactCount: 12 },
+ );
+
+ await h.hydrateNames();
+
+ expect(set).not.toHaveBeenCalled();
+ expect(resyncAppState).toHaveBeenCalledWith([...PATCH_NAMES], false);
+ });
+
+ it('uses the incremental resync on a first link (accountSyncCounter is still 0)', async () => {
+ // First connect still has Baileys' own snapshot path in flight; forcing another snapshot would
+ // race it. Empty contacts here are the boot window, not a missed reconnect.
+ const set = jest.fn().mockResolvedValue(undefined);
+ const resyncAppState = jest.fn().mockResolvedValue(undefined);
+ const { history: h } = history(
+ {
+ groupFetchAllParticipating: jest.fn().mockResolvedValue({}),
+ resyncAppState,
+ authState: { creds: { accountSyncCounter: 0 }, keys: { set } },
+ },
+ { contactCount: 0 },
+ );
+
+ await h.hydrateNames();
+
+ expect(set).not.toHaveBeenCalled();
+ expect(resyncAppState).toHaveBeenCalledWith([...PATCH_NAMES], false);
});
});
diff --git a/src/engine/adapters/baileys-history.ts b/src/engine/adapters/baileys-history.ts
index 8b5321ebb..ac2504d7a 100644
--- a/src/engine/adapters/baileys-history.ts
+++ b/src/engine/adapters/baileys-history.ts
@@ -28,6 +28,12 @@ export interface BaileysHistoryHost {
recordMessage(msg: WAMessage): void;
upsertContacts(records: Partial<BaileysContact>[]): void;
upsertChats(records: Partial<Chat>[]): void;
+ /**
+ * How many contacts the in-memory session store currently holds. Used to decide whether a
+ * reconnect must re-pull the address-book snapshot (Baileys skips history + app-state snapshot
+ * once `accountSyncCounter > 0`, and this store does not survive a process restart).
+ */
+ contactCount(): number;
/** The chat's cached disappearing-messages timer extraction (`msg.ephemeralDuration` primary). */
extractEphemeralDuration(msg: WAMessage): number | undefined;
/** The currently-registered onHistoryMessages callback, if any (assigned at initialize()). */
@@ -91,6 +97,12 @@ export class BaileysHistory {
* sync (the state machine goes Online before it runs) and the PUSH_NAME sync can fail to decrypt, so
* names never arrive. Fetch group subjects (reliable) and best-effort re-trigger the app-state sync;
* both are non-fatal, and DM push-names still arrive via `contacts.update` on live messages.
+ *
+ * On a reconnect (`accountSyncCounter > 0`) Baileys skips history sync and the address-book snapshot
+ * entirely — WhatsApp assumes the linked device kept its local copy. This gateway's contact store is
+ * in-memory, so a process restart leaves GET /contacts empty. When that happens we drop the stored
+ * app-state versions (so the next resync asks for a snapshot, not an incremental patch) and process
+ * the mutations as an initial sync, which is what emits `contacts.upsert` for the saved address book.
*/
async hydrateNames(): Promise<void> {
try {
@@ -115,7 +127,16 @@ export class BaileysHistory {
}
try {
const b = await this.host.loadLib();
- await this.sock().resyncAppState(b.ALL_WA_PATCH_NAMES, false);
+ const collections = b.ALL_WA_PATCH_NAMES;
+ if (!collections?.length) {
+ return;
+ }
+ const alreadySynced = (this.sock().authState?.creds?.accountSyncCounter ?? 0) > 0;
+ if (alreadySynced && this.host.contactCount() === 0) {
+ await this.restoreAddressbookSnapshot(collections);
+ return;
+ }
+ await this.sock().resyncAppState(collections, false);
this.host.logger.debug('Re-synced app state for contact names', { action: 'baileys_resync_appstate' });
} catch (err) {
this.host.logger.warn('App-state resync for contact names failed', {
@@ -124,6 +145,22 @@ export class BaileysHistory {
}
}
+ /**
+ * Drop persisted app-state collection versions and resync from a snapshot so `contactAction`
+ * mutations fire again. `null` in `keys.set` is Baileys' own delete; the next resync then sets
+ * `return_snapshot` because the collection has no version. `isInitialSync: true` keeps delete-chat
+ * mutations from wiping conversations that history is not about to rebuild.
+ */
+ private async restoreAddressbookSnapshot(collections: Parameters<WASocket['resyncAppState']>[0]): Promise<void> {
+ const versions = Object.fromEntries(collections.map(name => [name, null]));
+ await this.sock().authState.keys.set({ 'app-state-sync-version': versions });
+ await this.sock().resyncAppState(collections, true);
+ this.host.logger.debug('Restored address-book snapshot after reconnect', {
+ action: 'baileys_restore_addressbook',
+ contacts: this.host.contactCount(),
+ });
+ }
+
/**
* Media-free WAMessage -> IncomingMessage map for bulk history (downloading media for thousands of
* messages would be ruinous; the type is kept, the payload dropped). Returns null for protocol /
diff --git a/src/engine/adapters/baileys-lifecycle.ts b/src/engine/adapters/baileys-lifecycle.ts
index 5a9822518..6cdd2a7cd 100644
--- a/src/engine/adapters/baileys-lifecycle.ts
+++ b/src/engine/adapters/baileys-lifecycle.ts
@@ -437,7 +437,17 @@ export class BaileysLifecycle {
sock.ev.on('groups.upsert', groups => this.host.handleGroupsUpsert(groups));
sock.ev.on('group.join-request', event => this.host.handleGroupJoinRequest(event));
sock.ev.on('messaging-history.set', history => {
- this.host.upsertContacts(history.contacts);
+ // History sync copies conversation.displayName into `name`, which is a chat title — not the
+ // address-book saved name (that arrives via contacts.upsert from app-state contactAction).
+ // Fold the title into notify so chat-name fallback still works, and leave `name` unset so
+ // GET /contacts stays the agenda rather than every 1:1 the account has ever opened.
+ this.host.upsertContacts(
+ (history.contacts ?? []).map(c => ({
+ ...c,
+ notify: c.notify ?? c.name,
+ name: undefined,
+ })),
+ );
this.host.upsertChats(history.chats);
this.host.addLidMappings(history.lidPnMappings ?? []);
void this.host.captureHistoryMessages(history.messages ?? []);
diff --git a/src/engine/adapters/baileys-session-store.spec.ts b/src/engine/adapters/baileys-session-store.spec.ts
index bb30d7ccd..5bebc6381 100644
--- a/src/engine/adapters/baileys-session-store.spec.ts
+++ b/src/engine/adapters/baileys-session-store.spec.ts
@@ -46,6 +46,43 @@ describe('BaileysSessionStore', () => {
expect(store.listContacts()).toHaveLength(1);
});
+ it('does not let a later history-sync row wipe a saved name with undefined', () => {
+ // Baileys history contacts always include `name: displayName || name || username || undefined`.
+ // Spreading that onto an address-book upsert that already had a name used to clear it.
+ store.upsertContacts([{ id: '[email protected]', name: 'Alice', notify: 'Al' }]);
+ store.upsertContacts([{ id: '[email protected]', name: undefined, notify: 'Al' }]);
+ expect(store.findContact('[email protected]')).toMatchObject({ name: 'Alice', pushName: 'Al' });
+ });
+
+ it('accepts a contact keyed only by lid (id omitted) and finds it by phone', () => {
+ store.upsertContacts([{ lid: '111@lid', phoneNumber: '[email protected]', name: 'Ada' }]);
+ expect(store.findContact('111@lid')?.name).toBe('Ada');
+ expect(store.findContact('[email protected]')?.name).toBe('Ada');
+ expect(store.listContacts()[0]).toMatchObject({ id: '[email protected]', name: 'Ada', number: '628111' });
+ });
+
+ it('drops groups/newsletters/status from the contact map (they are not address-book entries)', () => {
+ store.upsertContacts([
+ { id: '[email protected]', name: 'Team' },
+ { id: '123@newsletter', name: 'Channel' },
+ { id: 'status@broadcast' },
+ { id: '[email protected]', name: 'Alice' },
+ ]);
+ expect(store.listContacts()).toHaveLength(1);
+ expect(store.findContact('[email protected]')).toBeNull();
+ expect(store.findContact('[email protected]')?.name).toBe('Alice');
+ });
+
+ it('does not promote a chat partner into the address book', () => {
+ store.upsertChats([
+ { id: '[email protected]', name: 'Alice' },
+ { id: '[email protected]', name: 'Team' },
+ ]);
+ expect(store.findContact('[email protected]')).toBeNull();
+ expect(store.listContacts()).toHaveLength(0);
+ expect(store.listChats()).toHaveLength(2);
+ });
+
/**
* Baileys documents `name` as the one YOU saved and `notify` as the pushname the contact set
* themselves, so a contact carrying only `notify` is not in the addressbook. Reporting true for
@@ -60,6 +97,7 @@ describe('BaileysSessionStore', () => {
expect(store.findContact('[email protected]')?.isMyContact).toBe(false);
// The pushname still surfaces either way; it is the addressbook claim that changed.
expect(store.findContact('[email protected]')?.pushName).toBe('Bob');
+ expect(store.listContacts()).toEqual([expect.objectContaining({ id: '[email protected]', name: 'Alice' })]);
});
describe('archived, pinned and muted state', () => {
@@ -633,14 +671,14 @@ describe('BaileysSessionStore', () => {
it('treats 0 as unbounded (legacy behaviour)', () => {
const s = storeWithCap('0');
for (let i = 0; i < 100; i++) {
- s.upsertContacts([{ id: `62${1000 + i}@s.whatsapp.net` }]);
+ s.upsertContacts([{ id: `62${1000 + i}@s.whatsapp.net`, name: 'x' }]);
}
expect(s.listContacts()).toHaveLength(100);
});
it('falls back to the 5000 default for a garbage override', () => {
const s = storeWithCap('not-a-number');
- s.upsertContacts(Array.from({ length: 5001 }, (_, i) => ({ id: `62${100000 + i}@s.whatsapp.net` })));
+ s.upsertContacts(Array.from({ length: 5001 }, (_, i) => ({ id: `62${100000 + i}@s.whatsapp.net`, name: 'x' })));
expect(s.listContacts()).toHaveLength(5000);
expect(s.findContact('[email protected]')).toBeNull(); // the oldest went first
expect(s.findContact('[email protected]')).not.toBeNull();
@@ -648,7 +686,7 @@ describe('BaileysSessionStore', () => {
it('treats a blank override as unset, not as 0 (unbounded)', () => {
const s = storeWithCap('');
- s.upsertContacts(Array.from({ length: 5001 }, (_, i) => ({ id: `62${100000 + i}@s.whatsapp.net` })));
+ s.upsertContacts(Array.from({ length: 5001 }, (_, i) => ({ id: `62${100000 + i}@s.whatsapp.net`, name: 'x' })));
expect(s.listContacts()).toHaveLength(5000);
});
});
diff --git a/src/engine/adapters/baileys-session-store.ts b/src/engine/adapters/baileys-session-store.ts
index b397dddd6..55f9e5c21 100644
--- a/src/engine/adapters/baileys-session-store.ts
+++ b/src/engine/adapters/baileys-session-store.ts
@@ -118,12 +118,22 @@ export class BaileysSessionStore {
upsertContacts(records: Partial<BaileysContact>[] = []): void {
for (const r of records) {
- if (!r.id) {
+ // History-sync / app-state rows sometimes key the person as `lid` and leave `id` empty.
+ const id = r.id ?? r.lid;
+ if (!id) {
+ continue;
+ }
+ // Groups/newsletters/status arrive in the same history-sync contact array as people; they
+ // are not address-book entries and must not occupy the contact cap or GET /contacts.
+ const kind = parseWaId(id).kind;
+ if (kind === 'group' || kind === 'newsletter' || kind === 'broadcast' || kind === 'status') {
continue;
}
- const existing = this.contacts.get(r.id) ?? { id: r.id };
- const merged: BaileysContact = { ...existing, ...r };
- this.contacts.set(r.id, merged);
+ const existing = this.contacts.get(id) ?? { id };
+ const merged: BaileysContact = { id: existing.id };
+ this.assignDefined(merged, existing);
+ this.assignDefined(merged, { ...r, id });
+ this.contacts.set(id, merged);
// Capture a lid->phone pair from the merged record (lid + phone can arrive in separate updates).
// `phoneNumber` is the authoritative PN field; fall back to `id` itself only when it's already
// in the phone dialect (a lid-only contact's `id` is `<lid>@lid`, which is not a usable phone).
@@ -135,6 +145,20 @@ export class BaileysSessionStore {
}
}
+ /**
+ * Copy own enumerable fields whose value is not `undefined`. History-sync contacts always include
+ * `name: displayName || name || username || undefined`, and a later `{ ...existing, ...partial }`
+ * spread would wipe a saved address-book name that arrived first via `contacts.upsert`.
+ */
+ private assignDefined(target: BaileysContact, source: Partial<BaileysContact>): void {
+ for (const key of Object.keys(source) as (keyof BaileysContact)[]) {
+ const value = source[key];
+ if (value !== undefined) {
+ (target as unknown as Record<string, unknown>)[key] = value;
+ }
+ }
+ }
+
upsertChats(records: Partial<Chat>[] = []): void {
for (const r of records) {
if (!r.id) {
@@ -276,12 +300,42 @@ export class BaileysSessionStore {
}
listContacts(): Contact[] {
- return [...this.contacts.values()].map(c => this.toNeutralContact(c));
+ // GET /contacts is the address book, not "everyone this session has ever seen". Baileys
+ // documents `name` as the one YOU saved; `notify` is only the pushname they set themselves.
+ return [...this.contacts.values()].filter(c => c.name).map(c => this.toNeutralContact(c));
}
findContact(id: string): Contact | null {
- const c = this.contacts.get(id) ?? this.contacts.get(this.toEngineJid(id));
- return c ? this.toNeutralContact(c) : null;
+ const parsed = parseWaId(id);
+ const keys = [id, this.toEngineJid(id)];
+ if (parsed.kind === 'lid') {
+ keys.push(`${parsed.userPart}@lid`);
+ }
+ if (parsed.kind === 'user') {
+ keys.push(`${parsed.userPart}@s.whatsapp.net`, `${parsed.userPart}@c.us`);
+ }
+ for (const key of keys) {
+ const direct = this.contacts.get(key);
+ if (direct) {
+ return this.toNeutralContact(direct);
+ }
+ }
+ if (parsed.kind !== 'user' && parsed.kind !== 'lid') {
+ return null;
+ }
+ const want = parsed.userPart;
+ for (const c of this.contacts.values()) {
+ const phone = c.phoneNumber
+ ? userPart(c.phoneNumber)
+ : c.id.endsWith('@s.whatsapp.net') || c.id.endsWith('@c.us')
+ ? userPart(c.id)
+ : '';
+ const lid = c.lid ? userPart(c.lid) : c.id.endsWith('@lid') ? userPart(c.id) : '';
+ if (phone === want || lid === want) {
+ return this.toNeutralContact(c);
+ }
+ }
+ return null;
}
listChats(): ChatSummary[] {
diff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.ts
index 382fb062a..c9eae8d27 100644
--- a/src/engine/adapters/baileys.adapter.spec.ts
+++ b/src/engine/adapters/baileys.adapter.spec.ts
@@ -77,6 +77,11 @@ class FakeSock extends EventEmitter {
// Baileys answers this by emitting its own connection.update carrying the result, so the default
// mirrors that: resolving alone proves nothing reached the adapter.
public fetchAccountReachoutTimelock = jest.fn().mockResolvedValue({ isActive: false });
+ public resyncAppState = jest.fn().mockResolvedValue(undefined);
+ public authState = {
+ creds: { accountSyncCounter: 0 },
+ keys: { set: jest.fn().mockResolvedValue(undefined) },
+ };
public signalRepository: { lidMapping: { getLIDForPN: jest.Mock } } | undefined;
fire(event: string, arg: unknown): void {
this.emitter.emit(event, arg);
@@ -122,6 +127,7 @@ jest.mock('@whiskeysockets/baileys', () => ({
normalizeMessageContent: jest.fn((c: unknown) => c),
// The pinned protocol node targets this JID; exported from the real module's WABinary surface.
S_WHATSAPP_NET: '@s.whatsapp.net',
+ ALL_WA_PATCH_NAMES: ['critical_block', 'critical_unblock_low', 'regular_high', 'regular_low', 'regular'],
DisconnectReason: { loggedOut: 401, forbidden: 403, restartRequired: 515, connectionReplaced: 440 },
proto: {
Message: {
@@ -4909,15 +4915,25 @@ describe('BaileysAdapter contact + chat reads', () => {
it('populates contacts from contacts.upsert and reads them', async () => {
const adapter = await ready();
- fakeSock.fire('contacts.upsert', [{ id: '[email protected]', notify: 'Al' }]);
+ fakeSock.fire('contacts.upsert', [{ id: '[email protected]', name: 'Al', notify: 'Al' }]);
const contacts = await adapter.getContacts();
expect(contacts).toHaveLength(1);
- expect(contacts[0]).toMatchObject({ id: '[email protected]', pushName: 'Al', number: '628111' });
+ expect(contacts[0]).toMatchObject({ id: '[email protected]', name: 'Al', pushName: 'Al', number: '628111' });
expect((await adapter.getContactById('[email protected]'))?.number).toBe('628111');
expect((await adapter.getContactById('[email protected]'))?.id).toBe('[email protected]'); // neutral id round-trips
expect(await adapter.getContactById('[email protected]')).toBeNull();
});
+ it('does not list a pushname-only peer on GET /contacts (address book only)', async () => {
+ const adapter = await ready();
+ fakeSock.fire('contacts.upsert', [{ id: '[email protected]', notify: 'Al' }]);
+ await expect(adapter.getContacts()).resolves.toHaveLength(0);
+ await expect(adapter.getContactById('[email protected]')).resolves.toMatchObject({
+ pushName: 'Al',
+ isMyContact: false,
+ });
+ });
+
it('populates chats + last message and reads getChats', async () => {
const adapter = await ready();
fakeSock.fire('chats.upsert', [{ id: '[email protected]', name: 'Alice', unreadCount: 1 }]);
@@ -4955,9 +4971,13 @@ describe('BaileysAdapter contact + chat reads', () => {
messages: [],
lidPnMappings: [{ lid: '111@lid', pn: '[email protected]' }],
});
- expect(await adapter.getContacts()).toHaveLength(1);
+ expect(await adapter.getContacts()).toHaveLength(0);
expect(await adapter.resolveContactPhone('111@lid')).toBe('628999');
expect(await adapter.resolveContactPhone('[email protected]')).toBe('628222');
+ expect(await adapter.getContactById('[email protected]')).toMatchObject({
+ pushName: 'Bob',
+ isMyContact: false,
+ });
});
it('contact/chat reads reject with EngineNotReadyError before connect', async () => {
diff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.ts
index 306ba08d2..5e679273e 100644
--- a/src/engine/adapters/baileys.adapter.ts
+++ b/src/engine/adapters/baileys.adapter.ts
@@ -160,6 +160,7 @@ export class BaileysAdapter implements IWhatsAppEngine {
this.sessionStore.addLidMappings([{ lid: `${lid.split('@')[0].split(':')[0]}@lid`, pn }]),
mapMessage: (msg, contentType, opts) => this.events.mapMessage(msg, contentType, opts),
listContacts: () => this.sessionStore.listContacts(),
+ contactCount: () => this.sessionStore.listContacts().length,
findContact: contactId => this.sessionStore.findContact(contactId),
resolvePhone: contactId => this.sessionStore.resolvePhone(contactId),
listChats: () => this.sessionStore.listChats(),