Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(message): validate bulk items and send through the live engine
Yudhi Armyndhariscd0aa744ddd6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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-14diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 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.tsindex 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.tsindex 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/secuimport { 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 contentinterface 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 cancellationif (!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 — bothdiff --git a/src/modules/message/dto/bulk-message.dto.spec.ts b/src/modules/message/dto/bulk-message.dto.spec.tsindex 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.tsindex 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'] })