Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import {
Controller,
Get,
Post,
Patch,
Put,
Delete,
Param,
Query,
Body,
HttpCode,
HttpStatus,
ParseUUIDPipe,
BadRequestException,
ForbiddenException,
Res,
} from '@nestjs/common';
import type { Response } from 'express';
import { ApiTags, ApiOperation, ApiResponse, ApiParam, ApiQuery, ApiExtraModels, getSchemaPath } from '@nestjs/swagger';
import { SessionService } from './session.service';
import {
CreateSessionDto,
SessionConfigResponseDto,
UpdateSessionConfigDto,
SessionProxyResponseDto,
UpdateSessionProxyDto,
SessionResponseDto,
QRCodeResponseDto,
MarkChatReadDto,
MarkChatUnreadDto,
SubscribePresenceDto,
SetOwnPresenceDto,
ChatPresenceResponseDto,
ArchiveChatDto,
MuteChatDto,
PinChatDto,
DeleteChatDto,
SendChatStateDto,
RequestPairingCodeDto,
PairingCodeResponseDto,
ChatSummaryDto,
SessionActionResponseDto,
SessionGroupSummaryDto,
SessionsOverviewResponseDto,
} from './dto';
import { Session } from './entities/session.entity';
import { ChatSummary } from '../../engine/interfaces/whatsapp-engine.interface';
import { paginate } from '../../common/utils/paginate';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import {
ChatScoped,
CurrentApiKey,
RequireRole,
RequireUnscopedKey,
SessionScoped,
} from '../auth/decorators/auth.decorators';
import { ChatScopeService } from '../auth/chat-scope.service';
import { ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';
import {
ENGINE_NOT_READY_409,
PAIRING_NOT_READY_409,
PAIRING_TRANSPORT_503,
RECIPIENT_LOOKUP_503,
} from '../../common/openapi/engine-status-responses';
@ApiTags('sessions')
@Controller('sessions')
// The `:sessionId` route param here is a WhatsApp session id, so the ApiKeyGuard enforces a key's
// allowedSessions scope against it (other controllers' `:id` is an unrelated resource id).
@SessionScoped()
export class SessionController {
constructor(
private readonly sessionService: SessionService,
private readonly auditService: AuditService,
private readonly chatScope: ChatScopeService,
) {}
private transformSession(session: Session): SessionResponseDto {
// engineLoaded() reads the engine map itself, so this is read at response time: a session that just
// finished reconnecting reports the engine in the same response that reports its status.
return SessionResponseDto.fromEntity(session, this.sessionService.engineLoaded(session));
}
@Post()
@RequireRole(ApiKeyRole.OPERATOR)
// Creating a session has no existing session id for the class-level @SessionScoped fence to check,
// and the new session is outside the caller's allowlist by construction — so a key restricted to
// specific sessions cannot create one. Different metadata key from @SessionScoped; they coexist.
@RequireUnscopedKey()
@ApiOperation({ summary: 'Create a new WhatsApp session' })
@ApiResponse({
status: 201,
description: 'Session created',
type: SessionResponseDto,
})
@ApiResponse({
status: 403,
description:
'Key lacks the OPERATOR role, is restricted to specific sessions, or set proxyUrl without the ADMIN role',
})
@ApiResponse({ status: 400, description: 'Validation failed, or the body carries a field the DTO does not declare.' })
@ApiResponse({ status: 409, description: 'Session name already exists' })
@ApiResponse({
status: 503,
description: 'On SQLite, another database transaction stayed open for 10 s; nothing was stored, so retry.',
})
async create(@Body() dto: CreateSessionDto, @CurrentApiKey() apiKey?: ApiKey): Promise<SessionResponseDto> {
// A session proxy carries the session's egress, including the gateway's fetches of caller-supplied
// URLs, so choosing one is a deployment decision: ADMIN only, like PATCH :sessionId/proxy. The
// global guard always attaches the key, so a missing one is refused too.
if (dto.proxyUrl && apiKey?.role !== ApiKeyRole.ADMIN) {
throw new ForbiddenException('Setting proxyUrl requires an ADMIN key');
}
const session = await this.sessionService.create(dto);
await this.auditService.logInfo(AuditAction.SESSION_CREATED, {
sessionId: session.id,
sessionName: session.name,
});
return this.transformSession(session);
}
@Get()
@ApiOperation({ summary: 'List all sessions' })
@ApiResponse({
status: 200,
description: 'List of sessions',
type: [SessionResponseDto],
})
@ApiQuery({ name: 'limit', required: false, description: 'Max sessions to return (1-1000, default 1000)' })
@ApiQuery({ name: 'offset', required: false, description: 'Number of sessions to skip (for paging)' })
@ApiQuery({
name: 'name',
required: false,
type: String,
description:
'Return only the session with exactly this name (case-sensitive); no match returns an empty array. ' +
'An empty value or a repeated key is rejected with 400.',
})
@ApiResponse({ status: 400, description: '`name` is empty or repeated.' })
async findAll(
@CurrentApiKey() apiKey?: ApiKey,
@Query('limit') limit?: string,
@Query('offset') offset?: string,
@Query('name') name?: string | string[],
): Promise<SessionResponseDto[]> {
// ?name=a&name=b arrives as an array and ?name= as ''; neither names one session, and silently
// dropping the filter would hand back every session instead.
if (Array.isArray(name) || name === '') {
throw new BadRequestException('name must be a single non-empty value');
}
// Scope to the key's allowedSessions so a session-restricted key cannot enumerate every
// session. A null/empty allowlist lists all whatever the key's role; a scoped ADMIN key is filtered too.
const sessions = await this.sessionService.findAll(apiKey?.allowedSessions, {
limit: limit ? parseInt(limit, 10) : undefined,
offset: offset ? parseInt(offset, 10) : undefined,
name,
});
return sessions.map(s => this.transformSession(s));
}
@ChatScoped('agnostic')
@Get(':sessionId')
@ApiOperation({ summary: 'Get session by ID' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Session details',
type: SessionResponseDto,
})
@ApiResponse({ status: 400, description: 'The session id is not a UUID' })
@ApiResponse({ status: 404, description: 'Session not found' })
async findOne(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
const session = await this.sessionService.findOne(id);
return this.transformSession(session);
}
@Get(':sessionId/config')
@ApiOperation({ summary: 'Get the tunable configuration for a session' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Effective session configuration',
type: SessionConfigResponseDto,
})
@ApiResponse({ status: 400, description: 'The session id is not a UUID' })
@ApiResponse({ status: 404, description: 'Session not found' })
async getConfig(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionConfigResponseDto> {
return this.sessionService.getConfig(id);
}
@Patch(':sessionId/config')
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({
summary: 'Update the tunable configuration for a session',
description:
'Merges the supplied keys into the session config; omitted keys are left unchanged and an ' +
'explicit null clears a key back to its default. No restart is required or performed. ' +
'`autoRejectCalls` is re-read on every incoming call, so it applies immediately; the two ' +
'reconnect settings are read once per start and therefore apply on the next start.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Updated session configuration',
type: SessionConfigResponseDto,
})
@ApiResponse({ status: 400, description: 'A supplied value is outside its accepted range' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({ status: 409, description: 'The session config kept changing under concurrent requests; retry' })
async updateConfig(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: UpdateSessionConfigDto,
): Promise<SessionConfigResponseDto> {
const config = await this.sessionService.updateConfig(id, dto);
await this.auditService.logInfo(AuditAction.SESSION_CONFIG_UPDATED, {
sessionId: id,
// The resulting state, not the request: a merge patch is meaningless in an audit trail without
// knowing what it merged into. Only the three recognised keys, never the raw column.
metadata: { ...config },
});
return config;
}
@Get(':sessionId/proxy')
@ApiOperation({ summary: 'Get the per-session egress proxy configuration (credentials masked)' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Effective proxy configuration',
type: SessionProxyResponseDto,
})
@ApiResponse({ status: 400, description: 'The session id is not a UUID' })
@ApiResponse({ status: 404, description: 'Session not found' })
async getProxy(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionProxyResponseDto> {
return this.sessionService.getProxy(id);
}
@Patch(':sessionId/proxy')
// A session proxy carries all of the session's egress, including the gateway's fetches of
// caller-supplied URLs, and its host is not checked against internal addresses: it is trusted
// egress chosen by the deployment's administrator. Setting or clearing it is therefore ADMIN only,
// like proxyUrl on POST /sessions, and never open to a key restricted to specific sessions.
@RequireRole(ApiKeyRole.ADMIN)
@RequireUnscopedKey()
@ApiOperation({
summary: 'Update the per-session egress proxy configuration',
description:
'Sets or clears the proxy URL. Credentials in `proxyUrl` are stored but never returned by GET. ' +
'No restart is performed — changes apply on the next session start.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Updated proxy configuration',
type: SessionProxyResponseDto,
})
@ApiResponse({ status: 400, description: 'Invalid proxyUrl' })
@ApiResponse({ status: 403, description: 'Key lacks the ADMIN role, or is restricted to specific sessions' })
@ApiResponse({ status: 404, description: 'Session not found' })
async updateProxy(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: UpdateSessionProxyDto,
): Promise<SessionProxyResponseDto> {
const proxy = await this.sessionService.updateProxy(id, dto);
await this.auditService.logInfo(AuditAction.SESSION_CONFIG_UPDATED, {
sessionId: id,
metadata: { proxyEnabled: proxy.enabled, proxyType: proxy.proxyType, proxyHost: proxy.proxyHost },
});
return proxy;
}
@Delete(':sessionId')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.NO_CONTENT)
@ApiOperation({ summary: 'Delete a session' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({ status: 204, description: 'Session deleted' })
@ApiResponse({ status: 400, description: 'The session id is not a UUID' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 409,
description:
'A credential teardown for the same session name is still in flight (retryable: the body ' +
"carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; wait for it to settle and retry), OR " +
"another node currently holds this session's live engine and deleting it here would strip a " +
'session the owner is running, OR ownership changes while deletion runs. The first two refusals ' +
'remove nothing. Ownership loss stops later deletion units; earlier batches may already be committed.',
})
async delete(@Param('sessionId', ParseUUIDPipe) id: string): Promise<void> {
const session = await this.sessionService.findOne(id);
await this.sessionService.delete(id);
await this.auditService.logInfo(AuditAction.SESSION_DELETED, {
sessionId: id,
sessionName: session.name,
});
}
@Post(':sessionId/start')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({
summary: 'Start a session and initialize WhatsApp connection',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Session started',
type: SessionResponseDto,
})
@ApiResponse({
status: 400,
description:
'Session already started or already starting, or this node is at its MAX_CONCURRENT_SESSIONS cap ' +
'(`Maximum concurrent sessions reached (N)`), answered only after the 404 and the 409 for a ' +
'session running on another node; a start refused at the cap launches nothing and leaves a ' +
'stop in place.',
})
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 409,
description:
'A credential teardown for the same session name is still in flight (e.g. a prior logout ' +
'that owns destructive cleanup). Retryable — the body carries `code: ' +
'SESSION_NAME_TEARDOWN_PENDING`; wait for it to settle and retry. No destructive side ' +
'effect runs before this refusal. Also returned when another node currently holds this ' +
"session's engine: only the owner may start it, and the claim is refused before any engine " +
'is launched, so no second connection to the account is opened. Also returned, with no `code`, ' +
'when a stop, a logout or force-kill that found a running engine, or a data import (`stopOrphans`) ' +
'of this session began or finished while the start was waiting, or a delete of it was still ' +
'running: the start yields and launches nothing. After a stop or force-kill, a new POST /start ' +
'clears it and starts the session; after a delete, or an import that removed the session, the ' +
'retry answers 404.',
})
@ApiResponse({
status: 503,
description:
"The gateway is shutting down, or the engine's browser or socket connection died during launch and " +
'the one automatic retry failed too; no engine is left running, so the start can be retried.',
})
@ApiResponse({
status: 504,
description:
'The engine did not finish starting within its timeout (WhatsApp Web or the network unreachable, ' +
'a stalled browser or resource limit, or, on whatsapp-web.js, an unreachable proxyUrl or the auth ' +
'timeout); the engine is torn down and the start can be retried.',
})
async start(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
const session = await this.sessionService.start(id, { explicit: true });
await this.auditService.logInfo(AuditAction.SESSION_STARTED, {
sessionId: session.id,
sessionName: session.name,
});
return this.transformSession(session);
}
@Post(':sessionId/stop')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Stop a session and disconnect WhatsApp' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Session stopped',
type: SessionResponseDto,
})
@ApiResponse({ status: 400, description: 'The session id is not a UUID' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 409,
description:
"Another node currently holds this session's live engine (multi-node deployments): stopping " +
'it here would report the session down while the owner keeps running it, so the request is ' +
'refused. Retry against the owning node, or once its lease has lapsed.',
})
@ApiResponse({
status: 502,
description:
'Session was stopped locally, but the engine teardown did not complete (the graceful ' +
'disconnect and the force-destroy escalation both failed, so the engine process may still ' +
"be running). Retryable — the body carries `code: 'SESSION_STOP_INCOMPLETE'`; the status " +
'is settled to `disconnected` and no success audit is written. Retry the stop; restart the ' +
'node to reap a leaked process.',
})
async stop(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
const session = await this.sessionService.stop(id);
await this.auditService.logInfo(AuditAction.SESSION_STOPPED, {
sessionId: session.id,
sessionName: session.name,
});
return this.transformSession(session);
}
@Post(':sessionId/logout')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({
summary: 'Log out of WhatsApp (unlinks this device) and stop the session',
description:
'Attempts an engine-native unlink of this companion device, then tears the session down ' +
'locally. `200` means the engine-native unlink operation completed AND the required local ' +
'credential cleanup completed — for Baileys a valid companion identity, an acknowledged ' +
'`remove-companion-device` IQ response, and removal of the on-disk auth dir; for ' +
'whatsapp-web.js the native `Client.logout()` promise settled. `200` is NOT an independent ' +
'observation that the handset UI no longer shows the linked device. Because a completed ' +
'unlink wipes the stored credentials, reconnecting after a `200` always requires a fresh QR ' +
'scan or pairing code.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Unlink operation and required local cleanup completed; session is stopped and `phone` is ' +
'cleared. Recorded in the audit log as `session_logged_out`.',
content: {
'application/json': {
schema: { $ref: '#/components/schemas/SessionResponseDto' },
example: {
id: '8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a',
name: 'my-bot',
status: 'disconnected',
phone: null,
// logout clears `phone` only, so a session that had connected keeps the name and the
// connection timestamp it was last linked with.
pushName: 'John Doe',
connectedAt: '2026-06-24T08:15:00.000Z',
lastActive: '2026-06-25T09:01:55.000Z',
createdAt: '2026-06-20T11:30:00.000Z',
updatedAt: '2026-06-25T09:11:00.000Z',
lastError: null,
restriction: null,
// The engine is torn out of the map before the status write, so a logout always reports false.
engineLoaded: false,
},
},
},
})
@ApiResponse({
status: 400,
description: 'Session is not started (no engine to send through); the row is left untouched',
})
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 502,
description:
'Session was stopped locally, but the logout operation is incomplete (no send, no ' +
'acknowledgement, timeout/transport error, or local-cleanup failure). Retryable — the ' +
"body carries `code: 'SESSION_LOGOUT_INCOMPLETE'`; `phone` is cleared and no success audit " +
'is written. Start the session again and retry the logout.',
})
async logout(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
const session = await this.sessionService.logout(id);
await this.auditService.logInfo(AuditAction.SESSION_LOGGED_OUT, {
sessionId: session.id,
sessionName: session.name,
});
return this.transformSession(session);
}
@Post(':sessionId/force-kill')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Force-kill a stuck session (SIGKILL its wedged engine, then tear it down)' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Session force-killed',
type: SessionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session is not started' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 502,
description:
'Session was stopped locally, but the engine force-kill did not complete (the force-destroy ' +
'threw or timed out, so the engine process may still be running). The body carries ' +
"`code: 'SESSION_FORCE_KILL_INCOMPLETE'`; the status is settled to `disconnected` and no " +
'success audit is written. Restart the node to reap a leaked process.',
})
async forceKill(@Param('sessionId', ParseUUIDPipe) id: string): Promise<SessionResponseDto> {
const session = await this.sessionService.forceKill(id);
await this.auditService.logInfo(AuditAction.SESSION_FORCE_KILLED, {
sessionId: session.id,
sessionName: session.name,
});
return this.transformSession(session);
}
@Get(':sessionId/qr')
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({ summary: 'Get QR code for session authentication' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'QR code data',
type: QRCodeResponseDto,
})
@ApiResponse({
status: 400,
description: 'QR code not ready or session already authenticated',
})
@ApiResponse({ status: 404, description: 'Session not found' })
async getQRCode(@Param('sessionId', ParseUUIDPipe) id: string): Promise<QRCodeResponseDto> {
const qrCode = await this.sessionService.getQRCode(id);
await this.auditService.logInfo(AuditAction.SESSION_QR_GENERATED, {
sessionId: id,
});
return qrCode;
}
@Post(':sessionId/pairing-code')
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({
summary: 'Request an 8-char pairing code to link via phone number (alternative to QR)',
description:
'On the whatsapp-web.js engine, only request a code for a number you are prepared to re-link. A request ' +
'for a number that already has a linked session has been observed to end with WhatsApp revoking that ' +
'device: the linked session logs out, its credentials are deleted and it falls back to `qr_ready`. ' +
'On that engine a number that is the stored phone of another session of this gateway (the Brazilian, ' +
'Mexican and Argentine mobile spellings of one number count as the same) is refused with `409` and WhatsApp ' +
'is not asked; the gateway cannot see a link made on another gateway or only on the phone. ' +
'Baileys was not affected in the same tests and accepts the request: its sessions are companion devices ' +
'and may share a number. Link by QR when a session of that number must stay up.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({ status: 201, description: 'Pairing code generated', type: PairingCodeResponseDto })
@ApiResponse({ status: 400, description: 'Session not started or already authenticated' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 409,
description:
PAIRING_NOT_READY_409 +
' On whatsapp-web.js also answered, with nothing sent to WhatsApp, when the requested number is the stored ' +
'phone of another session of this gateway: delete that session, or log it out while it runs, first.',
})
@ApiResponse({ status: 503, description: PAIRING_TRANSPORT_503 })
async requestPairingCode(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: RequestPairingCodeDto,
): Promise<PairingCodeResponseDto> {
return this.sessionService.requestPairingCode(id, dto.phoneNumber);
}
// Shares a Path Item with GroupController's POST on the same route — one parameter name for the
// one positional segment, or the contract splits it into two entries.
@ChatScoped('filtered')
@Get(':sessionId/groups')
@ApiOperation({ summary: 'Get all groups for a session' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'List of groups the session is a member of',
type: [SessionGroupSummaryDto],
})
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer the group-list query. Deliberately not reported as an empty list — ' +
'the engine returns the same empty value for "you are in no groups", and a caller cannot tell ' +
'those apart from the body. On Baileys, also answered when WhatsApp rate-limits or times out the ' +
'request (code 429 or 408); retry after a pause.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiQuery({ name: 'limit', required: false, description: 'Max groups to return (1–1000, default 1000)' })
@ApiQuery({ name: 'offset', required: false, description: 'Number of groups to skip (for paging)' })
async getGroups(
@Param('sessionId', ParseUUIDPipe) id: string,
@CurrentApiKey() apiKey?: ApiKey,
@Query('limit') limit?: string,
@Query('offset') offset?: string,
): Promise<{ id: string; name: string; linkedParentJID?: string | null }[]> {
// Filtered before paging, as getChats is, so a chat-restricted key sees only its groups and
// never a short window while an allowed group sat just past it.
const visible = await this.chatScope.filter(apiKey, await this.sessionService.listGroups(id), g => g.id);
return paginate(visible, limit ? parseInt(limit, 10) : undefined, offset ? parseInt(offset, 10) : undefined);
}
@ChatScoped('filtered')
@Get(':sessionId/chats')
@ApiOperation({ summary: 'Get active chats for a session' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({ status: 200, description: 'List of active chats (most recent first)', type: [ChatSummaryDto] })
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({
status: 503,
description:
'The whatsapp-web.js page connection died mid-read, or WhatsApp Web did not answer within the ' +
'protocol timeout, so nothing could be read. Deliberately not reported as an empty list: a page ' +
'that went away says nothing about the chats.',
})
@ApiQuery({ name: 'limit', required: false, description: 'Max chats to return (1–1000, default 1000)' })
@ApiQuery({ name: 'offset', required: false, description: 'Number of chats to skip (for paging)' })
async getChats(
@Param('sessionId', ParseUUIDPipe) id: string,
@CurrentApiKey() apiKey?: ApiKey,
@Query('limit') limit?: string,
@Query('offset') offset?: string,
): Promise<ChatSummary[]> {
// This route is admitted to a chat-restricted key because it FILTERS to the key's chats rather
// than naming one in the path. Filter BEFORE paginating: filtering the page instead would give a
// restricted key a short or empty window while an allowed chat sat just past it.
const skip = offset ? parseInt(offset, 10) : undefined;
const visible = await this.chatScope.filter(apiKey, await this.sessionService.listChats(id, skip), chat => chat.id);
return paginate(visible, limit ? parseInt(limit, 10) : undefined, skip);
}
@ChatScoped('fenced')
@Post(':sessionId/chats/read')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Mark a chat as read/seen' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Returns `{ success }`. `false` means the engine declined to act: the Baileys engine sends the ' +
'read receipt against the newest message the chat received that it holds in memory, else the ' +
'newest received one the gateway stored, so a chat with neither (one holding only the ' +
"account's own sends included) is reported as declined rather than marked read. The " +
'whatsapp-web.js engine reads the chat from the page and needs no local history.',
type: SessionActionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async markChatRead(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: MarkChatReadDto,
): Promise<{ success: boolean }> {
const success = await this.sessionService.sendSeen(id, dto.chatId, dto.messageIds);
return { success };
}
@ChatScoped('fenced')
@Post(':sessionId/presence/subscribe')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({
summary: "Subscribe to a chat's presence",
description:
'Asks WhatsApp to start reporting who is online or typing in this chat. Updates arrive as the ' +
'`presence.update` webhook and socket event — there is no synchronous answer, because presence ' +
'cannot be queried from either engine, only received.\n\n' +
'The subscription belongs to the connection: it does **not** survive a restart or an automatic ' +
'reconnect, and must be re-issued. Subscribe per chat rather than to everything — WhatsApp emits ' +
'an update on every transition, so a broad subscription is a firehose.\n\n' +
'whatsapp-web.js cannot do this at all (it exposes no presence subscribe and emits no presence ' +
'event) and answers `501`.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description: 'Subscribed; updates now arrive as presence.update events',
type: SessionActionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session not started' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({ status: 501, description: 'The active engine cannot observe presence (whatsapp-web.js)' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 503, description: RECIPIENT_LOOKUP_503 })
async subscribeToPresence(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: SubscribePresenceDto,
): Promise<{ success: boolean }> {
await this.sessionService.subscribeToPresence(id, dto.chatId);
return { success: true };
}
@Put(':sessionId/presence')
@RequireRole(ApiKeyRole.OPERATOR)
@ApiOperation({
summary: "Set the account's own global presence (appear online or offline)",
description:
'Publishes whether this account appears online. WhatsApp routes notifications away from the ' +
'phone while a linked device announces itself online, so a headless bot that never goes ' +
"offline suppresses the phone's own alerts — set `available: false` to hand them back.\n\n" +
'A successful call is remembered for the life of the running engine and re-applied once each ' +
'time that connection opens, including a Baileys transient reconnect: the socket announces ' +
'itself on connect (`available` unless `BAILEYS_MARK_ONLINE_ON_CONNECT=false`), which would ' +
"otherwise replace the caller's choice. The preference is dropped whenever the gateway replaces " +
'the engine: stop, restart, reconnect recovery, a watchdog recycle, or a takeover by another ' +
'node. Re-issue it after `session.status` reports `ready` again. On Baileys, typing, recording ' +
'and outbound sends do not publish global presence.\n\n' +
'On Baileys the call fails with 409 when the account push name has not synced yet — the ' +
'library would otherwise accept the request and send nothing. Supported on both engines.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({ status: 200, description: 'Presence published', type: SessionActionResponseDto })
@ApiResponse({ status: 400, description: 'Session not started, or validation failed' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 409,
description:
ENGINE_NOT_READY_409 +
' On Baileys this route also answers `409` for a `ready` session whose account push name has ' +
'not synced yet. Nothing was sent, and a retry succeeds only once the name has synced.',
})
@ApiResponse({
status: 503,
description:
'The whatsapp-web.js page connection died, or WhatsApp Web did not answer within the protocol ' +
'timeout. Nothing was confirmed; setting presence converges when repeated, so a retry is safe.',
})
async setOnlinePresence(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: SetOwnPresenceDto,
): Promise<{ success: boolean }> {
await this.sessionService.setOnlinePresence(id, dto.available);
return { success: true };
}
@ChatScoped('fenced')
@Get(':sessionId/presence/:chatId')
@RequireRole(ApiKeyRole.VIEWER)
@ApiOperation({
summary: "Read a chat's last reported presence",
description:
'Serves the most recent report received since the chat was subscribed. Returns `null` when ' +
'nothing has been reported — either the chat was never subscribed, or nothing has changed ' +
'since. That is a normal state, not a missing resource, so it is `200` with a null body rather ' +
'than a `404`.\n\n' +
'Held in memory and never persisted: presence is short-lived, and answering "typing" from ' +
'before a restart would be worse than answering nothing.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiParam({ name: 'chatId', description: 'Chat ID as subscribed' })
@ApiExtraModels(ChatPresenceResponseDto)
@ApiResponse({
status: 200,
description: 'Last reported presence, or null',
schema: { nullable: true, allOf: [{ $ref: getSchemaPath(ChatPresenceResponseDto) }] },
})
@ApiResponse({ status: 400, description: 'The session id is not a UUID' })
@ApiResponse({ status: 404, description: 'Session not found' })
async getPresence(
@Param('sessionId', ParseUUIDPipe) id: string,
@Param('chatId') chatId: string,
@Res() res: Response,
): Promise<void> {
const presence = await this.sessionService.getPresence(id, chatId);
const body: ChatPresenceResponseDto | null = presence
? { ...presence, observedAt: new Date(presence.observedAt) }
: null;
// Written directly: Nest answers a returned null with an empty body, not the JSON `null` above.
res.json(body);
}
@ChatScoped('fenced')
@Post(':sessionId/chats/unread')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Mark a chat as unread' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Returns `{ success }`. `false` means the engine declined to act. The Baileys engine keys the mark ' +
"to the chat's newest message in memory, else the newest stored one, else sends it without one for a " +
'chat the session knows; an id it knows no chat for answers `false`, and so does an archived chat ' +
'with no known message, which the phone leaves unmarked without one.',
type: SessionActionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async markChatUnread(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: MarkChatUnreadDto,
): Promise<{ success: boolean }> {
const success = await this.sessionService.markUnread(id, dto.chatId);
return { success };
}
@ChatScoped('fenced')
@Delete(':sessionId/chats/:chatId/messages')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({
summary: 'Delete every message in a chat, keeping the chat itself',
description:
"On success the gateway also removes its stored copies of the chat's messages (rows, inline and archived " +
'media, search entries) and emits `message:deleted` for each. Changes made on the phone are not mirrored.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiParam({ name: 'chatId', description: "Chat JID, e.g. [email protected] (URL-encode the '@')" })
@ApiResponse({
status: 200,
description:
'Returns `{ success }`. `false` means the engine declined to act — an unknown chat, or on the ' +
'Baileys engine a chat with no message in memory or stored, since the clear is keyed to its ' +
'last message.',
type: SessionActionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async clearChatMessages(
@Param('sessionId', ParseUUIDPipe) id: string,
@Param('chatId') chatId: string,
): Promise<{ success: boolean }> {
const success = await this.sessionService.clearChatMessages(id, chatId);
return { success };
}
@ChatScoped('fenced')
@Post(':sessionId/chats/archive')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Archive or unarchive a chat' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Returns `{ success }`. `false` means the engine declined to act. The Baileys engine keys the ' +
"change to the chat's newest message in memory, else the newest stored one, else sends it " +
'without one, which WhatsApp applies as well, for a chat the session knows; an id it knows no ' +
'chat for answers `false`.',
type: SessionActionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async archiveChat(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: ArchiveChatDto,
): Promise<{ success: boolean }> {
const success = await this.sessionService.archiveChat(id, dto.chatId, dto.archive);
return { success };
}
@ChatScoped('fenced')
@Post(':sessionId/chats/mute')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Mute or unmute a chat' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Returns `{ success: true }`. Unlike the archive route there is no declined outcome: the mute ' +
"change is not keyed to the chat's last message on either engine, so a chat with no known " +
'history mutes like any other.',
type: SessionActionResponseDto,
})
@ApiResponse({
status: 400,
description:
'Session not ready, an invalid chatId / muteUntil, or a chatId the whatsapp-web.js engine ' +
'cannot resolve. The Baileys engine writes the mute without resolving the chat first and ' +
'answers `success: true` for a chat that does not exist.',
})
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async muteChat(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: MuteChatDto,
): Promise<{ success: boolean }> {
await this.sessionService.muteChat(id, dto.chatId, dto.muteUntil);
return { success: true };
}
@ChatScoped('fenced')
@Post(':sessionId/chats/pin')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Pin or unpin a chat at the top of the chat list' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Returns `{ success }`. `false` means the engine declined, and only a pin can: WhatsApp allows ' +
'at most three pinned chats and the whatsapp-web.js engine reports the refusal. Unpinning always ' +
'succeeds, and the Baileys engine always reports success because it cannot observe the cap.',
type: SessionActionResponseDto,
})
@ApiResponse({
status: 400,
description:
'Session not ready, or a chatId the session cannot resolve. An unknown chat is reported here ' +
'rather than as `success: false`, which on this route means only that the three-pin cap ' +
'refused a real chat. The Baileys engine cannot resolve chats ahead of the write and answers ' +
'`success: true` for an unknown chat.',
})
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async pinChat(@Param('sessionId', ParseUUIDPipe) id: string, @Body() dto: PinChatDto): Promise<{ success: boolean }> {
const success = await this.sessionService.pinChat(id, dto.chatId, dto.pin);
return { success };
}
@ChatScoped('fenced')
@Post(':sessionId/chats/delete')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({
summary: 'Delete a chat from the chat list (e.g. a group you have left)',
description:
"On success the gateway also removes its stored copies of the chat's messages (rows, inline and archived " +
'media, search entries) and emits `message:deleted` for each. Changes made on the phone are not mirrored.',
})
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({
status: 200,
description:
'Returns `{ success }`. `false` means the engine declined to act: an unknown chat, or on the ' +
'Baileys engine a chat with no message in memory or stored, since the delete is keyed to its ' +
'last message.',
type: SessionActionResponseDto,
})
@ApiResponse({ status: 400, description: 'Session not ready' })
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({
status: 503,
description:
'WhatsApp did not answer within the request budget. The change may or may not have been applied — ' +
'the gateway stopped waiting for a confirmation that never came.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async deleteChat(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: DeleteChatDto,
): Promise<{ success: boolean }> {
const success = await this.sessionService.deleteChat(id, dto.chatId);
return { success };
}
@ChatScoped('fenced')
@Post(':sessionId/chats/typing')
@RequireRole(ApiKeyRole.OPERATOR)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: "Send a typing/recording presence indicator to a chat (or clear it with 'paused')" })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
@ApiResponse({ status: 200, description: 'Presence sent', type: SessionActionResponseDto })
@ApiResponse({
status: 400,
description:
'Session is not started, or validation failed (an empty chatId, a state other than typing, ' +
'recording or paused, or a body field the DTO does not declare).',
})
@ApiResponse({ status: 404, description: 'Session not found' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
async sendChatState(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: SendChatStateDto,
): Promise<{ success: boolean }> {
await this.sessionService.sendChatState(id, dto.chatId, dto.state);
return { success: true };
}
@Get('stats/overview')
@ApiOperation({
summary: 'Get session statistics for multi-session monitoring',
})
@ApiResponse({
status: 200,
description: 'Session statistics including counts and memory usage',
type: SessionsOverviewResponseDto,
})
async getStats(@CurrentApiKey() apiKey?: ApiKey): Promise<{
total: number;
active: number;
ready: number;
disconnected: number;
byStatus: Record<string, number>;
memoryUsage: { heapUsed: number; heapTotal: number; rss: number };
}> {
// Scope aggregate stats to the key's allowedSessions so a session-restricted key cannot enumerate
// global session counts/status (the route carries no :sessionId for the guard to scope against).
return this.sessionService.getStats(apiKey?.allowedSessions);
}
}