Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(message): declare the whatsapp-web.js send-shape 501s

Yudhi Armyndharis63180cbf5213
diff --git a/src/modules/message/message.controller.ts b/src/modules/message/message.controller.ts
index a5a735952..abe5eb34a 100644
--- a/src/modules/message/message.controller.ts
+++ b/src/modules/message/message.controller.ts
@@ -60,6 +60,13 @@ import {
RECIPIENT_UNREACHABLE_400,
} from '../../common/openapi/engine-status-responses';
+// whatsapp-web.js drops these sends without an error, so its adapter refuses them up front
+// (ensureSendable in wwebjs-messaging.ts). The contract keeps one entry per status, so on a route
+// that already declares a 501 these are appended to its text rather than declared again.
+const CHANNEL_OR_BROADCAST = 'a channel (`<id>@newsletter`) or a status or broadcast list (`@broadcast`)';
+const QUOTED_SEND_501 = `whatsapp-web.js also refuses a send with \`quotedMessageId\` to ${CHANNEL_OR_BROADCAST}; nothing is sent.`;
+const wwebjsRefuses501 = (what: string): string => `whatsapp-web.js cannot send ${what}; nothing is sent.`;
+
@ApiTags('messages')
@Controller('sessions/:sessionId/messages')
export class MessageController {
@@ -151,7 +158,7 @@ export class MessageController {
description: 'Session not active or invalid request',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 501, description: CUSTOM_LINK_PREVIEW_501 })
+ @ApiResponse({ status: 501, description: `${CUSTOM_LINK_PREVIEW_501} ${QUOTED_SEND_501}` })
async sendText(@Param('sessionId') sessionId: string, @Body() dto: SendTextMessageDto): Promise<MessageResponseDto> {
return this.messageService.sendText(sessionId, dto);
}
@@ -197,7 +204,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })
+ @ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
async sendImage(
@@ -223,7 +230,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })
+ @ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
async sendVideo(
@@ -249,7 +256,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })
+ @ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
async sendAudio(
@@ -275,7 +282,7 @@ export class MessageController {
description: 'Session not active, invalid request, or a url that answers non-2xx, times out or cannot be reached',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
- @ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })
+ @ApiResponse({ status: 501, description: `${CHANNEL_MEDIA_501} ${QUOTED_SEND_501}` })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
async sendDocument(
@@ -300,6 +307,7 @@ export class MessageController {
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
+ @ApiResponse({ status: 501, description: wwebjsRefuses501(`a location to ${CHANNEL_OR_BROADCAST}`) })
async sendLocation(@Param('sessionId') sessionId: string, @Body() dto: SendLocationDto): Promise<MessageResponseDto> {
return this.messageService.sendLocation(sessionId, dto);
}
@@ -317,6 +325,7 @@ export class MessageController {
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
+ @ApiResponse({ status: 501, description: wwebjsRefuses501(`a contact card to ${CHANNEL_OR_BROADCAST}`) })
async sendContact(@Param('sessionId') sessionId: string, @Body() dto: SendContactDto): Promise<MessageResponseDto> {
return this.messageService.sendContact(sessionId, dto);
}
@@ -334,7 +343,10 @@ export class MessageController {
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
- @ApiResponse({ status: 501, description: CHANNEL_MEDIA_501 })
+ @ApiResponse({
+ status: 501,
+ description: `${CHANNEL_MEDIA_501} ${wwebjsRefuses501('a sticker to a status or broadcast list (`@broadcast`) either')}`,
+ })
@ApiResponse({ status: 413, description: MEDIA_TOO_LARGE_413 })
@ApiResponse({ status: 503, description: MEDIA_URL_PROXY_503 })
async sendSticker(
@@ -357,6 +369,12 @@ export class MessageController {
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
+ @ApiResponse({
+ status: 501,
+ description: wwebjsRefuses501(
+ 'a poll to a status or broadcast list (`@broadcast`), nor one with `quotedMessageId` to a channel (`<id>@newsletter`)',
+ ),
+ })
async sendPoll(@Param('sessionId') sessionId: string, @Body() dto: SendPollDto): Promise<MessageResponseDto> {
return this.messageService.sendPoll(sessionId, dto);
}
@@ -375,6 +393,7 @@ export class MessageController {
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 400, description: RECIPIENT_UNREACHABLE_400 })
@ApiResponse({ status: 404, description: MESSAGE_NOT_FOUND_404 })
+ @ApiResponse({ status: 501, description: wwebjsRefuses501(`a reply to ${CHANNEL_OR_BROADCAST}`) })
async reply(@Param('sessionId') sessionId: string, @Body() dto: ReplyMessageDto): Promise<MessageResponseDto> {
return this.messageService.reply(sessionId, dto);
}