Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(message): validate bulk items and send through the live engine

Yudhi Armyndhariscd0aa744ddd6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ce9b6e97..9a0602859 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- A session whose automatic reconnect fails to relaunch the engine (a network, DNS or browser launch error) keeps retrying with backoff instead of stopping in `failed` until restarted by hand; an authentication failure or a stale browser profile still ends in `failed` ([#1580](https://github.com/rmyndharis/OpenWA/issues/1580)).
- A session that runs out of reconnect attempts fires the `session:error` plugin hook when it lands in `failed`.
- An explicit `maxReconnectAttempts` is honoured and the reconnect delay is capped at 5 minutes; the budget used to restart once the backoff passed 5 minutes, so the limit was never reached and the documented 1-hour cap never applied.
+- A bulk batch sends each message through the session's current engine, so a reconnect or restart mid-batch no longer fails every remaining message.
+- `POST /messages/send-bulk` answers 400 for an item with an empty `chatId`, a text item without text, or a media item without a `url` or `base64` under its type; such items used to be accepted with 202 and fail later.
+- `POST /messages/send-bulk` answers 400, not 500, when a concurrent request already created the same `batchId`.
## [0.23.5] - 2026-09-14
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 2f1f435ac..f93071372 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -2171,6 +2171,8 @@ Each `BulkMessageItemDto`: `{ chatId: string, type: 'text'|'image'|'video'|'audi
`BulkMessageOptionsDto`: `{ delayBetweenMessages?: number (1000–60000, default 3000), randomizeDelay?: boolean (default true), stopOnError?: boolean (default false) }`.
+Each item must carry what its `type` sends: a non-empty `chatId`, a non-empty `content.text` for `text`, and a `url` or `base64` under `content.<type>` for a media type. If any item does not, the request answers `400` and nothing is queued. The check runs again per item after `variables` and the `message:sending` gate, where a failure fails that item only.
+
Each item's base64 media is checked against the media byte cap (`MEDIA_DOWNLOAD_MAX_BYTES`) twice: at batch creation, and again per item after `variables` and the `message:sending` plugin gate are applied. An item that outgrows the cap only after rendering fails individually (`failed` in `results`, with `message:failed` fired) instead of being sent. `totalMessages` in the response reflects the de-duplicated item count.
The rendered text is bounded the same way, by `TEMPLATE_RENDER_MAX_CHARS` (default 64 KiB) — the limit the single-send template path already applied. `content.text` and `content.caption` are length-validated _before_ substitution, so caller-supplied `variables` could otherwise inflate each item without bound while the request body stayed far below the in-flight body budget. An item whose `text` or `caption` exceeds the limit after substitution fails individually with a message naming it, rather than being truncated silently or sent. Media is not bounded by this cap — `MEDIA_DOWNLOAD_MAX_BYTES` governs it, three orders of magnitude higher, because a 100 KB image is already ~137,000 base64 characters and would fail the character limit on every personalised media send.
diff --git a/src/modules/message/bulk-message.service.spec.ts b/src/modules/message/bulk-message.service.spec.ts
index f4205a3bd..9d2aa7fa3 100644
--- a/src/modules/message/bulk-message.service.spec.ts
+++ b/src/modules/message/bulk-message.service.spec.ts
@@ -1,5 +1,5 @@
import { Test, TestingModule } from '@nestjs/testing';
-import { HttpException, PayloadTooLargeException } from '@nestjs/common';
+import { BadRequestException, HttpException, PayloadTooLargeException } from '@nestjs/common';
import { getRepositoryToken } from '@nestjs/typeorm';
import { In, Not } from 'typeorm';
import {
@@ -453,6 +453,50 @@ describe('BulkMessageService.processBatch', () => {
expect(sendArgs[1]).toBe('hello world');
});
+ // A restart or reconnect registers a fresh adapter mid-batch; the retired one is not ready, so a
+ // batch holding it would fail every remaining item while the session is READY again.
+ it('sends each item through the engine registered at that moment, not the one the batch started with', async () => {
+ repo.findOne.mockResolvedValue(makeBatch(2));
+ const replacement = { sendTextMessage: jest.fn().mockResolvedValue({ id: 'wa2', timestamp: 222 }) };
+ engine.sendTextMessage.mockImplementationOnce(() => {
+ engines.set('s1', replacement as unknown as IWhatsAppEngine);
+ return Promise.resolve({ id: 'wa1', timestamp: 111 });
+ });
+
+ await runProcessBatch();
+
+ expect(engine.sendTextMessage).toHaveBeenCalledTimes(1);
+ expect(replacement.sendTextMessage).toHaveBeenCalledWith('[email protected]', 'hi');
+ });
+
+ it('fails only the item whose engine is gone mid-batch, without feeding the send breaker', async () => {
+ repo.findOne.mockResolvedValue(makeBatch(2));
+ engine.sendTextMessage.mockImplementationOnce(() => {
+ engines.delete('s1');
+ return Promise.resolve({ id: 'wa1', timestamp: 111 });
+ });
+
+ await runProcessBatch();
+
+ const finalPartial = (repo.update.mock.calls as Array<[unknown, { results: BatchMessageResult[] }]>).at(-1)![1];
+ expect(finalPartial.results.map(r => r.status)).toEqual([BatchMessageStatus.SENT, BatchMessageStatus.FAILED]);
+ expect(finalPartial.results[1].error?.message).toMatch(/not connected/i);
+ expect(pacing.recordSendFailure).not.toHaveBeenCalled();
+ });
+
+ // The create-time check sees the raw input; a gate rewrite can still empty an item out.
+ it('fails an item the message:sending gate rewrote into content its type cannot send', async () => {
+ repo.findOne.mockResolvedValue(makeBatch(1));
+ hookManager.execute.mockResolvedValueOnce({ continue: true, data: { input: {} } });
+
+ await runProcessBatch();
+
+ expect(engine.sendTextMessage).not.toHaveBeenCalled();
+ const finalPartial = (repo.update.mock.calls as Array<[unknown, { results: BatchMessageResult[] }]>).at(-1)![1];
+ expect(finalPartial.results[0].status).toBe(BatchMessageStatus.FAILED);
+ expect(finalPartial.results[0].error?.message).toMatch(/content\.text/);
+ });
+
it('releases the in-flight marker when the engine is missing (no processingBatches leak)', async () => {
repo.findOne.mockResolvedValue(makeBatch(1));
engines.delete('s1'); // engine-not-found → early-return path
@@ -1086,7 +1130,7 @@ describe('BulkMessageService.createBatch base64 media cap', () => {
return pendingSave;
});
const dto = {
- messages: [{ chatId: '[email protected]', type: 'text' as const, content: { text: { body: 'hi' } } }],
+ messages: [{ chatId: '[email protected]', type: 'text' as const, content: { text: 'hi' } }],
} as unknown as SendBulkMessageDto;
try {
@@ -1107,7 +1151,7 @@ describe('BulkMessageService.createBatch base64 media cap', () => {
it('releases the cap reservation when persistence fails', async () => {
repo.save.mockRejectedValueOnce(new Error('database unavailable'));
const dto = {
- messages: [{ chatId: '[email protected]', type: 'text' as const, content: { text: { body: 'hi' } } }],
+ messages: [{ chatId: '[email protected]', type: 'text' as const, content: { text: 'hi' } }],
} as unknown as SendBulkMessageDto;
await expect(service.createBatch('s1', dto)).rejects.toThrow('database unavailable');
@@ -1115,6 +1159,43 @@ describe('BulkMessageService.createBatch base64 media cap', () => {
expect((service as unknown as { inFlightBatches: number }).inFlightBatches).toBe(0);
});
+ it.each([
+ ['a text item with no text', { chatId: '[email protected]', type: 'text', content: {} }, /content\.text/],
+ ['a text item with empty text', { chatId: '[email protected]', type: 'text', content: { text: '' } }, /content\.text/],
+ ['an image item with no media', { chatId: '[email protected]', type: 'image', content: {} }, /content\.image\.url/],
+ [
+ 'a document item whose media sits under another type',
+ { chatId: '[email protected]', type: 'document', content: { image: { url: 'https://example.com/a.jpg' } } },
+ /content\.document\.url/,
+ ],
+ ])('rejects %s with a 400 before persisting the batch', async (_label, item, message) => {
+ const create = service.createBatch('s1', { messages: [item] } as unknown as SendBulkMessageDto);
+
+ await expect(create).rejects.toBeInstanceOf(BadRequestException);
+ await expect(create).rejects.toThrow(message);
+ expect(repo.save).not.toHaveBeenCalled();
+ });
+
+ // Two concurrent creates with one caller-supplied batchId both pass the existence read; the unique
+ // index rejects the second, which must read as the same 400 as the sequential duplicate.
+ it('answers a duplicate batchId that loses the insert race with the same 400', async () => {
+ repo.save.mockRejectedValueOnce(
+ Object.assign(new Error('UNIQUE constraint failed: message_batches.sessionId, message_batches.batchId'), {
+ code: 'SQLITE_CONSTRAINT_UNIQUE',
+ }),
+ );
+ const dto = {
+ batchId: 'campaign-42',
+ messages: [{ chatId: '[email protected]', type: 'text' as const, content: { text: 'hi' } }],
+ } as unknown as SendBulkMessageDto;
+
+ const create = service.createBatch('s1', dto);
+
+ await expect(create).rejects.toBeInstanceOf(BadRequestException);
+ await expect(create).rejects.toThrow("Batch ID 'campaign-42' already exists");
+ expect((service as unknown as { inFlightBatches: number }).inFlightBatches).toBe(0);
+ });
+
it('scopes the batchId uniqueness check to the session (no cross-session collision/oracle)', async () => {
// Simulate a DB where batchId 'dup' exists only under session 's1'.
repo.findOne.mockImplementation((opts: { where: { batchId?: string; sessionId?: string } }) => {
@@ -1127,7 +1208,7 @@ describe('BulkMessageService.createBatch base64 media cap', () => {
// so it neither collides with another tenant's namespace nor leaks that the id is in use elsewhere.
await expect(
service.createBatch('s2', {
- messages: [{ chatId: '[email protected]', type: 'text', content: { text: { body: 'hi' } } }],
+ messages: [{ chatId: '[email protected]', type: 'text', content: { text: 'hi' } }],
batchId: 'dup',
} as unknown as SendBulkMessageDto),
).resolves.toBeDefined();
diff --git a/src/modules/message/bulk-message.service.ts b/src/modules/message/bulk-message.service.ts
index faef5df15..b9baed476 100644
--- a/src/modules/message/bulk-message.service.ts
+++ b/src/modules/message/bulk-message.service.ts
@@ -35,6 +35,8 @@ import { SsrfBlockedError, SSRF_BLOCKED_CLIENT_MESSAGE } from '../../common/secu
import { renderTemplate } from '../../common/utils/template-render';
import { IWhatsAppEngine, MessageResult } from '../../engine/interfaces/whatsapp-engine.interface';
import { resolveNonNegativeIntEnv } from '../../config/configuration';
+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
+import { isUniqueViolation } from '../../common/utils/db-errors';
// Type definitions for bulk message content
interface BulkMessageContent {
@@ -211,8 +213,9 @@ export class BulkMessageService implements OnApplicationBootstrap {
// its base64 payloads) is persisted into the batch row. Mirrors the single-send cap in
// MessageService.buildMediaInput. The same check runs again per item after variables and the
// message:sending gate are applied (see executeBatch).
- for (const { content } of messages) {
+ for (const { type, content } of messages) {
this.assertContentMediaWithinCap(content);
+ this.assertItemContent(type, content);
}
const batchId = dto.batchId || `batch_${randomUUID().split('-')[0]}`;
@@ -263,6 +266,11 @@ export class BulkMessageService implements OnApplicationBootstrap {
await this.batchRepository.save(batch);
} catch (error) {
this.inFlightBatches--;
+ // Two concurrent creates with the same caller-supplied batchId both pass the read above; the
+ // unique index decides, and the loser gets the same 400 as the sequential case.
+ if (isUniqueViolation(error)) {
+ throw new BadRequestException(`Batch ID '${batchId}' already exists`);
+ }
throw error;
}
this.logger.log(
@@ -367,15 +375,14 @@ export class BulkMessageService implements OnApplicationBootstrap {
private async executeBatch(batch: MessageBatch): Promise<void> {
if (!(await this.markBatchProcessing(batch))) return;
- const engine = this.engines.get(batch.sessionId);
- if (!engine) {
+ if (!this.engines.get(batch.sessionId)) {
await this.failBatchWithoutEngine(batch);
return;
}
const results: BatchMessageResult[] = batch.results || [];
const state: BatchExecutionState = { results, stoppedOnError: false, cancelledByDb: false };
- await this.processBatchMessages(batch, engine, state);
+ await this.processBatchMessages(batch, state);
await this.finalizeBatch(batch, state);
}
@@ -408,13 +415,9 @@ export class BulkMessageService implements OnApplicationBootstrap {
} as QueryDeepPartialEntity<MessageBatch>);
}
- private async processBatchMessages(
- batch: MessageBatch,
- engine: IWhatsAppEngine,
- state: BatchExecutionState,
- ): Promise<void> {
+ private async processBatchMessages(batch: MessageBatch, state: BatchExecutionState): Promise<void> {
for (let i = batch.currentIndex; i < batch.messages.length; i++) {
- if (!(await this.processBatchMessage(batch, engine, i, state))) break;
+ if (!(await this.processBatchMessage(batch, i, state))) break;
}
}
@@ -422,12 +425,7 @@ export class BulkMessageService implements OnApplicationBootstrap {
* Send one batch message through the moderation gate, record the outcome, and persist progress.
* Returns false when the batch loop must stop (cancellation or stopOnError).
*/
- private async processBatchMessage(
- batch: MessageBatch,
- engine: IWhatsAppEngine,
- i: number,
- state: BatchExecutionState,
- ): Promise<boolean> {
+ private async processBatchMessage(batch: MessageBatch, i: number, state: BatchExecutionState): Promise<boolean> {
const { results } = state;
// Check for cancellation
if (!this.processingBatches.get(batch.id)) {
@@ -494,6 +492,12 @@ export class BulkMessageService implements OnApplicationBootstrap {
// gate rewrite can grow base64 media past the limit createBatch verified on the raw input.
// A violation fails just this item (honouring stopOnError) instead of sending it.
this.assertContentMediaWithinCap(content);
+ this.assertItemContent(msg.type, content);
+
+ // Resolved per item, not once per batch: a session restart or reconnect registers a fresh
+ // adapter, and a batch still holding the retired one would fail every remaining item.
+ const engine = this.engines.get(batch.sessionId);
+ if (!engine) throw new EngineNotReadyError();
// Send message based on type. The engine call is bracketed on its own so the pacing breaker
// hears exactly what the single-send path feeds it (message.service failSend/persistSentState):
@@ -635,6 +639,24 @@ export class BulkMessageService implements OnApplicationBootstrap {
this.logger.log(`Batch ${batch.batchId} completed: ${batch.progress.sent} sent, ${batch.progress.failed} failed`);
}
+ /**
+ * Require the field the item's type sends: a non-empty text for a text item, a url or base64 under
+ * the matching media key otherwise. The DTO cannot express this per type, so it runs at batch
+ * creation (a 400) and again per item after variables and the message:sending gate.
+ */
+ private assertItemContent(type: string, content: BulkMessageContent): void {
+ if (type === 'text') {
+ if (typeof content?.text !== 'string' || !content.text) {
+ throw new BadRequestException('A text item requires a non-empty content.text');
+ }
+ return;
+ }
+ const media = content?.[type as 'image' | 'video' | 'audio' | 'document'];
+ if (!stripBase64DataUri(media?.base64) && !media?.url) {
+ throw new BadRequestException(`A ${type} item requires content.${type}.url or content.${type}.base64`);
+ }
+ }
+
/**
* Bound one content payload's base64 media to the shared media byte cap. Runs at batch creation
* and again per item after template variables and the message:sending gate are applied — both
diff --git a/src/modules/message/dto/bulk-message.dto.spec.ts b/src/modules/message/dto/bulk-message.dto.spec.ts
index 3f3ba6892..9044fddad 100644
--- a/src/modules/message/dto/bulk-message.dto.spec.ts
+++ b/src/modules/message/dto/bulk-message.dto.spec.ts
@@ -43,3 +43,11 @@ describe('SendBulkMessageDto content length + variables validation', () => {
expect((await validateBulk(textItem('hi', { variables: [1, 2, 3] }))).length).toBeGreaterThan(0);
});
});
+
+describe('SendBulkMessageDto recipient', () => {
+ it('rejects an empty chatId', async () => {
+ expect((await validateBulk(textItem('hi'))).length).toBe(0);
+ const errors = await validateBulk({ messages: [{ chatId: '', type: 'text', content: { text: 'hi' } }] });
+ expect(errors.length).toBeGreaterThan(0);
+ });
+});
diff --git a/src/modules/message/dto/bulk-message.dto.ts b/src/modules/message/dto/bulk-message.dto.ts
index bf34d26c7..f1e15304c 100644
--- a/src/modules/message/dto/bulk-message.dto.ts
+++ b/src/modules/message/dto/bulk-message.dto.ts
@@ -1,6 +1,7 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import {
IsString,
+ IsNotEmpty,
IsIn,
IsArray,
IsObject,
@@ -109,6 +110,7 @@ class BulkMessageContentDto {
class BulkMessageItemDto {
@ApiProperty({ description: 'Recipient chat ID', example: '[email protected]' })
@IsString()
+ @IsNotEmpty()
chatId!: string;
@ApiProperty({ description: 'Message type', enum: ['text', 'image', 'video', 'audio', 'document'] })