Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(contact): answer 409 for batch pictures when the engine is not ready

Yudhi Armyndharisd3455a4f2fa2
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 012c78ff1..7b5752172 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -2527,6 +2527,8 @@ Batch-resolve profile picture URLs for many contacts in one request (a chat side
`pictures` is keyed by the requested id. A per-id failure — or a lookup that exceeds the 8 s per-id deadline — yields `null` for that id rather than failing the batch. An omitted or empty `ids` returns `{ "pictures": {} }`.
+An engine that is not ready is the exception: it describes the session rather than one id, so the whole request answers `409` and no partial result is returned.
+
> Route-order caveat: `profile-pictures` is declared **before** `GET /:contactId`, so the literal segment wins — a contact whose id is literally `profile-pictures` cannot be fetched through the single-contact route.
**Errors:** `400` session is not started · `401` missing/invalid API key, or key not scoped to this session · `409` conflict or engine not ready (retryable)
diff --git a/src/modules/contact/contact.service.spec.ts b/src/modules/contact/contact.service.spec.ts
index 1f2523391..e36188c64 100644
--- a/src/modules/contact/contact.service.spec.ts
+++ b/src/modules/contact/contact.service.spec.ts
@@ -2,6 +2,8 @@ import { BadRequestException, ConflictException, NotFoundException } from '@nest
import { ContactService } from './contact.service';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
+import { EngineTransportError } from '../../common/errors/engine-transport.error';
describe('ContactService', () => {
const makeService = (engine: Partial<IWhatsAppEngine> | undefined) => {
@@ -73,6 +75,26 @@ describe('ContactService', () => {
expect(out).toEqual({ '[email protected]': 'https://pps/1.jpg', '[email protected]': null, '[email protected]': 'https://pps/3.jpg' });
});
+ // Not ready is a fact about the session, not about one avatar: a 200 with every picture null would
+ // be cached by the dashboard as "nobody has a picture" for the whole stale window.
+ it('fails the whole batch with 409 when the engine is not ready, without starting further chunks', async () => {
+ const getProfilePicture = jest.fn().mockRejectedValue(new EngineNotReadyError());
+ const ids = Array.from({ length: 12 }, (_, i) => `${i}@c.us`);
+ const batch = makeService({ getProfilePicture }).getProfilePictures('s1', ids);
+ await expect(batch).rejects.toBeInstanceOf(EngineNotReadyError);
+ await expect(batch).rejects.toMatchObject({ status: 409 });
+ expect(getProfilePicture).toHaveBeenCalledTimes(5);
+ });
+
+ it('still nulls a single id whose lookup fails with a transport error', async () => {
+ const getProfilePicture = jest
+ .fn()
+ .mockRejectedValueOnce(new EngineTransportError('query stalled'))
+ .mockResolvedValueOnce('https://pps/2.jpg');
+ const out = await makeService({ getProfilePicture }).getProfilePictures('s1', ['[email protected]', '[email protected]']);
+ expect(out).toEqual({ '[email protected]': null, '[email protected]': 'https://pps/2.jpg' });
+ });
+
it('ignores ids beyond the 50-id batch cap', async () => {
const getProfilePicture = jest.fn().mockResolvedValue(null);
const ids = Array.from({ length: 60 }, (_, i) => `${i}@c.us`);
diff --git a/src/modules/contact/contact.service.ts b/src/modules/contact/contact.service.ts
index de88de1b5..e184258d9 100644
--- a/src/modules/contact/contact.service.ts
+++ b/src/modules/contact/contact.service.ts
@@ -3,6 +3,7 @@ import { EngineRegistry } from '../../engine/engine-registry.service';
import { createLogger } from '../../common/services/logger.service';
import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
import { paginate, ListOptions } from '../../common/utils/paginate';
+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { isIndividualWid, parseWaId, toNeutralJid } from '../../engine/identity/wa-id';
/**
@@ -85,7 +86,10 @@ export class ContactService {
* Batch-resolve profile picture URLs for a list of contact ids (the dashboard's chat-list avatars
* — one HTTP call instead of N, so the per-IP throttle isn't exhausted by a sidebar full of
* parallel fetches). Engine lookups run 5 at a time with a per-id deadline; a per-id failure or
- * timeout yields null for that id (hidden/no picture), never aborts the batch. Ids beyond
+ * timeout yields null for that id (hidden/no picture), never aborts the batch. The exception is
+ * EngineNotReadyError: it describes the session, not the id, so it fails the whole request with
+ * 409 after the current chunk and the remaining chunks are not started. Answering 200 with every
+ * avatar null would be cached by the dashboard as "no pictures". Ids beyond
* PROFILE_PICTURES_MAX_IDS are ignored.
*/
async getProfilePictures(sessionId: string, ids: string[]): Promise<Record<string, string | null>> {
@@ -93,6 +97,7 @@ export class ContactService {
const capped = ids.slice(0, ContactService.PROFILE_PICTURES_MAX_IDS);
const pictures: Record<string, string | null> = {};
const CHUNK = 5;
+ let notReady: EngineNotReadyError | undefined;
for (let i = 0; i < capped.length; i += CHUNK) {
const chunk = capped.slice(i, i + CHUNK);
const results = await Promise.all(
@@ -109,14 +114,16 @@ export class ContactService {
clearTimeout(timer);
resolve([id, url] as const);
},
- () => {
+ (error: unknown) => {
clearTimeout(timer);
+ if (error instanceof EngineNotReadyError) notReady = error;
resolve([id, null] as const);
},
);
});
}),
);
+ if (notReady) throw notReady;
for (const [id, url] of results) {
pictures[id] = url;
}