Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(integration): match a handover across a chat's lid and phone ids

Yudhi Armyndharis2c305938dc24
diff --git a/src/engine/identity/lid-mapping-store.service.ts b/src/engine/identity/lid-mapping-store.service.ts
index e4b66b7c4..0a57c23d6 100644
--- a/src/engine/identity/lid-mapping-store.service.ts
+++ b/src/engine/identity/lid-mapping-store.service.ts
@@ -47,8 +47,9 @@ export interface LidMappingStore {
* A cache miss is warmed from the table in the background (rows past the preload cap stay resolvable)
* and otherwise falls back to engine re-resolution (the table remains the source of truth), so eviction
* only costs a re-resolution, never data loss. The reverse map has no such warm path (nothing looks a
- * lid up by phone), so a phone-keyed filter uses {@link findLidsForPhone}, which reads the table. The reverse map is reconciled on each eviction so it does
- * not retain entries for LIDs no longer in the forward cache.
+ * lid up by phone), so a phone-keyed filter uses {@link findLidsForPhone}, which reads the table. The
+ * reverse map is reconciled on each eviction so it does not retain entries for LIDs no longer in the
+ * forward cache.
*/
@Injectable()
export class LidMappingStoreService implements LidMappingStore, OnModuleInit {
@@ -172,6 +173,22 @@ export class LidMappingStoreService implements LidMappingStore, OnModuleInit {
return [...lids];
}
+ /**
+ * Forward lookup that reads the table on a cache miss, for callers that can await (the handover
+ * gate). {@link getCached} answers a miss with undefined and only warms in the background, which
+ * is exactly when a mapping past the cap or evicted matters. Like {@link findLidsForPhone}, the row
+ * is not indexed, and a read error answers null.
+ */
+ async findPhoneForLid(lid: string): Promise<string | null> {
+ if (this.lidToPhone.has(lid)) return this.getCached(lid) ?? null;
+ try {
+ return (await this.repo.findOne({ where: { lid } }))?.phone ?? null;
+ } catch (err) {
+ this.logger.warn(`Could not read the phone for a lid: ${err instanceof Error ? err.message : String(err)}`);
+ return null;
+ }
+ }
+
async remember(lid: string, phone: string | null, sessionId?: string): Promise<void> {
if (!lid || this.lidToPhone.get(lid) === phone) {
return; // unseen-or-changed only; a no-op write would just churn updatedAt
diff --git a/src/engine/identity/lid-mapping-store.spec.ts b/src/engine/identity/lid-mapping-store.spec.ts
index 7711f75dc..1931cb67c 100644
--- a/src/engine/identity/lid-mapping-store.spec.ts
+++ b/src/engine/identity/lid-mapping-store.spec.ts
@@ -153,6 +153,23 @@ describe('LidMappingStoreService — LRU cap', () => {
expect(await store.findLidsForPhone('628000')).toEqual(['111']);
});
+ it('finds a phone by lid from the table on a cache miss, without indexing the row', async () => {
+ process.env.LID_MAPPING_CACHE_MAX = '1';
+ const repo = makeFakeRepo();
+ const store = new LidMappingStoreService(repo as unknown as Repository<LidMapping>);
+ await store.onModuleInit();
+
+ await store.remember('lid-a', '620001');
+ await store.remember('lid-b', '620002'); // evicts lid-a; its row stays persisted
+ expect(await store.findPhoneForLid('lid-a')).toBe('620001');
+ expect(await store.findPhoneForLid('lid-b')).toBe('620002');
+ expect(await store.findPhoneForLid('lid-x')).toBeNull();
+ expect(store.lidsForPhone('620002')).toEqual(['lid-b']); // the table read did not evict it
+
+ repo.findOne.mockRejectedValueOnce(new Error('connection lost'));
+ expect(await store.findPhoneForLid('lid-a')).toBeNull();
+ });
+
it('reconciles the reverse map on eviction (no orphan phoneToLids entries)', async () => {
process.env.LID_MAPPING_CACHE_MAX = '2';
const repo = makeFakeRepo();
diff --git a/src/modules/integration/conversation-mapping.service.spec.ts b/src/modules/integration/conversation-mapping.service.spec.ts
index 83164a608..a19bd12d6 100644
--- a/src/modules/integration/conversation-mapping.service.spec.ts
+++ b/src/modules/integration/conversation-mapping.service.spec.ts
@@ -1,7 +1,9 @@
-import { DataSource } from 'typeorm';
+import { DataSource, Repository } from 'typeorm';
import { ConversationMapping } from './entities/conversation-mapping.entity';
import { ConversationMappingConflict, ConversationMappingService, MappingKey } from './conversation-mapping.service';
import { AddIntegrationFabric1781900000000 } from '../../database/migrations/1781900000000-AddIntegrationFabric';
+import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
+import { LidMapping } from '../../engine/identity/lid-mapping.entity';
describe('ConversationMappingService', () => {
let ds: DataSource;
@@ -87,6 +89,144 @@ describe('ConversationMappingService', () => {
expect(await service.findHandoverForChat('sess-1', 'other-chat')).toBeNull();
});
+ describe('findHandoverForChat across the lid and phone forms of one chat', () => {
+ // lid 111 -> phone 628999. A 1:1 chat's neutral id flips from `111@lid` to `[email protected]` once the
+ // mapping is learned, so a takeover recorded under either form has to govern the other. The store is
+ // real but its cache is empty, as for a mapping past the preload cap or evicted: only the table has it.
+ const table = [{ lid: '111', phone: '628999' }];
+ const lidStore = new LidMappingStoreService({
+ find: ({ where }: { where: { phone: string } }) => Promise.resolve(table.filter(r => r.phone === where.phone)),
+ findOne: ({ where }: { where: { lid: string } }) => Promise.resolve(table.find(r => r.lid === where.lid) ?? null),
+ } as unknown as Repository<LidMapping>);
+ const human = (chatId: string, provider = 'convB') =>
+ service.upsert({ sessionId: 'sess-1', chatId, pluginId: 'chatwoot-adapter', instanceId: 'i2' }, provider, {
+ handoverState: 'human',
+ });
+ const bot = (chatId: string, provider: string) =>
+ service.upsert({ sessionId: 'sess-1', chatId, pluginId: 'chatwoot-adapter', instanceId: 'i2' }, provider);
+
+ beforeEach(() => {
+ service = new ConversationMappingService(ds.getRepository(ConversationMapping), lidStore);
+ });
+
+ it('finds a takeover stored under the lid when the chat now arrives by phone', async () => {
+ await human('111@lid');
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toEqual({
+ pluginId: 'chatwoot-adapter',
+ handoverState: 'human',
+ });
+ });
+
+ it('finds a takeover stored under the phone when the chat arrives by lid', async () => {
+ await human('[email protected]');
+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toEqual({
+ pluginId: 'chatwoot-adapter',
+ handoverState: 'human',
+ });
+ });
+
+ it('does not match another person', async () => {
+ await human('111@lid');
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();
+ });
+
+ const row = (chatId: string) =>
+ service.get({ sessionId: 'sess-1', chatId, pluginId: 'chatwoot-adapter', instanceId: 'i2' });
+
+ it('keeps the takeover when the flip makes the adapter link a fresh row under the phone form', async () => {
+ await human('111@lid');
+ await bot('[email protected]', 'convC'); // linked by the flip, not a hand-back
+ await bot('[email protected]', 'convC'); // and re-linked idempotently
+ expect((await row('[email protected]'))!.handoverState).toBe('human');
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toEqual({
+ pluginId: 'chatwoot-adapter',
+ handoverState: 'human',
+ });
+ });
+
+ it('a hand-back under either form clears both, and an idempotent upsert does not revive it', async () => {
+ await human('111@lid');
+ await bot('[email protected]', 'convC');
+ await service.setHandover((await row('[email protected]'))!.id, 'bot'); // the agent hands the chat back
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();
+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toBeNull();
+
+ await bot('111@lid', 'convB'); // the adapter re-links the lid row with nothing changed
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();
+ });
+
+ it('a takeover under either form survives an idempotent upsert of the other form', async () => {
+ await bot('111@lid', 'convB');
+ await bot('[email protected]', 'convC');
+ await service.setHandover((await row('111@lid'))!.id, 'human');
+ await bot('[email protected]', 'convC');
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toEqual({
+ pluginId: 'chatwoot-adapter',
+ handoverState: 'human',
+ });
+ });
+
+ it('a hand-back reaches a row whose form was paired after the takeover', async () => {
+ await human('111@lid');
+ await bot('[email protected]', 'convC'); // inherits the takeover
+ table.push({ lid: '333', phone: '628999' }); // another lid for the number is learned meanwhile
+ try {
+ await service.setHandover((await row('[email protected]'))!.id, 'bot');
+ expect((await row('111@lid'))!.handoverState).toBe('bot');
+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toBeNull();
+ } finally {
+ table.pop();
+ }
+ });
+
+ it('a decision on one lid of a number reaches its sibling lid and the phone-form row', async () => {
+ table.push({ lid: '222', phone: '628999' });
+ try {
+ await bot('111@lid', 'convB');
+ await bot('222@lid', 'convD');
+ await service.setHandover((await row('222@lid'))!.id, 'human');
+ expect(await service.findHandoverForChat('sess-1', '111@lid')).toEqual({
+ pluginId: 'chatwoot-adapter',
+ handoverState: 'human',
+ });
+ await bot('[email protected]', 'convC'); // a phone-form row joins and inherits the takeover
+ expect((await row('[email protected]'))!.handoverState).toBe('human');
+ await service.setHandover((await row('111@lid'))!.id, 'bot');
+ expect((await row('[email protected]'))!.handoverState).toBe('bot');
+ expect(await service.findHandoverForChat('sess-1', '222@lid')).toBeNull();
+ } finally {
+ table.pop();
+ }
+ });
+
+ it('a hand-back that lands while a row under the other form is being linked still reaches it', async () => {
+ await human('111@lid');
+ const repo = ds.getRepository(ConversationMapping);
+ const save = repo.save.bind(repo);
+ jest.spyOn(repo, 'save').mockImplementationOnce(async (entity: unknown) => {
+ // The agent hands back on the lid conversation after the new row read the takeover.
+ await service.setHandover((await row('111@lid'))!.id, 'bot');
+ return save(entity as ConversationMapping);
+ });
+ await bot('[email protected]', 'convC');
+ expect(await service.findHandoverForChat('sess-1', '[email protected]')).toBeNull();
+ });
+
+ it('a row rebound from a deleted session keeps a takeover a fresh row in the new session does not hold', async () => {
+ await human('111@lid');
+ // The session is re-paired, and the chat arrives by phone before the old lid row is rebound.
+ await service.upsert(
+ { sessionId: 'sess-2', chatId: '[email protected]', pluginId: 'chatwoot-adapter', instanceId: 'i2' },
+ 'convC',
+ );
+ await service.rebindSession((await row('111@lid'))!.id, 'sess-2');
+ expect(await service.findHandoverForChat('sess-2', '[email protected]')).toEqual({
+ pluginId: 'chatwoot-adapter',
+ handoverState: 'human',
+ });
+ });
+ });
+
it('delete removes the row so a later reverse-key insert no longer conflicts', async () => {
await service.upsert(key, 'conv-1');
const row = await service.get(key);
diff --git a/src/modules/integration/conversation-mapping.service.ts b/src/modules/integration/conversation-mapping.service.ts
index 7ce03e55d..ca2c4e4f3 100644
--- a/src/modules/integration/conversation-mapping.service.ts
+++ b/src/modules/integration/conversation-mapping.service.ts
@@ -1,8 +1,10 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Optional } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
-import { QueryDeepPartialEntity, Repository } from 'typeorm';
+import { In, QueryDeepPartialEntity, Repository } from 'typeorm';
import { ConversationMapping, HandoverState } from './entities/conversation-mapping.entity';
import { isUniqueViolation } from '../../common/utils/db-errors';
+import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
+import { parseWaId } from '../../engine/identity/wa-id';
// Type-only: PluginsModule binds this class to PLUGIN_CONVERSATION_MAPPING_PORT with a `useExisting`
// alias, which TypeScript does not check, so `implements` is what keeps the two in step.
import type { PluginConversationMappingPort } from '../../core/plugins/plugin-host-ports';
@@ -34,7 +36,10 @@ export class ConversationMappingConflict extends Error {
@Injectable()
export class ConversationMappingService implements PluginConversationMappingPort {
- constructor(@InjectRepository(ConversationMapping, 'data') private readonly repo: Repository<ConversationMapping>) {}
+ constructor(
+ @InjectRepository(ConversationMapping, 'data') private readonly repo: Repository<ConversationMapping>,
+ @Optional() private readonly lidMappingStore?: LidMappingStoreService,
+ ) {}
async upsert(key: MappingKey, providerConversationId: string, patch?: Partial<ConversationMapping>): Promise<void> {
const existing = await this.repo.findOne({ where: key });
@@ -43,7 +48,14 @@ export class ConversationMappingService implements PluginConversationMappingPort
return;
}
try {
- await this.repo.save(this.repo.create({ ...key, providerConversationId, handoverState: 'bot', ...patch }));
+ const handoverState = await this.inheritedHandover(key);
+ await this.repo.save(this.repo.create({ ...key, providerConversationId, handoverState, ...patch }));
+ // A hand-back on the other form between the read above and this insert did not reach the new row;
+ // read again now that the row exists (a later decision updates it directly).
+ if (!patch?.handoverState && handoverState !== 'bot') {
+ const current = await this.inheritedHandover(key);
+ if (current !== handoverState) await this.repo.update({ ...key }, { handoverState: current });
+ }
} catch (err) {
if (!isUniqueViolation(err)) throw err;
// A concurrent writer inserted between our findOne and save (forward-key race) OR the reverse
@@ -81,21 +93,55 @@ export class ConversationMappingService implements PluginConversationMappingPort
return this.repo.findOne({ where: key });
}
- // Session+chat-scoped handover lookup for the core gate: the most-recently-updated human/closed row for
- // this chat, IGNORING pluginId. A handover taken by one plugin (e.g. the Chatwoot relay) then governs
- // every plugin on that chat — the gate exempts the owner and silences the rest.
+ // Session+chat-scoped handover lookup for the core gate: a human/closed state held by any row for this
+ // chat, IGNORING pluginId. A handover taken by one plugin (e.g. the Chatwoot relay) then governs every
+ // plugin on that chat — the gate exempts the owner and silences the rest.
+ //
+ // A 1:1 chat's neutral id is `<lid>@lid` while its lid is unresolved and `<phone>@c.us` once the
+ // mapping is learned, so a row written under one form is matched from the other as well. Keyed on
+ // the literal id alone, a takeover recorded before the mapping was learned stopped applying after
+ // it, and the bot answered a chat a human had taken over. Rows stay keyed on the literal id, so one
+ // plugin instance can hold a row under each form; setHandover writes the decision to every one of
+ // them, and a new row under another form starts in the state the instance already holds, so they agree.
async findHandoverForChat(
sessionId: string,
chatId: string,
): Promise<{ pluginId: string; handoverState: HandoverState } | null> {
- const row = await this.repo.findOne({
- where: [
- { sessionId, chatId, handoverState: 'human' },
- { sessionId, chatId, handoverState: 'closed' },
- ],
+ const rows = await this.repo.find({
+ where: { sessionId, chatId: In(await this.chatIdAliases(chatId)) },
order: { updatedAt: 'DESC' },
});
- return row ? { pluginId: row.pluginId, handoverState: row.handoverState } : null;
+ const held = rows.find(row => row.handoverState === 'human' || row.handoverState === 'closed');
+ return held ? { pluginId: held.pluginId, handoverState: held.handoverState } : null;
+ }
+
+ // A plugin instance's first row under a chat's other id form starts in the handover the instance holds
+ // under the old form. The adapter finds no mapping for the new form and links a fresh one; starting
+ // it as 'bot' would leave the two forms disagreeing about a takeover.
+ private async inheritedHandover(key: MappingKey): Promise<HandoverState> {
+ const others = (await this.chatIdAliases(key.chatId)).filter(id => id !== key.chatId);
+ if (!others.length) return 'bot';
+ const prior = await this.repo.find({ where: { ...key, chatId: In(others) } });
+ return prior.find(row => row.handoverState !== 'bot')?.handoverState ?? 'bot';
+ }
+
+ /**
+ * The chat id plus its other individual forms: the phone it belongs to and every lid of that phone.
+ * A number WhatsApp recycled keeps its earlier owner's lid in the table too, and the table cannot
+ * tell which lid is current (a mapping is re-stamped whenever it is seen again), so for handover the
+ * two owners' chats are one chat: a takeover or a hand-back on either reaches both.
+ */
+ private async chatIdAliases(chatId: string): Promise<string[]> {
+ const ids = new Set([chatId]);
+ const { kind, userPart } = parseWaId(chatId);
+ const store = this.lidMappingStore;
+ const phone = kind === 'lid' ? await store?.findPhoneForLid(userPart) : kind === 'user' ? userPart : null;
+ if (phone && store) {
+ // The whole set: the phone and every lid of it, so a lid reaches its sibling lids as the phone does.
+ ids.add(`${phone}@c.us`);
+ for (const lid of await store.findLidsForPhone(phone)) ids.add(`${lid}@lid`);
+ }
+ return [...ids];
}
getByProvider(
@@ -106,8 +152,17 @@ export class ConversationMappingService implements PluginConversationMappingPort
return this.repo.findOne({ where: { pluginId, instanceId, providerConversationId } });
}
+ // A handover decision is about the chat, not one id form of it: it is written to every row this plugin
+ // instance holds for the chat in the session, so a later write to one form (an idempotent upsert)
+ // cannot revive or drop the decision through the other. A row rebound from a deleted session keeps
+ // the state it carried; where that disagrees with its other form, the gate reads the chat as taken
+ // over until the next decision, which errs on the side of keeping the bot quiet.
async setHandover(id: string, state: HandoverState): Promise<void> {
- await this.repo.update({ id }, { handoverState: state });
+ const row = await this.repo.findOne({ where: { id } });
+ if (!row) return;
+ const { sessionId, pluginId, instanceId } = row;
+ const chatId = In(await this.chatIdAliases(row.chatId));
+ await this.repo.update({ sessionId, pluginId, instanceId, chatId }, { handoverState: state });
}
/**