rmyndharis--openwa/docs/06-api-specification.md

06 - API Specification

6.1 API Overview

Base URL

Every REST route is mounted under the global api prefix:

http://<host>:2785/api

For local development that is http://localhost:2785/api; behind a reverse proxy substitute your public origin (the /api prefix is unchanged).

Authentication

A global API-key guard protects every route unless it is explicitly marked public (@Public()). Send the key in the X-API-Key header:

X-API-Key: owa_k1_your-api-key-here

Auth is header-only (never in a URL). A query-parameter API key is not accepted anywhere. REST routes take the key via the X-API-Key header; the WebSocket (Socket.IO) handshake — see §6.5 Real-time API — accepts it via the handshake auth.apiKey field or the X-API-Key header. The former ?apiKey= query fallback was removed (it leaked the credential into proxy/access logs). Never put the key in a URL.

The metrics endpoint is the lone exception to the API-key scheme: it authenticates with Authorization: Bearer <METRICS_TOKEN> instead of X-API-Key.

Common Headers

X-API-Key: owa_k1_your-api-key      # required on every non-public REST route
Content-Type: application/json       # required on requests with a JSON body

Content-Type: application/json is only needed when sending a body. There is no required Accept or X-Request-ID header.

Roles & Authorization

API keys carry one of three roles, ordered by privilege:

Role	Rank	Can do
viewer	1	Read-only routes (no @RequireRole, or routes that only need a valid key)
operator	2	Everything a viewer can, plus write/action routes guarded by @RequireRole(OPERATOR) (send messages, group/contact mutations, etc.)
admin	3	Everything, plus admin-only routes guarded by @RequireRole(ADMIN) (API-key management, settings)

@RequireRole(role) enforces a minimum role using the hierarchy VIEWER < OPERATOR < ADMIN: a key satisfies the guard if its own rank is ≥ the required rank (so an admin key passes an OPERATOR-guarded route). A route with no @RequireRole accepts any valid key, including viewer. A key whose role is below the requirement gets 403 Forbidden; a missing or invalid key gets 401 Unauthorized.

A key may additionally be scoped to specific sessions (allowedSessions) and/or source IPs (allowedIps). The scope/IP check runs in the guard before any role check, so a request outside that scope is rejected with 401 (not 403) even if the role would otherwise allow it.

API-Key Lifecycle

OpenWA seeds an initial admin key on first run (printed to the startup log and written to data/.api-key, or /app/data/.api-key in Docker). Use it to mint scoped, lower-privilege keys for integrations. Full key creation, listing, rotation, and revocation are documented under the auth resource in §6.4.9 (API Keys).

6.2 Response Format

OpenWA returns the raw handler payload directly — there is NO { success, data, meta } envelope. A resource route returns the resource object as-is; a list route returns a bare JSON array. Read fields directly (response.id, not response.data.id).

Success Response

A successful request returns the resource (or array) exactly as the handler produced it:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-session",
  "status": "ready"
}

List endpoints return a bare array (some paginated list routes instead return a small wrapper such as { "messages": [...], "total": 42 } — the per-endpoint docs state the exact shape):

[
  { "id": "…", "name": "session-a" },
  { "id": "…", "name": "session-b" }
]

Session status wire values are lowercase: created | initializing | qr_ready | authenticating | ready | disconnected | failed.

Error Response

Errors use the NestJS default shape. The HTTP status is on the status line and mirrored in statusCode; there is no application-specific code field:

{
  "statusCode": 404,
  "message": "Session 'my-session' not found",
  "error": "Not Found"
}

Validation failures (statusCode: 400) return message as an array of field-level strings. A global ValidationPipe runs with whitelist + forbidNonWhitelisted, so any request-body field not declared on the DTO is rejected with 400.

General Error Codes

HTTP Status	Meaning	When
400	Bad Request	DTO validation failed, unknown body field, or a business precondition not met (e.g. session not active, media over cap)
401	Unauthorized	Missing/invalid/expired/revoked X-API-Key (or METRICS_TOKEN for metrics), a blocked source IP, or a key used outside its allowedSessions scope
403	Forbidden	A valid, in-scope key whose role is below the route's @RequireRole requirement
404	Not Found	The addressed resource (session, message, webhook, batch, …) does not exist
409	Conflict	A uniqueness constraint was violated (e.g. duplicate name)
413	Payload Too Large	Base64 media exceeds the media byte cap (see §6.3)
500	Internal Server Error	Send failed at the WhatsApp engine or an unexpected server error

Timestamp Conventions

OpenWA uses two timestamp representations — be careful which a field is:

• Message timestamps are epoch numbers (Unix seconds), not ISO strings. This applies to the timestamp field on messages returned by send responses, history, and persisted message records (the persisted column is stored as a bigint and surfaced as a number).
• Entity audit fields use ISO-8601 UTC strings (example: 2026-02-02T10:00:00.000Z). This applies to createdAt / updatedAt on persisted entities, expiresAt, batch startedAt / completedAt, and similar metadata fields.

6.3 Media Specifications

Media DTO (flat shape)

All media send routes (send-image, send-video, send-audio, send-document, send-sticker) share one flat request DTO — SendMediaMessageDto. There is no nested { image: { url } } wrapper; the media source fields sit at the top level of the body:

Field	Type	Required	Constraints	Description
chatId	string	yes	non-empty	Recipient — <phone>@c.us or <groupId>@g.us
url	string	conditional	valid http/https URL; required when base64 absent	Remote media URL. Fetched server-side through an SSRF guard; a blocked/internal URL yields 400
base64	string	conditional	required when url absent	Raw base64 media data. Decoded size is checked against the media cap
mimetype	string	conditional	required when base64 is used	MIME type, e.g. image/jpeg, video/mp4, application/pdf
filename	string	no	max 255 chars	Optional file name (also used as the persisted body fallback for documents)
caption	string	no	max 1024 chars	Optional caption (not persisted for audio)
mentions	string[]	no	array of WIDs	WIDs to @mention in the caption (e.g. ["62811@c.us"]). See Mentions below

Provide exactly one of url or base64. Omitting both, or supplying base64 without mimetype, returns 400.

{
  "chatId": "6281234567890@c.us",
  "url": "https://example.com/image.jpg",
  "caption": "Check out this image!"
}

{
  "chatId": "6281234567890@c.us",
  "base64": "/9j/4AAQSkZJRg...",
  "mimetype": "image/jpeg",
  "filename": "photo.jpg"
}

Size Limit

There is a single shared media byte cap, not a per-type table. A base64 (or downloaded) media blob whose decoded size exceeds the cap is rejected with 413 Payload Too Large. The cap is MEDIA_DOWNLOAD_MAX_BYTES, default 50 MiB (52,428,800 bytes); the same value bounds outbound base64 sends, remote-URL downloads, and inbound media. A non-positive or garbage override falls back to the default.

Text Limit

send-text enforces a maximum body length of 4096 characters (text is @MaxLength(4096)). Media captions are limited to 1024 characters.

Mentions

send-text and the media send routes accept an optional mentions array of WIDs (<phone>@c.us) to tag participants — most useful in groups. Two things are required for WhatsApp to render a tag and notify the participant:

1. The mentions array lists the WID(s), e.g. ["62811@c.us"].
2. The text/caption contains the matching @<number> token, e.g. Hello @62811.

The contract is engine-neutral: pass neutral @c.us WIDs and the active engine (whatsapp-web.js or Baileys) de-normalizes them internally. Whether a mention surfaces a notification is ultimately client-side — outside a shared group some clients may not render it.

6.4 REST API Reference

Every path below is prefixed with /api. Unless marked public, send X-API-Key: <key>; OPERATOR/ADMIN annotations require a key of at least that role. Responses are the raw payload (no envelope); list endpoints return a bare array.

6.4.1 Sessions

Base path /api/sessions. Read routes return data shaped by SessionResponseDto.fromEntity (via transformSession), which strips config, proxyUrl, and proxyType and renames the entity field lastActiveAt to lastActive. The one exception is POST /api/sessions, which returns the raw Session entity and therefore does expose config/proxyUrl/proxyType/lastActiveAt. Session status wire values are lowercase: created | initializing | qr_ready | authenticating | ready | disconnected | failed.

GET /api/sessions

List all sessions, scoped to the API key's allowedSessions, ordered createdAt DESC.

Auth: API key · Scope: session-scoped (a scoped key sees only its allowedSessions; an ADMIN / null-allowlist key lists all)

Query parameters

Name	Type	Required	Default	Description
limit	integer (1-1000)	No	1000	Max sessions to return; oversized/non-finite values are clamped/fallback to the default window.
offset	integer	No	0	Sessions to skip for paging; negative/non-finite values resolve to 0.

Response 200

[
  {
    "id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
    "name": "my-bot",
    "status": "ready",
    "phone": "6281234567890",
    "pushName": "My Bot",
    "connectedAt": "2026-06-25T08:14:02.000Z",
    "lastActive": "2026-06-25T09:01:55.000Z",
    "createdAt": "2026-06-20T11:30:00.000Z",
    "updatedAt": "2026-06-25T09:01:55.000Z",
    "lastError": null
  }
]

lastError is non-null only when status is failed. config/proxyUrl/proxyType are not present (stripped by fromEntity).

Errors: 401 missing/invalid X-API-Key

GET /api/sessions/:id

Get a single session by ID.

Auth: API key · Scope: session-scoped (key's allowedSessions enforced against :id)

Path parameters

Name	Type	Description
id	string	WhatsApp session UUID

Response 200

{
  "id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
  "name": "my-bot",
  "status": "ready",
  "phone": "6281234567890",
  "pushName": "My Bot",
  "connectedAt": "2026-06-25T08:14:02.000Z",
  "lastActive": "2026-06-25T09:01:55.000Z",
  "createdAt": "2026-06-20T11:30:00.000Z",
  "updatedAt": "2026-06-25T09:01:55.000Z",
  "lastError": null
}

Errors: 401 missing/invalid key, or key not scoped to this session · 404 session not found

GET /api/sessions/:id/qr

Get the QR code (PNG data URL) for session authentication.

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Response 200 — QRCodeResponseDto

{
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "status": "qr_ready"
}

status is the session's current lowercase status.

Errors: 400 session not started / QR not ready yet / already authenticated · 401 · 403 · 404 not found

GET /api/sessions/:id/groups

Get all groups the session is a member of (paginated).

Auth: API key · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Query parameters

Name	Type	Required	Default	Description
limit	integer (1–1000)	No	1000	Max groups to return
offset	integer	No	0	Number of groups to skip for paging

Response 200

[
  { "id": "1234567890-123@g.us", "name": "Project Team", "linkedParentJID": null }
]

Bare array mapped from the engine's group list then paginated. linkedParentJID is present for community-linked groups.

Errors: 400 session not started (engine not in memory) · 401 · 403 · 404 session not found

GET /api/sessions/:id/chats

Get active chats for a session, most-recent first (paginated).

Auth: API key · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Query parameters

Name	Type	Required	Default	Description
limit	integer (1–1000)	No	1000	Max chats to return
offset	integer	No	0	Chats to skip for paging

Response 200 — ChatSummary[]

[
  {
    "id": "6281234567890@c.us",
    "name": "Alice",
    "isGroup": false,
    "unreadCount": 2,
    "timestamp": 1719306115,
    "lastMessage": "See you tomorrow"
  }
]

Sorted by timestamp DESC (most recent first) then paginated. timestamp is an epoch number (seconds).

Errors: 400 session not started · 401 · 403 · 404 session not found

GET /api/sessions/stats/overview

Get session statistics for multi-session monitoring.

Auth: API key · Scope: session-scoped (aggregate counts limited to the key's allowedSessions)

Response 200

{
  "total": 4,
  "active": 2,
  "ready": 2,
  "disconnected": 1,
  "byStatus": { "ready": 2, "disconnected": 1, "created": 1 },
  "memoryUsage": { "heapUsed": 142, "heapTotal": 210, "rss": 318 }
}

byStatus is keyed by lowercase status values. memoryUsage values are megabytes (Math.round(bytes / 1024 / 1024)). active = count of running engines. A scoped key sees only its allowedSessions stats.

Errors: 401 missing/invalid X-API-Key

POST /api/sessions

Create a new WhatsApp session.

Auth: API key (OPERATOR)

Request body — CreateSessionDto

Field	Type	Required	Constraints	Description
name	string	Yes	@IsString; length 3–50; @Matches(/^[a-zA-Z0-9-]+$/) (letters, numbers, hyphens only)	Unique session name; duplicate → 409
config	object	No	@IsOptional (arbitrary object, no shape validation)	Opaque engine config; defaults to {}; never returned by read routes
proxyUrl	string	No	@IsOptional; @IsString; max 255; @IsUrl (protocols http/https/socks4/socks5, require_protocol, require_tld:false, allow_underscores)	Per-session proxy egress; credentialed http://user:pass@host and single-label hosts allowed; not SSRF-blocked
proxyType	http | https | socks4 | socks5	No	@IsOptional; @IsIn([...])	Proxy protocol

{
  "name": "my-bot",
  "config": { "autoReconnect": true },
  "proxyUrl": "http://proxy.example.com:8080",
  "proxyType": "http"
}

Minimal: { "name": "my-bot" }.

Response 201

{
  "id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
  "name": "my-bot",
  "status": "created",
  "phone": null,
  "pushName": null,
  "config": { "autoReconnect": true },
  "proxyUrl": "http://proxy.example.com:8080",
  "proxyType": "http",
  "connectedAt": null,
  "lastActiveAt": null,
  "createdAt": "2026-06-25T09:00:00.000Z",
  "updatedAt": "2026-06-25T09:00:00.000Z"
}

This route returns the raw Session entity (not via fromEntity), so config/proxyUrl/proxyType/lastActiveAt are present here only. Newly created status is created.

Errors: 400 validation (bad name/proxyUrl/proxyType, or an extra non-whitelisted field) · 401 · 403 key lacks OPERATOR role · 409 session name already exists

POST /api/sessions/:id/start

Start a session and initialize the WhatsApp connection.

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

No request body.

Response 201

{
  "id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
  "name": "my-bot",
  "status": "initializing",
  "phone": null,
  "pushName": null,
  "connectedAt": null,
  "lastActive": null,
  "createdAt": "2026-06-20T11:30:00.000Z",
  "updatedAt": "2026-06-25T09:05:00.000Z",
  "lastError": null
}

Returned via transformSession. Status typically transitions to initializing / qr_ready. Note: Swagger declares 200, but with no @HttpCode override the runtime status is 201 (NestJS POST default).

Errors: 400 session already started / already starting · 401 · 403 · 404 not found

POST /api/sessions/:id/stop

Stop a session and disconnect WhatsApp.

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

No request body.

Response 201

{
  "id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
  "name": "my-bot",
  "status": "disconnected",
  "phone": "6281234567890",
  "pushName": "My Bot",
  "connectedAt": null,
  "lastActive": "2026-06-25T09:01:55.000Z",
  "createdAt": "2026-06-20T11:30:00.000Z",
  "updatedAt": "2026-06-25T09:10:00.000Z",
  "lastError": null
}

Returned via transformSession; status typically becomes disconnected. Swagger declares 200; runtime status is 201.

Errors: 401 · 403 · 404 not found

POST /api/sessions/:id/force-kill

Force-kill a stuck session (SIGKILL the wedged engine, then tear it down).

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

No request body.

Response 201

{
  "id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
  "name": "my-bot",
  "status": "disconnected",
  "phone": "6281234567890",
  "pushName": "My Bot",
  "connectedAt": null,
  "lastActive": "2026-06-25T09:01:55.000Z",
  "createdAt": "2026-06-20T11:30:00.000Z",
  "updatedAt": "2026-06-25T09:12:00.000Z",
  "lastError": null
}

Returned via transformSession. Swagger declares 200; runtime status is 201.

Errors: 401 · 403 · 404 not found

POST /api/sessions/:id/pairing-code

Request an 8-char pairing code to link via phone number (alternative to QR).

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Request body — RequestPairingCodeDto

Field	Type	Required	Constraints	Description
phoneNumber	string	Yes	@IsString; @IsNotEmpty; @Matches(/^[0-9]{6,15}$/) (digits only, 6–15, no +/spaces/dashes)	International format: country code + number, e.g. 628123456789

{ "phoneNumber": "628123456789" }

Response 201 — PairingCodeResponseDto

{ "pairingCode": "ABCD1234", "status": "qr_ready" }

status is the lowercase session status.

Errors: 400 validation, or session not started, or already authenticated · 401 · 403 · 404 not found

POST /api/sessions/:id/chats/read

Mark a chat as read/seen.

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Request body — MarkChatReadDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	@IsString; @IsNotEmpty; @Matches(/^[^\s@]+@[^\s@]+$/) (localpart@host, no whitespace)	Engine-native JID, e.g. 1234567890@c.us (wwebjs) or 1234@s.whatsapp.net (Baileys)

{ "chatId": "1234567890@c.us" }

Response 201

{ "success": true }

Swagger declares 200; runtime status is 201.

Errors: 400 validation, or session not started · 401 · 403 · 404 session not found

POST /api/sessions/:id/chats/unread

Mark a chat as unread.

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Request body — MarkChatReadDto (reused)

Field	Type	Required	Constraints	Description
chatId	string	Yes	@IsString; @IsNotEmpty; @Matches(/^[^\s@]+@[^\s@]+$/)	Engine-native JID, e.g. 1234567890@c.us

{ "chatId": "1234567890@c.us" }

Response 201

{ "success": true }

Swagger declares 200; runtime status is 201.

Errors: 400 validation, or session not started · 401 · 403 · 404 session not found

POST /api/sessions/:id/chats/delete

Delete a chat from the chat list (e.g. a group you have left).

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Request body — DeleteChatDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	@IsString; @IsNotEmpty; @Matches(/^[^\s@]+@[^\s@]+$/) (localpart@host, no whitespace)	Engine-native JID, e.g. 1234567890-123@g.us

{ "chatId": "1234567890-123@g.us" }

Response 201

{ "success": true }

Swagger declares 200; runtime status is 201.

Errors: 400 validation, or session not started · 401 · 403 · 404 session not found

POST /api/sessions/:id/chats/typing

Send a typing/recording presence indicator to a chat (or clear it with paused).

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Request body — SendChatStateDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	@IsString; @IsNotEmpty (no JID regex; engine-neutral, the adapter validates)	Engine-native chat id, e.g. 1234567890@c.us
state	typing | recording | paused	Yes	@IsIn(['typing','recording','paused'])	typing/recording show the indicator; paused clears it

{ "chatId": "1234567890@c.us", "state": "typing" }

Response 201

{ "success": true }

Always returns { "success": true } (the service returns void; the controller hardcodes true). Swagger declares 200; runtime status is 201.

Errors: 400 validation, or session not started · 401 · 403 · 404 session not found

DELETE /api/sessions/:id

Delete a session.

Auth: API key (OPERATOR) · Scope: session-scoped

Path parameters

Name	Type	Description
id	string	Session UUID

Response 204 — empty body (@HttpCode(204), returns void). A findOne lookup runs first, so a missing id yields 404.

Errors: 401 missing/invalid key, or key not scoped to this session · 403 key role below OPERATOR · 404 session not found

6.4.2 Messages

All routes are mounted under /api/sessions/:sessionId/messages. Reads (GET history, batch status, reactions) accept any valid API key (including VIEWER). All write/send routes require API key (OPERATOR) or higher. Send routes return MessageResponseDto { messageId, timestamp } (timestamp is an epoch number in seconds; there is no status field). The global ValidationPipe runs whitelist + forbidNonWhitelisted, so any body field not listed below is rejected with 400.

GET /api/sessions/:sessionId/messages

Get persisted message history for a session from the local DB (paginated, filterable). Reads the DB only — does not hit WhatsApp.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID

Query parameters

Name	Type	Required	Default	Description
chatId	string	No	—	Filter by chat ID. Matched across @c.us / @s.whatsapp.net dialects via the lid-mapping table.
from	string	No	—	Filter by sender. A phone also matches any lid that resolves to it.
limit	integer	No	50	Clamped to [1,100]; a non-finite value falls back to 50.
offset	integer	No	0	Clamped to >=0; a non-finite value falls back to 0.

Response 200

{
  "messages": [
    {
      "id": "9f1c2e7a-2b3d-4c5e-8a91-0d1e2f3a4b5c",
      "sessionId": "my-session",
      "waMessageId": "true_628123456789@c.us_3EB0ABCD",
      "chatId": "628123456789@c.us",
      "from": "628123456789@c.us",
      "to": "628987654321@c.us",
      "body": "Hello from OpenWA!",
      "type": "text",
      "direction": "outgoing",
      "timestamp": 1719312000,
      "metadata": null,
      "status": "sent",
      "createdAt": "2026-06-25T09:20:00.000Z"
    }
  ],
  "total": 1
}

Each Message: { id (uuid), sessionId, waMessageId (string|null), chatId, from, to, body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }. Ordered by createdAt DESC. The response is the raw service object (no envelope).

Errors: 401 missing/invalid API key

GET /api/sessions/:sessionId/messages/:chatId/history

Fetch chat history live from WhatsApp for a chat, bypassing the local DB.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
chatId	string	Chat ID, e.g. 628123456789@c.us or groupId@g.us

Query parameters

Name	Type	Required	Default	Description
limit	integer	No	50	Clamped to [1,100]; when deep=true the ceiling rises to 2000. Non-finite falls back to 50.
includeMedia	boolean	No	false	Truthy only for true or 1. Downloads base64 media (slower). Forced OFF when deep=true.
deep	boolean	No	false	Truthy only for true or 1. Raises the limit ceiling 100→2000 (whatsapp-web.js only) and forces metadata-only.

Response 200

Returns a bare array of engine-neutral IncomingMessage objects:

[
  {
    "id": "true_628123456789@c.us_3EB0ABCD",
    "from": "628123456789@c.us",
    "to": "628987654321@c.us",
    "chatId": "628123456789@c.us",
    "body": "Hi there",
    "type": "text",
    "timestamp": 1719312000,
    "fromMe": false,
    "isGroup": false,
    "author": "628123456789@c.us",
    "senderPhone": "628123456789"
  }
]

Each item may also include isStatusBroadcast, mentionedIds, isLidSender, contact, media { mimetype, filename?, data?, omitted?, sizeBytes? }, quotedMessage { id, body }, call { video, missed } (for call messages), and location { latitude, longitude, description?, address?, url? }. type is one of text|image|video|audio|voice|document|sticker|location|contact|call|revoked|masked|unknown. A masked message is one WhatsApp deliberately withholds from linked/companion devices — e.g. a high-security business OTP — so its body is empty by design (the content is only available on the primary phone) rather than a parsing failure; this occurs on the Baileys engine.

Errors: 400 session not active · 401 missing/invalid API key · 500 engine error

GET /api/sessions/:sessionId/messages/:chatId/:messageId/reactions

Get reactions for a specific message, grouped by emoji with the senders.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
chatId	string	Chat ID containing the message
messageId	string	Message ID to get reactions for

Response 200

Returns a bare array of MessageReaction:

[
  {
    "emoji": "👍",
    "senders": [
      { "senderId": "628123456789@c.us", "emoji": "👍", "timestamp": 1719312050 }
    ]
  }
]

Errors: 400 session not active · 401 missing/invalid API key · 500 engine error

GET /api/sessions/:sessionId/messages/batch/:batchId

Get the processing status and progress of a bulk batch.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
batchId	string	Batch ID

Response 200

{
  "batchId": "batch_a1b2c3d4",
  "status": "processing",
  "progress": { "total": 2, "sent": 1, "failed": 0, "pending": 1, "cancelled": 0 },
  "results": [
    {
      "chatId": "628111111111@c.us",
      "status": "sent",
      "messageId": "true_628111111111@c.us_3EB0ABCD",
      "sentAt": "2026-06-25T09:21:00.000Z"
    },
    { "chatId": "628222222222@c.us", "status": "pending" }
  ],
  "startedAt": "2026-06-25T09:20:55.000Z",
  "completedAt": null
}

status is one of pending|processing|completed|cancelled|failed; per-result status is pending|sent|failed|cancelled. A failed result carries a sanitized error { code, message } (internals are not leaked).

Errors: 401 missing/invalid API key · 404 batch not found for this session

POST /api/sessions/:sessionId/messages/send-text

Send a plain text message.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendTextMessageDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	phone@c.us or groupId@g.us
text	string	Yes	non-empty, max 4096	Message text
mentions	string[]	No	array of WIDs	WIDs to @mention (e.g. ["62811@c.us"]). See Mentions below

{ "chatId": "628123456789@c.us", "text": "Hello from OpenWA!" }

{ "chatId": "120363000000000000@g.us", "text": "Hello @62811", "mentions": ["62811@c.us"] }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

messageId is the WhatsApp message id from the engine. An optional SIMULATE_TYPING humanising pause may run before send.

Errors: 400 unknown body field, validation failure, or session not active / blocked by a plugin hook · 401 missing/invalid API key · 403 key role below OPERATOR · 404 session not found · 500 engine error

POST /api/sessions/:sessionId/messages/send-template

Render a stored text template (header/body/footer joined by blank lines, {{vars}} substituted) and send it as text.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendTemplateMessageDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
templateId	string	Conditional	non-empty; required when templateName is absent	Stored template id
templateName	string	Conditional	non-empty; required when templateId is absent	Stored template name
vars	Record<string,string>	No	object	Substituted into {{placeholder}} tokens; defaults to {}

{
  "chatId": "628123456789@c.us",
  "templateName": "order-confirmation",
  "vars": { "customer": "Alice", "orderId": "1234" }
}

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Delegates to the send-text path after rendering.

Errors: 400 unknown body field, validation failure, or session not active · 401 missing/invalid API key · 403 key role below OPERATOR · 404 session or template not found · 500 engine error

POST /api/sessions/:sessionId/messages/send-image

Send an image (by URL or base64) with an optional caption.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendMediaMessageDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
url	string	Conditional	URL; required when base64 is absent	http/https media URL (SSRF-guarded; a blocked internal URL maps to 400)
base64	string	Conditional	string; required when url is absent	Base64 media data (capped to the media byte limit)
mimetype	string	Conditional	string; required when using base64	MIME type of the media
filename	string	No	max 255	File name
caption	string	No	max 1024	Caption text

{ "chatId": "628123456789@c.us", "url": "https://example.com/image.jpg", "caption": "Check out this image!" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 neither url nor base64, base64 without mimetype, base64 over media cap, SSRF-blocked URL, session not active, or unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-video

Send a video (by URL or base64) with an optional caption. Uses the same SendMediaMessageDto (and the same validation rules and errors) as send-image.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendMediaMessageDto (fields chatId, url, base64, mimetype, filename, caption — see send-image)

{ "chatId": "628123456789@c.us", "url": "https://example.com/clip.mp4", "caption": "video" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 media validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-audio

Send an audio message (by URL or base64). Uses SendAudioMessageDto. A caption is accepted by the DTO but not persisted for audio. Set ptt: true to send a real WhatsApp voice note (microphone bubble + waveform) instead of a plain audio file. ptt is a JSON boolean, exclusive to this endpoint, and — because voice notes require audio/ogg; codecs=opus — the server defaults the mimetype to that when you set ptt without one; for reliable playback (especially on the Baileys engine, which does not transcode) supply OGG/Opus bytes. A ptt voice note is stored as message type: "voice".

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendAudioMessageDto (all SendMediaMessageDto fields — chatId, url, base64, mimetype, filename, caption — plus optional ptt boolean)

{ "chatId": "628123456789@c.us", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg", "ptt": true }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 media validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-document

Send a document/file (by URL or base64). Uses SendMediaMessageDto; filename is used as the persisted body fallback.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendMediaMessageDto (fields chatId, url, base64, mimetype, filename, caption — see send-image)

{ "chatId": "628123456789@c.us", "url": "https://example.com/report.pdf", "filename": "report.pdf", "mimetype": "application/pdf" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 media validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-location

Send a location pin.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendLocationDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
latitude	number	Yes	valid latitude	Latitude (out-of-range → 400)
longitude	number	Yes	valid longitude	Longitude (out-of-range → 400)
description	string	No	string	Pin description
address	string	No	string	Pin address

{ "chatId": "628123456789@c.us", "latitude": -6.2088, "longitude": 106.8456, "description": "Jakarta", "address": "Central Jakarta" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 invalid coords / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-contact

Send a contact card (vCard).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendContactDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
contactName	string	Yes	non-empty	Display name for the contact card
contactNumber	string	Yes	non-empty	Contact phone number

{ "chatId": "628123456789@c.us", "contactName": "John Doe", "contactNumber": "628987654321" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-sticker

Send a sticker (by URL or base64; typically webp). Reuses SendMediaMessageDto.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendMediaMessageDto (fields chatId, url, base64, mimetype, filename, caption — see send-image)

{ "chatId": "628123456789@c.us", "url": "https://example.com/sticker.webp", "mimetype": "image/webp" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 media validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-poll

Send a native WhatsApp poll.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendPollDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
name	string	Yes	max 255	Poll question / title
options	string[]	Yes	2–12 items, each non-empty, max 100 chars	Options to vote on
allowMultipleAnswers	boolean	No	—	Allow picking several options (default single choice)

{ "chatId": "1203630000@g.us", "name": "Where should we meet?", "options": ["Park", "Beach", "Downtown"], "allowMultipleAnswers": false }

Response 201

{ "messageId": "true_1203630000@g.us_3EB0ABCD", "timestamp": 1719312000 }

Errors: 400 validation failure (option count/length) / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/reply

Reply to a message, quoting a prior message.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — ReplyMessageDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
quotedMessageId	string	Yes	non-empty	WhatsApp id of the message being quoted
text	string	Yes	non-empty	Reply text

{ "chatId": "628123456789@c.us", "quotedMessageId": "true_628123456789@c.us_3EB0ABCD", "text": "Replying to you" }

Response 201

{ "messageId": "true_628123456789@c.us_3EB0EFGH", "timestamp": 1719312100 }

The quoted body is best-effort resolved from the DB for the reply preview.

Errors: 400 validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/forward

Forward a message from one chat to another.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — ForwardMessageDto

Field	Type	Required	Constraints	Description
fromChatId	string	Yes	non-empty	Source chat
toChatId	string	Yes	non-empty	Destination chat
messageId	string	Yes	non-empty	WhatsApp id of the message to forward

{ "fromChatId": "628111111111@c.us", "toChatId": "628222222222@c.us", "messageId": "true_628111111111@c.us_3EB0XYZ" }

Response 201

{ "messageId": "true_628222222222@c.us_3EB0NEW", "timestamp": 1719312200 }

messageId may be an empty string when the engine could not recover the forwarded copy's id.

Errors: 400 validation failure / session not active / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/react

Add or remove a reaction to a message (an empty emoji removes the reaction).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — ReactMessageDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
messageId	string	Yes	non-empty	Message to react to
emoji	string	Yes	string (may be empty)	Reaction emoji; an empty string removes the reaction. The field must be present.

{ "chatId": "628123456789@c.us", "messageId": "true_628123456789@c.us_3EB0ABCD", "emoji": "👍" }

Response 200

The controller hardcodes the result after the engine call. Note the 200 status (via @HttpCode), not 201.

{ "success": true }

Errors: 400 session not active / message not found / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/delete

Delete a message (for everyone by default); also flags the stored record as revoked.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — DeleteMessageDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	non-empty	Target chat
messageId	string	Yes	non-empty	Message to delete
forEveryone	boolean	No	boolean (default true)	Delete for everyone; defaults to true in the service

{ "chatId": "628123456789@c.us", "messageId": "true_628123456789@c.us_3EB0ABCD", "forEveryone": true }

Response 200

After the engine delete, the stored message body is cleared and its type set to revoked. Note the 200 status (via @HttpCode).

{ "success": true }

Errors: 400 session not active / message not found / unknown body field · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/send-bulk

Send messages to multiple recipients as an async batch — returns immediately and processes in the background.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — SendBulkMessageDto

Field	Type	Required	Constraints	Description
batchId	string	No	string	Auto-generated batch_<hex> if omitted; a duplicate id returns 400
messages	BulkMessageItemDto[]	Yes	array, max 100, nested-validated	The batch items (see below)
options	BulkMessageOptionsDto	No	nested-validated	Pacing/error options (see below)

Each BulkMessageItemDto: { chatId: string, type: 'text'|'image'|'video'|'audio'|'document', content: BulkMessageContentDto, variables?: Record<string,string> }. content (all fields optional, nested-validated): text?: string, image?/video?/audio?/document?: { url?, base64?, mimetype?, filename? }, caption?: string.

BulkMessageOptionsDto: { delayBetweenMessages?: number (1000–60000, default 3000), randomizeDelay?: boolean (default true), stopOnError?: boolean (default false) }.

{
  "messages": [
    { "chatId": "628111111111@c.us", "type": "text", "content": { "text": "Hi {{name}}" }, "variables": { "name": "Alice" } },
    { "chatId": "628222222222@c.us", "type": "image", "content": { "image": { "url": "https://example.com/promo.jpg" }, "caption": "Promo" } }
  ],
  "options": { "delayBetweenMessages": 3000, "randomizeDelay": true, "stopOnError": false }
}

Response 202

202 Accepted (via @HttpCode). statusUrl points at the batch-status route below.

{
  "batchId": "batch_a1b2c3d4",
  "status": "pending",
  "totalMessages": 2,
  "estimatedCompletionTime": "2026-06-25T09:21:00.000Z",
  "statusUrl": "/api/sessions/my-session/messages/batch/batch_a1b2c3d4"
}

Errors: 400 session not active, duplicate batchId, base64 over media cap, or DTO/nested validation failure (unknown nested field rejected) · 401 missing/invalid API key · 403 key role below OPERATOR · 500 engine error

POST /api/sessions/:sessionId/messages/batch/:batchId/cancel

Cancel a running (pending/processing) bulk batch. No request body.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
batchId	string	Batch ID

Response 200

200 via @HttpCode. On cancel, the remaining pending count is moved to cancelled.

{
  "batchId": "batch_a1b2c3d4",
  "status": "cancelled",
  "progress": { "total": 2, "sent": 1, "failed": 0, "pending": 0, "cancelled": 1 }
}

Errors: 400 batch already completed or cancelled · 401 missing/invalid API key · 403 key role below OPERATOR · 404 batch not found

6.4.3 Contacts

Contact endpoints are scoped under a session: /api/sessions/:sessionId/contacts. All read routes require a valid API key; the block/unblock writes require an OPERATOR key. Every route returns 400 "Session is not started" when the target session exists but is not in a started/ready state, and 404 when the session itself does not exist. Responses are the raw handler payload (no envelope).

The Contact object returned by the list and get-by-id routes has this shape:

{
  "id": "6281234567890@c.us",
  "name": "Jane Doe",
  "pushName": "Jane",
  "number": "6281234567890",
  "isMyContact": true,
  "isBlocked": false,
  "profilePicUrl": "https://pps.whatsapp.net/v/..."
}

name, pushName, and profilePicUrl are optional and may be absent.

GET /api/sessions/:sessionId/contacts

List all contacts for a session, returned as an in-memory paginated window.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID.

Query parameters

Name	Type	Required	Default	Description
limit	integer	No	1000	Parsed with parseInt(…,10); clamped to [1, 1000]. Omitted or non-finite values fall back to 1000.
offset	integer	No	0	Parsed with parseInt(…,10); non-finite values fall back to 0, then truncated to >= 0.

Response 200 — bare Contact[] array

[
  {
    "id": "6281234567890@c.us",
    "name": "Jane Doe",
    "pushName": "Jane",
    "number": "6281234567890",
    "isMyContact": true,
    "isBlocked": false,
    "profilePicUrl": "https://pps.whatsapp.net/v/..."
  }
]

Errors: 400 session is not started · 401 missing/invalid API key, or key not scoped to this session · 404 session not found

GET /api/sessions/:sessionId/contacts/check/:number

Check whether a phone number exists on WhatsApp and return its canonical WhatsApp id when it does.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID.
number	string	Phone number to check, e.g. 628123456789 (digits, no @c.us suffix).

Response 200

{
  "number": "628123456789",
  "exists": true,
  "whatsappId": "628123456789@c.us"
}

whatsappId is the canonical native chat id, or null when the number is not on WhatsApp; exists is whatsappId !== null.

Route-order caveat: the literal check/ segment disambiguates this route from GET /:contactId. A contact whose id is literally check would be shadowed by this handler.

Errors: 400 session is not started · 401 missing/invalid API key · 404 session not found

GET /api/sessions/:sessionId/contacts/:contactId

Get a single contact by its WhatsApp id.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID.
contactId	string	Contact id / JID, e.g. 6281234567890@c.us or an @lid.

Response 200 — Contact

{
  "id": "6281234567890@c.us",
  "name": "Jane Doe",
  "pushName": "Jane",
  "number": "6281234567890",
  "isMyContact": true,
  "isBlocked": false,
  "profilePicUrl": "https://pps.whatsapp.net/v/..."
}

Errors: 400 session is not started · 401 missing/invalid API key · 404 Contact <id> not found (engine returned null), or session not found

GET /api/sessions/:sessionId/contacts/:contactId/profile-picture

Get the profile picture URL for a contact (best-effort).

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID.
contactId	string	Contact id / JID, e.g. 6281234567890@c.us.

Response 200

{ "url": "https://pps.whatsapp.net/v/..." }

url is null when there is no picture, the contact's privacy hides it, or it cannot be resolved.

The path segment is profile-picture (hyphenated), not profile-pic.

Errors: 400 session is not started · 401 missing/invalid API key · 404 session not found

GET /api/sessions/:sessionId/contacts/:contactId/phone

Resolve a contact id (e.g. an @lid) to a phone number (MSISDN digits), best-effort.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID.
contactId	string	Contact id / JID to resolve, e.g. an @lid.

Response 200

{ "contactId": "12345678901234@lid", "phone": "6281234567890" }

phone is null when the engine cannot map the id (e.g. an @lid the account has never seen).

Errors: 400 session is not started · 401 missing/invalid API key · 404 session not found

POST /api/sessions/:sessionId/contacts/:contactId/block

Block a contact.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID.
contactId	string	Contact id / JID, e.g. 6281234567890@c.us.

This route takes no request body and binds no DTO. Send an empty body {} (the global whitelist + forbidNonWhitelisted ValidationPipe rejects any unexpected field with 400).

Response 200

This route is annotated @HttpCode(200), so it returns 200 rather than the POST default 201.

{ "success": true, "message": "Contact blocked" }

Errors: 400 session is not started · 401 missing/invalid API key · 403 key role below OPERATOR · 404 session not found

DELETE /api/sessions/:sessionId/contacts/:contactId/block

Unblock a contact.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID.
contactId	string	Contact id / JID, e.g. 6281234567890@c.us.

No request body.

Response 200

No @HttpCode override is present, so this DELETE returns the NestJS default 200 (not 204).

{ "success": true, "message": "Contact unblocked" }

Errors: 400 session is not started · 401 missing/invalid API key · 403 key role below OPERATOR · 404 session not found

6.4.4 Groups

All group routes are nested under a session: base path /api/sessions/:sessionId/groups. Reads (GET) require a plain API key; writes (create/modify/leave/revoke) require an OPERATOR role key. All routes resolve the engine for the session first, so a session that is not started yields 400 Session is not started.

GET /api/sessions/:sessionId/groups

List all groups for a session, with pagination.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID

Query parameters

Name	Type	Required	Default	Description
limit	string (parsed base-10 to number)	No	1000	Max groups to return; clamped to [1, 1000]. Omitted/non-finite → 1000.
offset	string (parsed base-10 to number)	No	0	Groups to skip. Non-finite → 0; negative truncated to 0.

Response 200

Raw array (no envelope). The service calls engine.getGroups() then paginates to bound the window.

[
  {
    "id": "120363021234567890@g.us",
    "name": "Project Team",
    "participantsCount": 12,
    "isAdmin": true,
    "linkedParentJID": null
  }
]

Errors: 400 session is not started · 401 missing/invalid X-API-Key

GET /api/sessions/:sessionId/groups/:groupId

Get detailed group info including participants.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID, e.g. 120363021234567890@g.us

Response 200

Raw object (no envelope). engine.getGroupInfo() returns GroupInfo | null; the service throws 404 when it is null.

{
  "id": "120363021234567890@g.us",
  "name": "Project Team",
  "description": "Internal coordination group.",
  "owner": "628123456789@c.us",
  "createdAt": 1718900000,
  "isReadOnly": false,
  "isAnnounce": false,
  "linkedParentJID": null,
  "participants": [
    {
      "id": "628123456789@c.us",
      "number": "628123456789",
      "name": "Alice",
      "isAdmin": true,
      "isSuperAdmin": true
    }
  ]
}

Errors: 400 session is not started · 401 missing/invalid X-API-Key · 404 Group <groupId> not found

GET /api/sessions/:sessionId/groups/:groupId/invite-code

Get the group invite code and full invite link.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Response 200

inviteCode comes from engine.getGroupInviteCode(); inviteLink is https://chat.whatsapp.com/<inviteCode>.

{
  "inviteCode": "AbCdEf123456",
  "inviteLink": "https://chat.whatsapp.com/AbCdEf123456"
}

Errors: 400 session is not started · 401 missing/invalid X-API-Key

POST /api/sessions/:sessionId/groups

Create a new group with an initial set of participants.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID

Request body — CreateGroupDto

Field	Type	Required	Constraints	Description
name	string	Yes	@IsString, @IsNotEmpty	Group subject/name
participants	string[]	Yes	@IsArray, @ArrayNotEmpty, @IsString({each:true})	Non-empty array of WhatsApp IDs, e.g. 628123456789@c.us

{
  "name": "Project Team",
  "participants": ["628123456789@c.us", "628987654321@c.us"]
}

Response 201

Returns the created Group directly (raw).

{
  "id": "120363021234567890@g.us",
  "name": "Project Team",
  "participantsCount": 3,
  "isAdmin": true,
  "linkedParentJID": null
}

Errors: 400 validation (missing/empty name or participants, or any non-DTO field) / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

POST /api/sessions/:sessionId/groups/:groupId/participants

Add participants to a group.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — ParticipantsDto

Field	Type	Required	Constraints	Description
participants	string[]	Yes	@IsArray, @ArrayNotEmpty, @IsString({each:true})	Non-empty array of WhatsApp IDs

{ "participants": ["628123456789@c.us"] }

Response 200

Status is forced to 200 via @HttpCode(HttpStatus.OK) (overriding the POST default). The body is a fixed acknowledgement after the void engine call.

{ "success": true, "message": "Participants added" }

Errors: 400 validation / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

DELETE /api/sessions/:sessionId/groups/:groupId/participants

Remove participants from a group. Note: this DELETE carries a JSON request body.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — ParticipantsDto

Field	Type	Required	Constraints	Description
participants	string[]	Yes	@IsArray, @ArrayNotEmpty, @IsString({each:true})	Non-empty array of WhatsApp IDs

{ "participants": ["628123456789@c.us"] }

Response 200

No @HttpCode, so NestJS uses the DELETE default of 200.

{ "success": true, "message": "Participants removed" }

Errors: 400 validation / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

POST /api/sessions/:sessionId/groups/:groupId/participants/promote

Promote participants to group admin.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — ParticipantsDto

Field	Type	Required	Constraints	Description
participants	string[]	Yes	@IsArray, @ArrayNotEmpty, @IsString({each:true})	Non-empty array of WhatsApp IDs

{ "participants": ["628123456789@c.us"] }

Response 200 (forced via @HttpCode(HttpStatus.OK))

{ "success": true, "message": "Participants promoted to admin" }

Errors: 400 validation / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

POST /api/sessions/:sessionId/groups/:groupId/participants/demote

Demote participants from group admin.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — ParticipantsDto

Field	Type	Required	Constraints	Description
participants	string[]	Yes	@IsArray, @ArrayNotEmpty, @IsString({each:true})	Non-empty array of WhatsApp IDs

{ "participants": ["628123456789@c.us"] }

Response 200 (forced via @HttpCode(HttpStatus.OK))

{ "success": true, "message": "Participants demoted from admin" }

Errors: 400 validation / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

PUT /api/sessions/:sessionId/groups/:groupId/subject

Change the group name/subject.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — GroupSubjectDto

Field	Type	Required	Constraints	Description
subject	string	Yes	@IsString, @IsNotEmpty	New group subject/name

{ "subject": "New Team Name" }

Response 200

No @HttpCode; PUT default is 200.

{ "success": true, "message": "Group subject updated" }

Errors: 400 validation (empty subject) / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

PUT /api/sessions/:sessionId/groups/:groupId/description

Change the group description. An empty string clears the description.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — GroupDescriptionDto

Field	Type	Required	Constraints	Description
description	string	Yes	@IsString (no @IsNotEmpty)	Must be present and a string, but "" is valid and clears the description

{ "description": "Internal coordination group." }

Response 200

No @HttpCode; PUT default is 200.

{ "success": true, "message": "Group description updated" }

Errors: 400 validation (description missing / not a string) / session not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

POST /api/sessions/:sessionId/groups/:groupId/leave

Leave a group.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — none (send an empty body).

Response 200 (forced via @HttpCode(HttpStatus.OK))

{ "success": true, "message": "Left the group" }

Errors: 400 session is not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

POST /api/sessions/:sessionId/groups/:groupId/invite-code/revoke

Revoke the current invite code and generate a new one.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
groupId	string	Group ID

Request body — none (send an empty body).

Response 200 (forced via @HttpCode(HttpStatus.OK))

inviteCode is the new code from engine.revokeGroupInviteCode(); inviteLink is https://chat.whatsapp.com/<newCode>.

{
  "inviteCode": "XyZ987654321",
  "inviteLink": "https://chat.whatsapp.com/XyZ987654321",
  "message": "Invite code revoked and new one generated"
}

Errors: 400 session is not started · 401 missing/invalid X-API-Key · 403 key lacks OPERATOR role

6.4.5 Message Templates

Reusable message templates scoped to a session, with {{variable}} placeholders rendered at send time. All routes are nested under /api/sessions/:sessionId/templates and require an OPERATOR key. The sessionId is stored on the template but is not validated against an existing session in these handlers.

GET /api/sessions/:sessionId/templates

List all templates for a session, newest first.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID; filters templates by sessionId.

Response 200

Bare Template[] array (no pagination, no envelope). Ordered by createdAt DESC. Returns an empty array — not 404 — when the session has no templates.

[
  {
    "id": "f1c2a3b4-5d6e-7f80-9a1b-2c3d4e5f6071",
    "sessionId": "9b1c0e2a-3d4f-5a6b-7c8d-9e0f1a2b3c4d",
    "name": "order-confirmation",
    "body": "Hi {{customer}}, your order {{orderId}} has shipped.",
    "header": "OpenWA Store",
    "footer": "Reply STOP to unsubscribe.",
    "createdAt": "2026-06-25T10:15:00.000Z",
    "updatedAt": "2026-06-25T10:15:00.000Z"
  }
]

Errors: 401 missing/invalid X-API-Key · 403 key below OPERATOR role

GET /api/sessions/:sessionId/templates/:id

Get a single template by ID within the session.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID; combined with id in the lookup.
id	string	Template UUID.

Response 200

Raw Template entity (no envelope).

{
  "id": "f1c2a3b4-5d6e-7f80-9a1b-2c3d4e5f6071",
  "sessionId": "9b1c0e2a-3d4f-5a6b-7c8d-9e0f1a2b3c4d",
  "name": "order-confirmation",
  "body": "Hi {{customer}}, your order {{orderId}} has shipped.",
  "header": "OpenWA Store",
  "footer": "Reply STOP to unsubscribe.",
  "createdAt": "2026-06-25T10:15:00.000Z",
  "updatedAt": "2026-06-25T10:15:00.000Z"
}

Errors: 401 missing/invalid X-API-Key · 403 key below OPERATOR role · 404 no row matches the id+sessionId pair ({ "statusCode": 404, "message": "Template with id '<id>' not found", "error": "Not Found" })

POST /api/sessions/:sessionId/templates

Create a message template for the session (with {{variable}} placeholders in the body).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID; stored as template.sessionId. Not validated against an existing session in this handler.

Request body — CreateTemplateDto

Field	Type	Required	Constraints	Description
name	string	yes	non-empty, max 100 chars	Unique template name within the session (DB unique index on [sessionId, name]). Duplicate → 409.
body	string	yes	non-empty, max 4096 chars	Template body containing {{variable}} placeholders rendered at send time.
header	string	no	max 1024 chars	Optional header text; coerced to null when omitted. Prepended to rendered body.
footer	string	no	max 1024 chars	Optional footer text; coerced to null when omitted. Appended to rendered body.

{
  "name": "order-confirmation",
  "body": "Hi {{customer}}, your order {{orderId}} has shipped.",
  "header": "OpenWA Store",
  "footer": "Reply STOP to unsubscribe."
}

Response 201

Returns the saved Template entity raw (no envelope). The lazy session relation is not loaded on a freshly saved entity, so it is absent from the JSON.

{
  "id": "f1c2a3b4-5d6e-7f80-9a1b-2c3d4e5f6071",
  "sessionId": "9b1c0e2a-3d4f-5a6b-7c8d-9e0f1a2b3c4d",
  "name": "order-confirmation",
  "body": "Hi {{customer}}, your order {{orderId}} has shipped.",
  "header": "OpenWA Store",
  "footer": "Reply STOP to unsubscribe.",
  "createdAt": "2026-06-25T10:15:00.000Z",
  "updatedAt": "2026-06-25T10:15:00.000Z"
}

Errors: 400 validation failure (missing/empty name/body, over-length, or any extra field rejected by forbidNonWhitelisted) · 401 missing/invalid X-API-Key · 403 key below OPERATOR role · 409 duplicate name for the session

PUT /api/sessions/:sessionId/templates/:id

Update a template's name/body/header/footer (partial; only provided fields change).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID.
id	string	Template UUID to update.

Request body — UpdateTemplateDto

Field	Type	Required	Constraints	Description
name	string	no	if present: non-empty, max 100 chars	Applied only when not undefined. Duplicate name → 409.
body	string	no	if present: non-empty, max 4096 chars	Applied only when not undefined.
header	string	no	max 1024 chars	Applied only when not undefined. The update path does not coerce to null, so passing explicit null fails @IsString; omit the key to leave it unchanged.
footer	string	no	max 1024 chars	Applied only when not undefined.

{
  "body": "Hi {{customer}}, your order {{orderId}} is out for delivery.",
  "footer": "Thanks for shopping with us."
}

Response 200

Loads via lookup (404 if missing), patches the provided fields, saves, and returns the updated entity raw. updatedAt is refreshed.

{
  "id": "f1c2a3b4-5d6e-7f80-9a1b-2c3d4e5f6071",
  "sessionId": "9b1c0e2a-3d4f-5a6b-7c8d-9e0f1a2b3c4d",
  "name": "order-confirmation",
  "body": "Hi {{customer}}, your order {{orderId}} is out for delivery.",
  "header": "OpenWA Store",
  "footer": "Thanks for shopping with us.",
  "createdAt": "2026-06-25T10:15:00.000Z",
  "updatedAt": "2026-06-25T11:02:00.000Z"
}

Errors: 400 validation / forbidNonWhitelisted · 401 missing/invalid X-API-Key · 403 key below OPERATOR role · 404 id+sessionId not found (raised before any write) · 409 rename collides with another template name in the session

DELETE /api/sessions/:sessionId/templates/:id

Delete a template by ID.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID.
id	string	Template UUID to delete.

Response 204

No content (empty body). The handler looks the template up first, so a missing template yields 404 rather than a silent 204.

Errors: 401 missing/invalid X-API-Key · 403 key below OPERATOR role · 404 id+sessionId not found

6.4.6 Catalog & Channels

WhatsApp Business catalog browsing/sending and channel (newsletter) operations. Catalog read routes (/catalog…) require any valid API key; the two product/catalog send routes live under the /messages path and require an OPERATOR key. Channel read routes require any valid API key; subscribe/unsubscribe require OPERATOR.

GET /api/sessions/:sessionId/catalog

Get business catalog info for the session's WhatsApp Business account.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id.

Response 200

{
  "id": "1234567890123456",
  "name": "My Storefront",
  "description": "Best products in town",
  "productCount": 12,
  "url": "https://wa.me/c/6281234567890"
}

Returns null when the account has no catalog (catalog is a WhatsApp Business-only feature; non-business accounts may yield null). The response is the raw engine.getCatalog() return — no envelope.

Errors: 401 missing/invalid API key · 404 Session <sessionId> not found or not connected · 500 engine error

GET /api/sessions/:sessionId/catalog/products

List catalog products with pagination.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id.

Query parameters

Name	Type	Required	Default	Description
page	integer	No	1	Page number. Coerced from string; must be an integer >= 1 or 400.
limit	integer	No	20	Page size. Must be an integer >= 1. No upper cap declared on the DTO.

Validated against ProductQueryDto via the global ValidationPipe; any unknown query key is rejected with 400 (forbidNonWhitelisted).

Response 200

{
  "products": [
    {
      "id": "PROD_12345",
      "name": "Wireless Earbuds",
      "description": "Noise-cancelling, 24h battery",
      "price": 49990,
      "currency": "IDR",
      "priceFormatted": "Rp 49.990",
      "imageUrl": "https://example.com/img/earbuds.jpg",
      "url": "https://wa.me/p/PROD_12345/6281234567890",
      "isAvailable": true,
      "retailerId": "SKU-EB-01"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Errors: 400 invalid page/limit or unknown query key · 401 missing/invalid API key · 404 Session <sessionId> not found or not connected · 500 engine error

GET /api/sessions/:sessionId/catalog/products/:productId

Get a specific catalog product by id.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id.
productId	string	Catalog product id.

Response 200

{
  "id": "PROD_12345",
  "name": "Wireless Earbuds",
  "description": "Noise-cancelling, 24h battery",
  "price": 49990,
  "currency": "IDR",
  "priceFormatted": "Rp 49.990",
  "imageUrl": "https://example.com/img/earbuds.jpg",
  "url": "https://wa.me/p/PROD_12345/6281234567890",
  "isAvailable": true,
  "retailerId": "SKU-EB-01"
}

An unknown productId returns 200 with body null — it is not a 404. Only a missing/disconnected session yields 404.

Errors: 401 missing/invalid API key · 404 Session <sessionId> not found or not connected · 500 engine error

POST /api/sessions/:sessionId/messages/send-product

Send a product message (catalog product card) to a chat. Note: this route lives under the /messages path but belongs to the catalog module.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id.

Request body — SendProductDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	@IsString	Target chat/recipient id (e.g. 6281234567890@c.us).
productId	string	Yes	@IsString	Catalog product id to send.
body	string	No	@IsString	Optional message body/caption.

{
  "chatId": "6281234567890@c.us",
  "productId": "PROD_12345",
  "body": "Check out this item!"
}

Response 201

{ "id": "true_6281234567890@c.us_3EB0...", "timestamp": 1719331200 }

timestamp is an epoch number (seconds).

Errors: 400 missing chatId/productId, wrong types, or any field not on the DTO · 401 missing/invalid API key · 403 API-key role below OPERATOR · 404 Session <sessionId> not found or not connected · 500 engine error

POST /api/sessions/:sessionId/messages/send-catalog

Send the business catalog link to a chat. Note: this route lives under the /messages path but belongs to the catalog module.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id.

Request body — SendCatalogDto

Field	Type	Required	Constraints	Description
chatId	string	Yes	@IsString	Target chat/recipient id.
body	string	No	@IsString	Optional message body/caption.

{
  "chatId": "6281234567890@c.us",
  "body": "Browse our full catalog here"
}

Response 201

{ "id": "true_6281234567890@c.us_3EB0...", "timestamp": 1719331200 }

timestamp is an epoch number (seconds).

Errors: 400 missing/invalid chatId or any non-DTO field · 401 missing/invalid API key · 403 API-key role below OPERATOR · 404 Session <sessionId> not found or not connected · 500 engine error

GET /api/sessions/:sessionId/channels

List all channels/newsletters the session is subscribed to.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id. The engine must be started or the request fails with 400.

Response 200

[
  {
    "id": "120363000000000000@newsletter",
    "name": "OpenWA Updates",
    "description": "Release notes and tips",
    "inviteCode": "ABC123xyz",
    "subscriberCount": 1042,
    "picture": "https://example.com/ch.jpg",
    "verified": true,
    "createdAt": 1717200000
  }
]

Bare array, no envelope.

Errors: 400 Session is not started · 401 missing/invalid API key

GET /api/sessions/:sessionId/channels/:channelId

Get a single channel/newsletter by its id.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id. Engine must be started.
channelId	string	Channel/newsletter id.

Response 200

{
  "id": "120363000000000000@newsletter",
  "name": "OpenWA Updates",
  "description": "Release notes and tips",
  "inviteCode": "ABC123xyz",
  "subscriberCount": 1042,
  "picture": "https://example.com/ch.jpg",
  "verified": true,
  "createdAt": 1717200000
}

Errors: 400 Session is not started · 401 missing/invalid API key · 404 Channel <channelId> not found (engine returned null)

GET /api/sessions/:sessionId/channels/:channelId/messages

Get recent messages from a channel/newsletter.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id. Engine must be started.
channelId	string	Channel/newsletter id.

Query parameters

Name	Type	Required	Default	Description
limit	number	No	engine default (Swagger notes 50)	Max messages to return. Taken as a raw query string and run through parseInt(limit, 10) when present, else undefined is passed to the engine. There is no DTO/ValidationPipe on this value — a non-numeric limit becomes NaN and is forwarded to the engine.

Response 200

[
  {
    "id": "false_120363000000000000@newsletter_3EB0...",
    "body": "v0.7.3 is out!",
    "timestamp": 1719331200,
    "hasMedia": false,
    "mediaUrl": null
  }
]

Bare array. timestamp is an epoch number (seconds).

Errors: 400 Session is not started · 401 missing/invalid API key

POST /api/sessions/:sessionId/channels/subscribe

Subscribe to a channel using its invite code.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id. Engine must be started.

Request body — SubscribeChannelDto

Field	Type	Required	Constraints	Description
inviteCode	string	Yes	@IsString @IsNotEmpty	Channel invite code from the channel share link.

{ "inviteCode": "ABC123xyz" }

Response 201

{
  "id": "120363000000000000@newsletter",
  "name": "OpenWA Updates",
  "description": "Release notes and tips",
  "inviteCode": "ABC123xyz",
  "subscriberCount": 1042,
  "picture": "https://example.com/ch.jpg",
  "verified": true,
  "createdAt": 1717200000
}

Errors: 400 Session is not started, missing/empty inviteCode, or any unknown body field · 401 missing/invalid API key · 403 API-key role below OPERATOR

DELETE /api/sessions/:sessionId/channels/:channelId

Unsubscribe from a channel.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session id. Engine must be started.
channelId	string	Channel id to unsubscribe from.

Response 200

{ "success": true }

Note: this is the one route in the module that returns a literal { success: true } (hard-coded by the controller after the void engine call resolves) rather than the raw engine return. There is no @HttpCode override, so it returns 200, not 204.

Errors: 400 Session is not started · 401 missing/invalid API key · 403 API-key role below OPERATOR

6.4.7 Labels & Status

Labels are a WhatsApp Business feature: every label route lives under a session and reads/writes the chat-label assignments exposed by the engine. Status routes manage the session's status feed (stories) — reading visible statuses and posting/deleting your own. Read routes require a base API key; all writes require OPERATOR.

GET /api/sessions/:sessionId/labels

List all labels defined for the session (WhatsApp Business accounts only).

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID

Response 200

[
  { "id": "1", "name": "New customer", "hexColor": "#FF9485" },
  { "id": "5", "name": "Paid", "hexColor": "#25D366" }
]

Bare array — raw return of engine.getLabels(); no envelope.

Errors: 400 session is not started (no live engine), or the account is not a WhatsApp Business account · 401 missing/invalid API key

GET /api/sessions/:sessionId/labels/:labelId

Get a single label by its ID.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
labelId	string	Label ID

Response 200

{ "id": "5", "name": "Paid", "hexColor": "#25D366" }

The engine resolves Label | null; a null is mapped to 404 in the service, so a 200 always carries a label.

Errors: 400 session is not started · 401 missing/invalid API key · 404 Label <labelId> not found

GET /api/sessions/:sessionId/labels/chat/:chatId

List the labels currently assigned to a specific chat.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	Session ID
chatId	string	Chat ID (e.g. 6281234567890@c.us or a group …@g.us)

Response 200

[
  { "id": "5", "name": "Paid", "hexColor": "#25D366" }
]

Bare array — raw return of engine.getChatLabels(chatId).

Errors: 400 session is not started · 401 missing/invalid API key

POST /api/sessions/:sessionId/labels/chat/:chatId

Add a label to a chat.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
chatId	string	Chat ID to label

Request body — AddLabelDto

Field	Type	Required	Constraints	Description
labelId	string	yes	non-empty string	Label ID to add to the chat

{ "labelId": "5" }

Response 201

{ "success": true }

The handler always returns the literal { "success": true }. NestJS POST default status is 201 (the Swagger doc says 200; the runtime code is 201).

Errors: 400 validation failure (missing/empty/non-string labelId, or any unknown body field — strict whitelist), or session is not started · 401 missing/invalid API key · 403 key lacks OPERATOR role

DELETE /api/sessions/:sessionId/labels/chat/:chatId/:labelId

Remove a label from a chat.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID
chatId	string	Chat ID
labelId	string	Label ID to remove

Response 200

{ "success": true }

The handler always returns { "success": true }. DELETE default status is 200 (no @HttpCode override).

Errors: 400 session is not started · 401 missing/invalid API key · 403 key lacks OPERATOR role

GET /api/sessions/:sessionId/status

Get all contact status updates (stories) visible to the session.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session identifier

Response 200

{
  "statuses": [
    {
      "id": "false_6281234567890@c.us_3A1F...",
      "contact": { "id": "6281234567890@c.us", "name": "Alice", "pushName": "Alice" },
      "type": "image",
      "caption": "On the road",
      "mediaUrl": "https://…",
      "backgroundColor": "#25D366",
      "font": 2,
      "timestamp": "2026-06-25T08:30:00.000Z",
      "expiresAt": "2026-06-26T08:30:00.000Z"
    }
  ]
}

The controller wraps the engine array in { statuses }. type is one of text | image | video; caption, mediaUrl, backgroundColor, font are optional. timestamp and expiresAt serialize to ISO strings (these are Date values, not the epoch-number convention used by message timestamps).

Errors: 401 missing/invalid API key, or key not scoped to this session · 404 Session {id} not found or not connected

GET /api/sessions/:sessionId/status/:contactId

Get status updates posted by a specific contact.

Auth: API key

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session identifier
contactId	string	Contact JID/id (e.g. 6281234567890@c.us)

Response 200

{
  "statuses": [
    {
      "id": "false_6281234567890@c.us_3A1F...",
      "contact": { "id": "6281234567890@c.us", "pushName": "Alice" },
      "type": "text",
      "caption": "Hello!",
      "backgroundColor": "#25D366",
      "font": 0,
      "timestamp": "2026-06-25T08:30:00.000Z",
      "expiresAt": "2026-06-26T08:30:00.000Z"
    }
  ]
}

Same { statuses } wrapper and Status shape as the list-all route.

Errors: 401 missing/invalid API key, or key not scoped to this session · 404 session not found / not connected

POST /api/sessions/:sessionId/status/send-text

Post a text status (story) to the session's status feed. Baileys engine only — a whatsapp-web.js session returns 501 (see Errors).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session identifier

Request body — SendTextStatusDto

Field	Type	Required	Constraints	Description
text	string	yes	—	Status text body
recipients	string[]	yes	1–256 items, each matching ^\d+@(c\.us|lid)$	JIDs of the contacts permitted to view the status (passed as statusJidList to the engine). Empty array → 400
backgroundColor	string	no	6-digit hex color matching ^#[0-9A-Fa-f]{6}$	e.g. #25D366; bad value → backgroundColor must be a hex color (e.g., #25D366)
font	integer	no	integer 0–5	Font index

{ "text": "Hello from OpenWA!", "recipients": ["6281234567890@c.us"], "backgroundColor": "#25D366", "font": 2 }

Response 201

{
  "statusId": "false_status@broadcast_3A1F...",
  "timestamp": "2026-06-25T08:30:00.000Z",
  "expiresAt": "2026-06-26T08:30:00.000Z"
}

Returns the engine StatusResult directly (no wrapper). POST default status is 201.

Recipient JIDs: @c.us (regular phone) recipients are reliable. @lid (privacy-id) recipients are best-effort and unverified — WhatsApp may not deliver to an unresolved LID, so prefer @c.us where the phone number is known.

Sender-side caveat: the posting account's own phone may display a "waiting for this status update" notice in its status feed; this is cosmetic — recipients view the status normally.

Errors: 400 validation failure (unknown body field, missing/empty recipients, a JID not matching @c.us/@lid, or more than 256 recipients, bad backgroundColor/font), or session is not started · 401 missing/invalid API key · 403 key lacks OPERATOR role · 404 session not found / not connected · 501 the session is on the whatsapp-web.js engine (status posting is Baileys-only; WA Web removed WAWebStatusGatingUtils.canCheckStatusRankingPosterGating around 2026-04-30, so the wwebjs path is upstream-blocked — see #455)

POST /api/sessions/:sessionId/status/send-image

Post an image status (story) from a URL or base64 payload. Baileys engine only — a whatsapp-web.js session returns 501 (see Errors).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session identifier

Request body — SendImageStatusDto

Field	Type	Required	Constraints	Description
image	object (MediaInput)	yes	validated nested object (an empty {} passes — there is no @IsNotEmpty)	Media source wrapper
image.url	string	no	—	Media source URL
image.base64	string	no	—	Base64-encoded media data
image.mimetype	string	no	—	Media MIME type; if omitted the service defaults to image/jpeg
recipients	string[]	yes	1–256 items, each matching ^\d+@(c\.us|lid)$	JIDs of the contacts permitted to view the status (statusJidList). Empty array → 400
caption	string	no	—	Optional caption

The service resolves the media as image.url || image.base64 || '' and applies mimetype image.mimetype ?? 'image/jpeg'.

{ "image": { "url": "https://example.com/photo.jpg", "mimetype": "image/png" }, "recipients": ["6281234567890@c.us"], "caption": "My status" }

Response 201

{
  "statusId": "false_status@broadcast_3A1F...",
  "timestamp": "2026-06-25T08:30:00.000Z",
  "expiresAt": "2026-06-26T08:30:00.000Z"
}

Returns the engine StatusResult directly. POST default status is 201.

Recipient JIDs: @c.us (regular phone) recipients are reliable. @lid (privacy-id) recipients are best-effort and unverified — prefer @c.us where the phone number is known. Sender-side caveat: the posting account's own phone may show a "waiting for this status update" notice; recipients view it normally.

Errors: 400 validation failure (unknown body field, missing/empty recipients, a JID not matching @c.us/@lid, or more than 256 recipients), or session is not started · 401 missing/invalid API key · 403 key lacks OPERATOR role · 404 session not found / not connected · 501 the session is on the whatsapp-web.js engine (status posting is Baileys-only; see send-text and #455)

POST /api/sessions/:sessionId/status/send-video

Post a video status (story) from a URL or base64 payload. Baileys engine only — a whatsapp-web.js session returns 501 (see Errors).

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session identifier

Request body — SendVideoStatusDto

Field	Type	Required	Constraints	Description
video	object (MediaInput)	yes	validated nested object (an empty {} passes)	Media source wrapper
video.url	string	no	—	Media source URL
video.base64	string	no	—	Base64-encoded media data
video.mimetype	string	no	—	Media MIME type; if omitted the service defaults to video/mp4
recipients	string[]	yes	1–256 items, each matching ^\d+@(c\.us|lid)$	JIDs of the contacts permitted to view the status (statusJidList). Empty array → 400
caption	string	no	—	Optional caption

The service resolves the media as video.url || video.base64 || '' and applies mimetype video.mimetype ?? 'video/mp4'.

{ "video": { "url": "https://example.com/clip.mp4", "mimetype": "video/quicktime" }, "recipients": ["6281234567890@c.us"], "caption": "Watch this" }

Response 201

{
  "statusId": "false_status@broadcast_3A1F...",
  "timestamp": "2026-06-25T08:30:00.000Z",
  "expiresAt": "2026-06-26T08:30:00.000Z"
}

Returns the engine StatusResult directly. POST default status is 201.

Recipient JIDs: @c.us (regular phone) recipients are reliable. @lid (privacy-id) recipients are best-effort and unverified — prefer @c.us where the phone number is known. Sender-side caveat: the posting account's own phone may show a "waiting for this status update" notice; recipients view it normally.

Errors: 400 validation failure (unknown body field, missing/empty recipients, a JID not matching @c.us/@lid, or more than 256 recipients), or session is not started · 401 missing/invalid API key · 403 key lacks OPERATOR role · 404 session not found / not connected · 501 the session is on the whatsapp-web.js engine (status posting is Baileys-only; see send-text and #455)

DELETE /api/sessions/:sessionId/status/:statusId

Delete one of the session's own posted statuses.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	WhatsApp session identifier
statusId	string	Id of the status to delete (the statusId returned by a send-* call)

Response 200

{ "message": "Status deleted successfully" }

The service returns void; the controller returns a fixed success object. DELETE default status is 200.

Errors: 401 missing/invalid API key · 403 key lacks OPERATOR role · 404 Session {id} not found or not connected

6.4.8 Webhooks (management)

Webhooks are configured per session and managed under /api/sessions/:sessionId/webhooks (handled by WebhookController). A separate cross-session list endpoint lives at /api/webhooks (handled by WebhooksListController). Every route requires an API key with OPERATOR role or higher.

Two fields — secret and headers — are write-only: they are accepted on create/update but are never returned in any response (the response DTO has no @Expose for them, so fromEntity drops them). The secret is used to compute the X-OpenWA-Signature: sha256=<hex> HMAC-SHA256 header on deliveries.

The events array accepts these members plus the * wildcard: message.received, message.sent, message.ack, message.failed, message.revoked, message.reaction, session.status, session.qr, session.authenticated, session.disconnected, group.join, group.leave, group.update. The group.* events are reserved — accepted and validated but never dispatched (no engine emit source).

GET /api/sessions/:sessionId/webhooks

List all webhooks for a session, ordered by createdAt descending.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID to filter webhooks by.

Response 200

[
  {
    "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "sessionId": "my-session",
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "session.status"],
    "filters": null,
    "active": true,
    "retryCount": 3,
    "lastTriggeredAt": null,
    "createdAt": "2026-06-25T10:00:00.000Z",
    "updatedAt": "2026-06-25T10:00:00.000Z"
  }
]

Returns a bare array; empty array if the session has no webhooks. secret and headers are never included. Not paginated.

Errors: 401 missing/invalid API key · 403 insufficient role

GET /api/sessions/:sessionId/webhooks/:id

Get a single webhook by ID, scoped to the session.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session ID. The lookup is WHERE { id, sessionId }, so a webhook belonging to a different session resolves to 404 (no cross-session existence oracle).
id	string (uuid)	Webhook ID.

Response 200

{
  "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "sessionId": "my-session",
  "url": "https://your-server.com/webhook",
  "events": ["message.received"],
  "filters": null,
  "active": true,
  "retryCount": 3,
  "lastTriggeredAt": "2026-06-25T11:30:00.000Z",
  "createdAt": "2026-06-25T10:00:00.000Z",
  "updatedAt": "2026-06-25T10:00:00.000Z"
}

Errors: 401 missing/invalid API key · 403 insufficient role · 404 webhook not found in this session (message "Webhook with id '<id>' not found")

GET /api/webhooks

List webhooks visible to the calling API key, scoped to its allowed sessions.

Auth: API key (OPERATOR) · Scope: session-scoped — derived from the authenticated key, not from any param/query

Query parameters

Name	Type	Required	Default	Description
limit	integer (1-1000)	No	1000	Max webhooks to return; oversized/non-finite values are clamped/fallback to the default window.
offset	integer	No	0	Webhooks to skip for paging; negative/non-finite values resolve to 0.

Response 200

[
  {
    "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "sessionId": "my-session",
    "url": "https://your-server.com/webhook",
    "events": ["message.received"],
    "filters": null,
    "active": true,
    "retryCount": 3,
    "lastTriggeredAt": null,
    "createdAt": "2026-06-25T10:00:00.000Z",
    "updatedAt": "2026-06-25T10:00:00.000Z"
  }
]

Bare array, ordered by createdAt descending, bounded by limit/offset. If the calling key has a non-empty allowedSessions list, results are filtered to WHERE sessionId IN (allowedSessions); a key with null/empty allowedSessions (e.g. an unrestricted ADMIN key) sees all webhooks. This is the cross-session list; the per-session list lives at GET /api/sessions/:sessionId/webhooks.

Errors: 401 missing/invalid API key · 403 insufficient role

POST /api/sessions/:sessionId/webhooks

Create a webhook for the session.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session the webhook is scoped to; stored as webhook.sessionId. No session-existence check is performed at create time.

Request body — CreateWebhookDto

Field	Type	Required	Constraints	Description
url	string	yes	@IsUrl({ require_tld: false }) (allows hostnames without a dot, e.g. http://localhost:3000); also run through the SSRF guard, which can reject with 400. Entity column max 2048 chars.	Webhook URL to receive events.
events	string[]	no	@IsArray, @ArrayMinSize(1), @IsIn([...WEBHOOK_EVENTS, '*'], { each: true })	Event names to subscribe to (see allowed set above). Defaults to ["message.received"] when omitted.
secret	string	no	@IsString, @MaxLength(255)	HMAC-SHA256 signing key. Write-only — never returned. Used for X-OpenWA-Signature. Defaults to null.
headers	Record<string,string>	no	@IsHeaderMap() — flat object (not array), ≤50 entries, names match /^[A-Za-z0-9-]+$/, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard).	Custom headers added to deliveries. Write-only — never returned. At delivery, content-type and x-openwa-* names are stripped. Defaults to {}.
filters	WebhookFilters | null	no	@IsValidWebhookFilters() — { conditions: [...] }; each condition { field, operator('is'|'isNot'|'contains'|'equals'), value(string|string[]|boolean), caseSensitive?:boolean }; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: sender, recipient, body, type, isGroup, fromMe, hasMedia, mentions.	Optional AND pre-filter; all conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to null.
retryCount	number (int)	no	@IsInt, @Min(0), @Max(5)	Delivery retry attempts on failure. Defaults to 3.

{
  "url": "https://your-server.com/webhook",
  "events": ["message.received", "session.status"],
  "secret": "your-secret-key",
  "headers": { "X-Custom-Header": "value" },
  "filters": {
    "conditions": [
      { "field": "sender", "operator": "is", "value": ["1234567890@c.us"] },
      { "field": "body", "operator": "contains", "value": "invoice" }
    ]
  },
  "retryCount": 3
}

Response 201

{
  "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "sessionId": "my-session",
  "url": "https://your-server.com/webhook",
  "events": ["message.received", "session.status"],
  "filters": {
    "conditions": [
      { "field": "sender", "operator": "is", "value": ["1234567890@c.us"] },
      { "field": "body", "operator": "contains", "value": "invoice" }
    ]
  },
  "active": true,
  "retryCount": 3,
  "lastTriggeredAt": null,
  "createdAt": "2026-06-25T10:00:00.000Z",
  "updatedAt": "2026-06-25T10:00:00.000Z"
}

secret and headers are deliberately excluded from the response. active defaults to true, lastTriggeredAt is null on create.

Errors: 400 validation failure, unknown body field (whitelist), or SSRF URL rejection · 401 missing/invalid API key · 403 insufficient role

PUT /api/sessions/:sessionId/webhooks/:id

Update a webhook. Partial — only fields present in the body are changed.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session scope; the webhook is looked up by (sessionId, id) first → 404 if not in this session.
id	string (uuid)	Webhook ID.

Request body — UpdateWebhookDto (all fields optional; only fields where the value is not undefined are applied)

Field	Type	Required	Constraints	Description
url	string	no	@IsOptional, @IsUrl({ require_tld: false }); re-runs the SSRF guard when provided → 400 if blocked.	New URL.
events	string[]	no	@IsOptional, @IsArray, @ArrayMinSize(1), @IsIn([...WEBHOOK_EVENTS, '*'], { each: true })	Same allowed set as create (incl. * and reserved group.*).
secret	string	no	@IsOptional, @IsString, @MaxLength(255)	Write-only. An empty string is normalized to null, which disables HMAC.
headers	Record<string,string>	no	@IsOptional, @IsHeaderMap() (same constraints as create)	Write-only. Replaces existing headers wholesale when provided.
filters	WebhookFilters | null	no	@IsOptional, @IsValidWebhookFilters()	Set to null to clear filters.
active	boolean	no	@IsOptional, @IsBoolean	Enable/disable the webhook. (Present only on update, not create.)
retryCount	number (int)	no	@IsOptional, @IsInt, @Min(0), @Max(5)	Retry attempts.

{
  "events": ["*"],
  "active": false,
  "retryCount": 5,
  "filters": null
}

Response 200

{
  "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "sessionId": "my-session",
  "url": "https://your-server.com/webhook",
  "events": ["*"],
  "filters": null,
  "active": false,
  "retryCount": 5,
  "lastTriggeredAt": null,
  "createdAt": "2026-06-25T10:00:00.000Z",
  "updatedAt": "2026-06-25T12:00:00.000Z"
}

Returns the saved entity; secret and headers excluded.

Errors: 400 validation failure, unknown body field (whitelist), or SSRF URL rejection · 401 missing/invalid API key · 403 insufficient role · 404 webhook not found in this session

POST /api/sessions/:sessionId/webhooks/:id/test

Send a synthetic test payload to the webhook URL and report the result. No request body.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session scope; looked up first → 404 if not in this session.
id	string (uuid)	Webhook ID.

Response 200

{ "success": true, "statusCode": 200 }

On a reachable endpoint the response is { success: <response.ok>, statusCode: <response.status> } — so a non-2xx target returns 200 HTTP with success: false and the target's statusCode. On an SSRF/timeout/network error the response is { "success": false, "error": "<message>" }. The endpoint never throws on delivery failure; the failure is reflected in the body, not the HTTP status. The test POST sends { "event": "test", ... } with headers Content-Type, User-Agent: OpenWA-Webhook/1.0.0, X-OpenWA-Event: test, X-OpenWA-Idempotency-Key, X-OpenWA-Delivery-Id, X-OpenWA-Retry-Count: 0, and X-OpenWA-Signature when a secret is set. Timeout defaults to 10000 ms (webhook.timeout config).

Errors: 401 missing/invalid API key · 403 insufficient role · 404 webhook not found in this session

DELETE /api/sessions/:sessionId/webhooks/:id

Delete a webhook, scoped to the session.

Auth: API key (OPERATOR)

Path parameters

Name	Type	Description
sessionId	string	Session scope; looked up first → 404 if not in this session.
id	string (uuid)	Webhook ID.

Response 204

No content (empty body; explicit @HttpCode(204)).

Errors: 401 missing/invalid API key · 403 insufficient role · 404 webhook not found in this session

6.4.9 API Keys

API keys are managed under /api/auth/api-keys. All management routes (create/list/get/update/delete/revoke) require an ADMIN key. The plaintext key string is returned only once, at creation. Validation of the caller's own key lives at POST /api/auth/validate and accepts any valid key.

GET /api/auth/api-keys

List all API keys, newest first. The plaintext key is never returned.

Auth: API key (ADMIN)

Response 200

Bare JSON array (no envelope), ordered by createdAt DESC. Null array/date fields are omitted.

[
  {
    "id": "3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33",
    "name": "Production Bot",
    "keyPrefix": "owa_k1_a1b2",
    "role": "operator",
    "allowedIps": ["192.168.1.1", "10.0.0.0/8"],
    "allowedSessions": ["session-uuid-1"],
    "isActive": true,
    "expiresAt": "2027-12-31T23:59:59.000Z",
    "lastUsedAt": "2026-06-25T08:14:00.000Z",
    "usageCount": 42,
    "createdAt": "2026-06-01T10:00:00.000Z"
  }
]

Errors: 401 missing/invalid X-API-Key · 403 key role below ADMIN

GET /api/auth/api-keys/:id

Get a single API key's details by id. No plaintext key.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string (uuid)	API key id. Opaque resource id, not session-scoped.

Response 200

{
  "id": "3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33",
  "name": "Production Bot",
  "keyPrefix": "owa_k1_a1b2",
  "role": "operator",
  "allowedIps": ["192.168.1.1", "10.0.0.0/8"],
  "allowedSessions": ["session-uuid-1"],
  "isActive": true,
  "expiresAt": "2027-12-31T23:59:59.000Z",
  "lastUsedAt": "2026-06-25T08:14:00.000Z",
  "usageCount": 42,
  "createdAt": "2026-06-01T10:00:00.000Z"
}

Errors: 401 missing/invalid key · 403 key role below ADMIN · 404 "API key with id '<id>' not found"

POST /api/auth/api-keys

Create a new API key; returns the full plaintext key exactly once.

Auth: API key (ADMIN)

Request body — CreateApiKeyDto

Field	Type	Required	Constraints	Description
name	string	yes	length 3–100	Friendly name for the key.
role	enum admin | operator | viewer	no	@IsEnum	Defaults to operator when omitted.
allowedIps	string[]	no	each entry a valid IPv4 address or IPv4 CIDR /0-32; IPv6 rejected	IP whitelist (IPv4-only by design).
allowedSessions	string[]	no	each @IsString	Session IDs this key may access.
expiresAt	string (ISO 8601 date)	no	@IsDateString	Stored as a Date.

{
  "name": "Production Bot",
  "role": "operator",
  "allowedIps": ["192.168.1.1", "10.0.0.0/8"],
  "allowedSessions": ["session-uuid-1"],
  "expiresAt": "2027-12-31T23:59:59Z"
}

Response 201 — ApiKeyCreatedResponseDto

Same shape as the read DTO plus an apiKey field carrying the full plaintext key owa_k1_<64 hex>. This is the only time the plaintext key is returned. keyPrefix is the first 12 chars; usageCount starts at 0, isActive is true. Null allowedIps/allowedSessions/expiresAt/lastUsedAt are omitted.

{
  "id": "3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33",
  "name": "Production Bot",
  "keyPrefix": "owa_k1_a1b2",
  "role": "operator",
  "allowedIps": ["192.168.1.1", "10.0.0.0/8"],
  "allowedSessions": ["session-uuid-1"],
  "isActive": true,
  "expiresAt": "2027-12-31T23:59:59.000Z",
  "usageCount": 0,
  "createdAt": "2026-06-25T09:30:00.000Z",
  "apiKey": "owa_k1_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Errors: 400 validation (bad name length, invalid role enum, non-IPv4 allowedIps entry, bad expiresAt, or any non-whitelisted body field) · 401 missing/invalid key · 403 key role below ADMIN

PUT /api/auth/api-keys/:id

Update mutable fields of an API key. isActive is not updatable here — use the revoke route to deactivate.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string (uuid)	API key id.

Request body — UpdateApiKeyDto

Field	Type	Required	Constraints	Description
name	string	no	length 3–100	Applied only if truthy.
role	enum admin | operator | viewer	no	@IsEnum	Applied only if truthy.
allowedIps	string[]	no	IPv4 address / CIDR only	Applied if not undefined (can be set to [] to clear).
allowedSessions	string[]	no	each @IsString	Applied if not undefined.
expiresAt	string (ISO 8601 date)	no	@IsDateString	Applied if not undefined; empty/falsy clears to null.

{
  "name": "Renamed Bot",
  "role": "viewer",
  "allowedIps": ["203.0.113.5"],
  "expiresAt": "2028-01-01T00:00:00Z"
}

Response 200 — ApiKeyResponseDto

Returns the updated key (no plaintext).

{
  "id": "3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33",
  "name": "Renamed Bot",
  "keyPrefix": "owa_k1_a1b2",
  "role": "viewer",
  "allowedIps": ["203.0.113.5"],
  "isActive": true,
  "expiresAt": "2028-01-01T00:00:00.000Z",
  "usageCount": 42,
  "createdAt": "2026-06-01T10:00:00.000Z"
}

Errors: 400 validation (incl. forbidNonWhitelisted for unknown fields such as isActive) · 401 missing/invalid key · 403 key role below ADMIN · 404 not found

POST /api/auth/api-keys/:id/revoke

Revoke (deactivate) an API key without deleting it. No request body required.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string (uuid)	API key id.

Response 200 — ApiKeyResponseDto

Sets isActive to false and returns the key. Default POST status 200 (no @HttpCode override). After revoke, the key fails validation with 401 "API key is revoked".

{
  "id": "3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33",
  "name": "Production Bot",
  "keyPrefix": "owa_k1_a1b2",
  "role": "operator",
  "isActive": false,
  "usageCount": 42,
  "createdAt": "2026-06-01T10:00:00.000Z"
}

Errors: 401 missing/invalid key · 403 key role below ADMIN · 404 not found

DELETE /api/auth/api-keys/:id

Permanently delete an API key (hard delete). Also drops any un-flushed usage accumulator.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string (uuid)	API key id.

Response 204

@HttpCode(204) — no response body.

Errors: 401 missing/invalid key · 403 key role below ADMIN · 404 "API key with id '<id>' not found"

POST /api/auth/validate

Validate the supplied X-API-Key and report its validity and role.

Auth: API key (any valid role — VIEWER+)

The key is read from the X-API-Key header, not the body; send an empty body. This route sits behind the global guard (it is not @Public), so a missing/invalid/revoked/expired key is rejected with 401 at the guard before the handler runs. On success it returns the caller's role.

Response 200

{ "valid": true, "role": "operator" }

Errors: 401 missing/invalid/revoked/expired key (raised by the global guard before the handler)

Implemented by AuthValidateController (@Controller('auth')), sharing the same /api/auth base.

6.4.10 System (Health, Metrics, Stats, Settings)

System endpoints expose operational status, Prometheus metrics, aggregate statistics, and runtime settings. Health and metrics use non-standard auth (public / Bearer token); stats and settings use the API key, with several routes gated to ADMIN.

GET /api/health

Basic health check returning status, the current timestamp, and the running app version.

Auth: public

Response 200

{ "status": "ok", "timestamp": "2026-06-25T12:34:56.789Z", "version": "0.7.3" }

Notes: timestamp is an ISO-8601 string (new Date().toISOString()). version is read from package.json at module load. Exempt from rate limiting (@SkipThrottle).

GET /api/health/live

Kubernetes liveness probe — returns a deliberately static body reflecting only process liveness; it does NOT probe dependencies.

Auth: public

Response 200

{ "status": "ok" }

Notes: always { "status": "ok" }. Intentionally static so a transient dependency outage does not trigger a pod kill. The handler never returns a non-200.

GET /api/health/ready

Readiness probe — verifies the main (auth/audit) and data TypeORM datasources respond to SELECT 1 (each bounded to a 3000 ms timeout) and reports 503 while the app is draining/shutting down.

Auth: public

Response 200

{
  "status": "ok",
  "details": {
    "mainDatabase": { "status": "up" },
    "dataDatabase": { "status": "up" }
  }
}

Errors: 503 — either datasource fails or exceeds its 3 s SELECT 1 timeout, or the app is shutting down. The handler throws ServiceUnavailableException, so NestJS wraps the custom { status, details } object as the message field:

{
  "statusCode": 503,
  "message": {
    "status": "error",
    "details": { "mainDatabase": { "status": "up" }, "dataDatabase": { "status": "down" } }
  },
  "error": "Service Unavailable"
}

During shutdown the details instead read { "shutdown": { "status": "draining" } }. Probes run in parallel via Promise.all. There is no health/detailed route.

GET /api/metrics

Prometheus exposition scrape of OpenWA process + session + message metrics; gated by a METRICS_TOKEN bearer (disabled when the token is unset).

Auth: Bearer METRICS_TOKEN — Authorization: Bearer <METRICS_TOKEN>. This route is @Public() (it bypasses the X-API-Key guard); access is instead validated inside the service with a constant-time compare. The Bearer prefix is stripped case-insensitively. Hidden from Swagger.

Response 200

Content-Type text/plain; version=0.0.4; charset=utf-8, Cache-Control: no-store. Raw text (no JSON envelope):

# HELP openwa_up 1 if the OpenWA process is running
# TYPE openwa_up gauge
openwa_up 1
# TYPE openwa_process_uptime_seconds gauge
openwa_process_uptime_seconds 3600
# TYPE openwa_process_resident_memory_bytes gauge
openwa_process_resident_memory_bytes 187432960
# TYPE openwa_process_heap_used_bytes gauge
openwa_process_heap_used_bytes 64512000
# TYPE openwa_sessions_total gauge
openwa_sessions_total 3
# TYPE openwa_sessions_active gauge
openwa_sessions_active 2
# TYPE openwa_sessions gauge
openwa_sessions{status="ready"} 2
openwa_sessions{status="disconnected"} 1
# TYPE openwa_messages_total counter
openwa_messages_total{direction="outgoing"} 1280
openwa_messages_total{direction="incoming"} 940
# TYPE openwa_messages_failed_total counter
openwa_messages_failed_total 4

Values come from StatsService.getOverview() plus process.memoryUsage()/process.uptime(). The render is memoized for 5000 ms to avoid re-running the overview query on every scrape.

Errors: 401 — METRICS_TOKEN is configured but the bearer is missing or does not match ({ "statusCode": 401, "message": "Invalid metrics token", "error": "Unauthorized" }) · 404 — METRICS_TOKEN is unset/blank, so the endpoint is disabled ({ "statusCode": 404, "message": "Metrics endpoint is disabled (set METRICS_TOKEN to enable)", "error": "Not Found" }).

GET /api/stats/overview

Get overall cross-session aggregate statistics (sessions by status + message totals + today's counts).

Auth: API key (ADMIN) — deliberately ADMIN-only (global cross-tenant aggregate).

Response 200

{
  "sessions": {
    "active": 2,
    "total": 3,
    "byStatus": { "READY": 2, "DISCONNECTED": 1 }
  },
  "messages": {
    "sent": 1280,
    "received": 940,
    "failed": 4,
    "today": { "sent": 42, "received": 30 }
  }
}

Notes: raw handler return (no envelope). sessions.byStatus is keyed by SessionStatus enum values with per-status counts; sessions.active counts only READY. messages.sent/received are all-time outgoing/incoming COUNTs; failed is the FAILED-status COUNT; today.* are the same counts since local midnight. Side effect: caches the sessions block via CacheService.

Errors: 401 — missing/invalid X-API-Key · 403 — key role below ADMIN.

GET /api/stats/messages

Get message statistics over a period: time series, counts by type, by session, and top chats.

Auth: API key (ADMIN) — cross-session aggregate.

Query parameters

Name	Type	Required	Default	Description
period	'24h' | '7d' | '30d'	No	24h	Window for the report. @IsIn(['24h','7d','30d']) — any other value → 400. Bucket interval is hour for 24h, else day.

Response 200

{
  "timeSeries": [
    { "timestamp": "2026-06-25 10:00:00", "sent": 12, "received": 8 },
    { "timestamp": "2026-06-25 11:00:00", "sent": 20, "received": 14 }
  ],
  "byType": { "chat": 180, "image": 24, "unknown": 3 },
  "bySession": [
    { "sessionId": "9f1c…", "name": "support-line", "sent": 200, "received": 140 }
  ],
  "topChats": [
    { "chatId": "6281234567890@c.us", "messageCount": 320 }
  ]
}

Notes: raw handler return. timeSeries.timestamp is a DB-formatted bucket string — hourly YYYY-MM-DD HH:00:00 for 24h, daily YYYY-MM-DD for 7d/30d — sorted ascending. byType keys are message-type strings (a null type becomes unknown). bySession.name is Unknown when the session is not found. topChats is the top 10 by messageCount DESC. All counts are numbers.

Errors: 400 — period not in the enum, or any non-whitelisted query field (strict whitelist + forbidNonWhitelisted) · 401 — missing/invalid API key · 403 — role below ADMIN.

GET /api/stats/sessions/:sessionId

Get statistics for a single session: identity, message counts, top chats, and 24 h hourly activity.

Auth: API key — any valid key (VIEWER and up); there is no @RequireRole. Note: the handler does NOT verify the key is scoped to this session, so any authenticated key can read any session's stats.

Path parameters

Name	Type	Description
sessionId	string	Session entity id. No format validation; 404 if no session matches.

Response 200

{
  "session": { "id": "9f1c…", "name": "support-line", "status": "ready" },
  "messages": { "sent": 200, "received": 140, "today": 18, "failed": 1 },
  "topChats": [
    { "chatId": "6281234567890@c.us", "count": 64, "lastActive": "2026-06-25 11:42:07" }
  ],
  "hourlyActivity": [
    { "hour": 0, "sent": 0, "received": 0 },
    { "hour": 1, "sent": 3, "received": 2 }
  ]
}

Notes: raw handler return. session.status is the SessionStatus enum value. messages.sent/received are all-time outgoing/incoming COUNTs; today is the total message count since local midnight; failed is the FAILED-status count. topChats is the top 10 by count DESC, with lastActive = MAX(createdAt) as a DB-native datetime string. hourlyActivity always has 24 entries (hour 0..23), missing hours zero-filled, computed over the last 24 h.

Errors: 401 — missing/invalid API key · 404 — session not found (Session not found).

GET /api/settings

Get application settings (environment-derived; general/api/notifications groups).

Auth: API key (ADMIN). Settings expose server configuration, so a VIEWER or session-scoped key is rejected with 403.

Response 200

{
  "general": {
    "apiBaseUrl": "http://localhost:2785",
    "sessionTimeout": 0,
    "autoReconnect": false,
    "debugMode": false
  },
  "api": {
    "rateLimit": 100,
    "rateLimitWindow": 60000,
    "enableDocs": true
  },
  "notifications": {
    "emailEnabled": false,
    "notificationEmail": "",
    "webhookAlerts": true
  }
}

Notes: raw return of an in-memory Settings object built once in the controller constructor from ConfigService (snapshotted at construction, not re-read per request). general.sessionTimeout is floor(webhook.timeout / 60000) minutes; api.rateLimitWindow is in ms; enableDocs/notifications.* are partly hardcoded (enableDocs: true, emailEnabled: false, notificationEmail: '', webhookAlerts: true).

Errors: 401 — missing/invalid X-API-Key · 403 — API key lacks the ADMIN role.

PUT /api/settings

Update settings — intentionally not implemented; always returns 501 (settings are env-derived and read-only at runtime).

Auth: API key (ADMIN)

Request body — none. There is no request DTO; any body is ignored (the exception is thrown before validation matters).

Response 501

{
  "statusCode": 501,
  "message": "Settings are derived from environment configuration and are read-only at runtime. Change the corresponding environment variable and restart the service.",
  "error": "Not Implemented"
}

Notes: the handler unconditionally throws NotImplementedException. Even an ADMIN key always gets 501; there is no success response.

Errors: 401 — missing/invalid key · 403 — key lacks ADMIN · 501 — always (not implemented).

6.4.11 Administration (Infrastructure, Plugins, MCP)

Admin-facing operations: infrastructure status & config, the data/storage migration tooling, plugin lifecycle, and the optional MCP transport. Almost every route is API key (ADMIN); the two exceptions are the public GET /api/infra/health and the POST /mcp JSON-RPC endpoint (see end of section).

Note on the infra/MCP request bodies: the PUT /api/infra/config, POST /api/infra/restart, POST /api/infra/import-data, POST /api/infra/storage/import bodies and the entire POST /mcp envelope are plain TS interfaces, not class-validator DTOs — the global whitelist/forbidNonWhitelisted ValidationPipe does not run on them. Unknown fields pass through silently and no type/constraint checks happen, except the few field-level guards noted per endpoint. Plugin DTOs (InstallFromUrlDto, PluginConfigDto, PluginSessionsDto) are class-validated and reject unknown fields with 400.

---

GET /api/infra/health

Public liveness probe.

Auth: public

Response 200

{ "status": "ok", "timestamp": "2026-06-25T12:00:00.000Z" }

---

GET /api/infra/status

Aggregate infrastructure status (database, Redis, queue, storage, engine).

Auth: API key (ADMIN)

Response 200

{
  "database": { "connected": true, "type": "sqlite", "host": "" },
  "redis": { "enabled": false, "connected": false, "host": "localhost", "port": 6379 },
  "queue": {
    "enabled": false,
    "webhooks": { "pending": 0, "completed": 0, "failed": 0 }
  },
  "storage": { "type": "local", "path": "./data/media" },
  "engine": {
    "type": "whatsapp-web.js",
    "headless": true,
    "sessionDataPath": "./data/sessions",
    "browserArgs": "--no-sandbox --disable-gpu"
  }
}

The queue.webhooks counters are live BullMQ job counts (pending = waiting + active + delayed; plus completed/failed), degrading to zeros when the queue is disabled or Redis is unreachable. redis.connected is a live probe. storage only ever returns type+path here (no bucket).

Errors: 401 missing/invalid key · 403 key role < ADMIN

---

GET /api/infra/engines

List available WhatsApp engine plugins.

Auth: API key (ADMIN)

Response 200 — bare array

[
  {
    "id": "whatsapp-web.js",
    "name": "WhatsApp Web.js",
    "enabled": true,
    "features": ["send", "receive", "media", "groups"],
    "library": { "name": "whatsapp-web.js", "version": "1.34.7" }
  }
]

library is optional and may be omitted per engine.

Errors: 401 · 403

---

GET /api/infra/engines/current

Get the currently active engine type.

Auth: API key (ADMIN)

Response 200

{ "engineType": "whatsapp-web.js" }

Errors: 401 · 403

---

GET /api/infra/config

Read the saved infrastructure config from data/.env.generated (used to hydrate the dashboard form). Secrets are never returned — only *Set/*CredentialsSet booleans indicate that a secret is stored.

Auth: API key (ADMIN)

Response 200 — SavedConfigResponse

{
  "database": {
    "type": "sqlite", "builtIn": false, "host": "", "port": "",
    "username": "", "database": "", "poolSize": 10,
    "sslEnabled": false, "sslRejectUnauthorized": true, "passwordSet": false
  },
  "redis": { "enabled": false, "builtIn": false, "host": "", "port": "", "passwordSet": false },
  "queue": { "enabled": false },
  "storage": {
    "type": "local", "builtIn": false, "localPath": "./data/media",
    "s3Bucket": "", "s3Region": "", "s3Endpoint": "", "s3CredentialsSet": false
  },
  "engine": {
    "type": "whatsapp-web.js", "headless": true,
    "sessionDataPath": "./data/sessions", "browserArgs": "--no-sandbox --disable-gpu"
  }
}

When data/.env.generated does not exist, empty-string/default values are returned (poolSize=10, sslRejectUnauthorized=true, engine.type='whatsapp-web.js', headless=true).

Errors: 401 · 403

---

PUT /api/infra/config

Merge-save infrastructure config to data/.env.generated (a 0600 secret file). A partial payload preserves untouched keys; empty/omitted secret fields keep the existing stored secret.

Auth: API key (ADMIN)

Request body — SaveConfigDto (plain interface, not class-validated; only engine.type and CR/LF safety are enforced)

Field	Type	Required	Constraints	Description
database	object	No	—	DB section (see nested)
database.type	'sqlite' | 'postgres'	No	—	sqlite drops stale postgres keys; postgres writes connection keys
database.builtIn	boolean	No	—	When true+postgres, forces the bundled postgres container creds + pushes postgres Docker profile
database.host / .port / .username / .database	string	No	port is a string	External postgres connection (defaults localhost/5432/postgres/openwa)
database.password	string	No	secret	Empty/omitted keeps the existing stored secret
database.poolSize	number	No	—	Default 10
database.sslEnabled	boolean	No	—	Default false
database.sslRejectUnauthorized	boolean	No	—	Only written when sslEnabled is true; default true
redis.enabled / .builtIn	boolean	No	—	builtIn+enabled forces redis container + profile
redis.host / .port	string	No	port is a string	Defaults localhost/6379
redis.username	string	No	—	Redis ACL username
redis.password	string	No	secret	Empty keeps existing
queue.enabled	boolean	No	—	Writes QUEUE_ENABLED
storage.type	'local' | 's3'	No	—	local drops stale S3 keys; s3 drops STORAGE_LOCAL_PATH
storage.builtIn	boolean	No	—	true+s3 uses bundled MinIO defaults + pushes minio profile
storage.localPath	string	No	—	Default ./data/media
storage.s3Bucket / .s3Region / .s3Endpoint	string	No	—	External S3
storage.s3AccessKey / .s3SecretKey	string	No	secret	Empty keeps existing
engine.type	string	No	must be a known engine id, else 400	The only validated field in the body
engine.headless	boolean	No	—	Default true; saved as PUPPETEER_HEADLESS
engine.sessionDataPath	string	No	—	Default ./data/sessions
engine.browserArgs	string	No	—	Saved as PUPPETEER_ARGS

{
  "database": { "type": "postgres", "builtIn": false, "host": "db.example.com", "port": "5432", "username": "openwa", "password": "s3cret", "database": "openwa", "poolSize": 10, "sslEnabled": true, "sslRejectUnauthorized": false },
  "redis": { "enabled": true, "builtIn": true },
  "queue": { "enabled": true },
  "storage": { "type": "s3", "builtIn": false, "s3Bucket": "my-bucket", "s3Region": "ap-southeast-1", "s3AccessKey": "AKIA...", "s3SecretKey": "...", "s3Endpoint": "https://s3.example.com" },
  "engine": { "type": "whatsapp-web.js", "headless": true, "sessionDataPath": "./data/sessions", "browserArgs": "--no-sandbox --disable-gpu" }
}

Response 200

{ "message": "Configuration saved. Server restart required.", "saved": true, "envPath": "data/.env.generated", "profiles": ["postgres", "redis"] }

This route always returns HTTP 200, even on failure: write/IO errors are caught and returned as { "saved": false, "envPath": "", "profiles": [], "message": "Failed to save configuration: …" }. The only true 400 cases are an unknown engine.type or any value containing \r/\n. profiles lists newly-required Docker profiles.

Errors: 400 unknown engine.type / CR-LF in a value · 401 · 403

---

POST /api/infra/restart

Request a graceful server restart, optionally orchestrating Docker profiles (add/remove services). Schedules process shutdown as a side-effect.

Auth: API key (ADMIN)

Request body — optional inline type (plain interface, not class-validated)

Field	Type	Required	Default	Description
profiles	string[]	No	[]	Docker profiles to enable/start (e.g. postgres, redis, minio)
profilesToRemove	string[]	No	[]	Docker profiles whose containers should be stopped/removed

{ "profiles": ["postgres", "redis"], "profilesToRemove": ["minio"] }

Response 200

{
  "message": "Restarting…",
  "restarting": true,
  "profiles": ["postgres", "redis"],
  "profilesToRemove": ["minio"],
  "estimatedTime": 48
}

estimatedTime (seconds) = base 15 + 20/postgres + 13/redis + 15/minio + 5/removal. orchestration is present only when Docker is available and profiles is non-empty; removal only when Docker is available and profilesToRemove is non-empty. Without Docker, a data/.orchestration-request.json signal file is written instead. After responding, shutdownService.shutdown() runs (default ~3s grace); readiness returns 503 during drain.

Errors: 401 · 403

---

GET /api/infra/export-data

Export every row from the Data DB (sessions, webhooks, messages, batches, templates, Baileys stored messages) as JSON for migration. Read-only, but runs raw SELECT * on the data DataSource.

Auth: API key (ADMIN)

Response 200

{
  "exportedAt": "2026-06-25T12:00:00.000Z",
  "dataDbType": "sqlite",
  "tables": {
    "sessions": [ { "id": "s1", "name": "main", "status": "READY", "phone": "15551234567", "pushName": "Me", "config": {}, "proxyUrl": null, "proxyType": null, "connectedAt": "2026-06-25T00:00:00.000Z", "lastActiveAt": "2026-06-25T00:00:00.000Z", "createdAt": "2026-06-25T00:00:00.000Z", "updatedAt": "2026-06-25T00:00:00.000Z" } ],
    "webhooks": [],
    "messages": [],
    "messageBatches": [],
    "templates": [],
    "baileysStoredMessages": []
  },
  "counts": { "sessions": 1, "webhooks": 0, "messages": 0, "messageBatches": 0, "templates": 0, "baileysStoredMessages": 0 }
}

Rows are raw DB column shapes (e.g. messageBatches rows use snake_case columns: batch_id, session_id, current_index, created_at, …). webhooks rows include secret in cleartext. messages/messageBatches/templates/baileysStoredMessages default to [] if their table is missing; sessions/webhooks are not try-wrapped, so a hard DB error there yields 500.

Errors: 401 · 403 · 500 DB error

---

POST /api/infra/import-data

Replace all Data DB rows with the supplied export. Destructive and transactional (all-or-nothing).

Auth: API key (ADMIN)

Request body — inline { tables: Partial<MigrationTables> } (plain interface, not class-validated)

Field	Type	Required	Description
tables	object	Yes	Container of per-table row arrays. Accessing data.tables directly means a missing/null value throws 500
tables.sessions	SessionRow[]	No	Inserted first; skipped if absent/empty
tables.webhooks	WebhookRow[]	No	Includes secret
tables.messages	MessageRow[]	No	—
tables.messageBatches	MessageBatchRow[]	No	snake_case columns
tables.templates	TemplateRow[]	No	—
tables.baileysStoredMessages	BaileysStoredMessageRow[]	No	—

{
  "tables": {
    "sessions": [ { "id": "s1", "name": "main", "status": "READY", "phone": "15551234567", "pushName": "Me", "config": {}, "proxyUrl": null, "proxyType": null, "connectedAt": "2026-06-25T00:00:00.000Z", "lastActiveAt": "2026-06-25T00:00:00.000Z", "createdAt": "2026-06-25T00:00:00.000Z", "updatedAt": "2026-06-25T00:00:00.000Z" } ],
    "webhooks": [], "messages": [], "messageBatches": [], "templates": [], "baileysStoredMessages": []
  }
}

Response 200

{
  "imported": true,
  "counts": { "sessions": 1, "webhooks": 0, "messages": 0, "messageBatches": 0, "templates": 0, "baileysStoredMessages": 0 },
  "warnings": []
}

Inside a transaction it DELETEs all rows from webhooks/messages/message_batches/templates/baileys_stored_messages/sessions, then re-inserts. If any row insert fails, warnings is non-empty, the transaction is rolled back, and imported:false is returned (counts reflect rows inserted before the failure). JSON object/array fields are auto-stringified before insert.

Errors: 401 · 403 · 500 tables missing/null or unrecoverable DB error

---

GET /api/infra/storage/files/count

File count and total size in the active storage backend.

Auth: API key (ADMIN)

Response 200

{ "storageType": "local", "count": 128, "sizeBytes": 5242880, "sizeMB": "5.00" }

Errors: 401 · 403 · 500

---

GET /api/infra/storage/export

Export all storage files into a tar.gz under data/exports and return its server-side path (not a download stream).

Auth: API key (ADMIN)

Response 200

{ "message": "Storage export completed", "download": "data/exports/storage-export-1750000000000-abc.tar.gz" }

download is a server filesystem path — feed it back to POST /api/infra/storage/import. The archive is auto-deleted after STORAGE_EXPORT_TTL_MS (default 1h).

Errors: 401 · 403 · 500

---

POST /api/infra/storage/import

Import storage files from a tar.gz located inside the data/ directory.

Auth: API key (ADMIN)

Request body — inline { filePath: string } (plain interface, not class-validated; path-safety enforced manually)

Field	Type	Required	Constraints	Description
filePath	string	Yes	Must resolve inside <cwd>/data and exist on disk, else 400	Path to the archive (constrained to data/ to block traversal)

{ "filePath": "./data/exports/storage-export-1750000000000-abc.tar.gz" }

Response 200

{ "imported": true, "count": 128, "storageType": "local" }

Errors: 400 missing/out-of-data//not-found path · 401 · 403 · 500

---

GET /api/plugins

List all loaded plugins (built-in + installed), with secret config values redacted.

Auth: API key (ADMIN)

Response 200 — PluginDto[] (bare array, [] if none)

[
  {
    "id": "chat-flow",
    "name": "Chat Flow",
    "version": "1.0.0",
    "type": "extension",
    "description": "Visual reply flows",
    "author": "openwa-plugins",
    "status": "enabled",
    "config": { "apiKey": "********" },
    "builtIn": false,
    "provides": ["message-hook"],
    "sessionScoped": true,
    "activeSessions": ["*"],
    "loadedAt": "2026-06-25T00:00:00.000Z",
    "enabledAt": "2026-06-25T00:01:00.000Z"
  }
]

type is one of engine | storage | queue | auth | extension; status is installed | enabled | disabled | error. activeSessions: ["*"] means all sessions. Optional fields: configSchema, configUi, i18n, sessionConfig (secrets redacted), error.

Errors: 401 · 403

---

GET /api/plugins/catalog

List the remote plugin catalog annotated with this instance's install state. (Declared before :id so catalog is not captured as an id.)

Auth: API key (ADMIN)

Response 200 — bare array

[
  {
    "id": "group-translate",
    "name": "Group Translate",
    "version": "1.2.0",
    "type": "extension",
    "description": "Auto-translate group messages",
    "author": "openwa-plugins",
    "download": "https://github.com/openwa-plugins/group-translate/releases/download/v1.2.0/group-translate.zip",
    "installed": true,
    "installedVersion": "1.1.0",
    "updateAvailable": true
  }
]

Returns [] when no plugins.catalogUrl is configured.

Errors: 400 catalog fetch failed / not a JSON array · 401 · 403

---

GET /api/plugins/:id

Get a single plugin by id.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Response 200 — single PluginDto (same shape as the list element, secrets redacted).

Errors: 401 · 403 · 404 Plugin {id} not found

---

GET /api/plugins/:id/config-ui

Serve a plugin's sandboxed config-UI entry HTML (for an iframe srcdoc).

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Response 200 — raw HTML (not JSON). Headers: Content-Type: text/html; charset=utf-8, Content-Security-Policy: sandbox, X-Content-Type-Options: nosniff.

Errors: 401 · 403 · 404 plugin missing, no configUi.entry, file missing, or containment-check failure

---

GET /api/plugins/:id/health

Check a plugin's health (delegates to the loader / sandboxed workers).

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Response 200

{ "healthy": true }

Internal failures are reported in-band as { "healthy": false, "message": "…" } with HTTP 200.

Errors: 401 · 403 · 404 unknown id

---

POST /api/plugins/install

Install a plugin from an uploaded .zip package.

Auth: API key (ADMIN)

Request body — multipart/form-data (no DTO)

Field	Type	Required	Constraints	Description
file	binary (.zip)	Yes	≤ 5 MB; must contain a valid plugin manifest	Form field name is literally file

Response 201 — the newly installed PluginDto.

Errors: 400 no file / invalid package / install failed · 401 · 403 · 409 plugin id or directory already exists

---

POST /api/plugins/install-url

Install a plugin by downloading its .zip from an HTTP(S) URL (SSRF-guarded fetch: host validated, redirects refused, size-capped at plugins.downloadMaxBytes, default 5 MB).

Auth: API key (ADMIN)

Request body — InstallFromUrlDto (class-validated; extra fields → 400)

Field	Type	Required	Constraints	Description
url	string	Yes	@IsUrl({ protocols:['http','https'], require_protocol:true })	Absolute http(s) URL of the package

{ "url": "https://github.com/openwa-plugins/chat-flow/releases/download/v1.0.0/chat-flow.zip" }

Response 201 — the newly installed PluginDto.

Errors: 400 invalid URL / download or package invalid · 401 · 403 · 409 already installed

---

POST /api/plugins/:id/enable

Enable a plugin.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Response 200

{ "success": true, "message": "Plugin enabled successfully" }

Enable failures are returned in-band as { "success": false, "message": "…" } (still HTTP 200).

Errors: 401 · 403 · 404 unknown id

---

POST /api/plugins/:id/disable

Disable a plugin.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Response 200

{ "success": true, "message": "Plugin disabled successfully" }

Errors: 401 · 403 · 404 unknown id

---

PUT /api/plugins/:id/config

Update a plugin's base configuration object.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Request body — PluginConfigDto (class-validated; body must be exactly {config:{…}})

Field	Type	Required	Constraints	Description
config	object	Yes	@IsObject()	Whole config object. Masked/sentinel secret values mean "unchanged" and are restored from the stored config

{ "config": { "apiKey": "sk-...", "replyDelayMs": 1500 } }

Response 200

{ "success": true, "message": "Plugin configuration updated" }

Update failures are returned in-band as { "success": false, "message": "…" } (HTTP 200).

Errors: 400 extra top-level field · 401 · 403 · 404 unknown id

---

PUT /api/plugins/:id/config/:sessionId

Set (or clear) a plugin config override for a specific session.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id
sessionId	string	Session the override applies to

Request body — PluginConfigDto

Field	Type	Required	Constraints	Description
config	object	Yes	@IsObject()	Per-session override slice. Empty {} clears the override (falls back to base config). Masked secrets restored from the existing per-session value

{ "config": { "replyDelayMs": 3000 } }

Response 200

{ "success": true, "message": "Plugin configuration for session session-1 updated" }

Errors: 400 plugin is global (not session-scoped) / extra field · 401 · 403 · 404 unknown id

---

PUT /api/plugins/:id/sessions

Set which sessions a session-scoped plugin is activated for.

Auth: API key (ADMIN) · Scope: session-scoped (the key's allowedSessions is enforced)

Path parameters

Name	Type	Description
id	string	Plugin id

Request body — PluginSessionsDto (class-validated)

Field	Type	Required	Constraints	Description
sessions	string[]	Yes	@IsArray(), @IsString({ each:true })	Session ids to activate for. ["*"] = all, [] = none

{ "sessions": ["*"] }

Response 200 — the updated PluginDto (reflecting the new activeSessions).

A session-restricted key requesting "*" or out-of-scope sessions gets 403 API key not authorized for session(s): ….

Errors: 400 plugin is global · 401 · 403 key not authorized for requested sessions · 404 unknown id

---

POST /api/plugins/:id/update

Update an installed plugin in place from a URL, preserving config + enabled state (old directory backed up and restored on failure).

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id (must match the package's manifest id)

Request body — InstallFromUrlDto (class-validated)

Field	Type	Required	Constraints	Description
url	string	Yes	@IsUrl({ protocols:['http','https'], require_protocol:true })	Absolute http(s) URL of the new .zip (SSRF-guarded download)

{ "url": "https://example.com/plugins/chat-flow-1.1.0.zip" }

Response 201 — the updated PluginDto.

Errors: 400 download/package invalid, manifest id mismatch, or built-in plugin · 401 · 403 · 404 unknown id

---

DELETE /api/plugins/:id

Uninstall a plugin and delete its files. Built-in plugins are protected.

Auth: API key (ADMIN)

Path parameters

Name	Type	Description
id	string	Plugin id

Response 200

{ "success": true, "message": "Plugin uninstalled successfully" }

Note: this DELETE returns 200 with a body (not the usual 204).

Errors: 400 cannot uninstall (e.g. built-in) · 401 · 403 · 404 unknown id

---

POST /mcp

MCP Streamable-HTTP / JSON-RPC 2.0 transport that exposes the agent-tool registry over the Model Context Protocol. This is a transport, not a REST resource — there is no NestJS controller, no DTO, and no {success,data} shape.

Auth: API key — sent as X-Api-Key: <key> or Authorization: Bearer <key>. Auth is enforced per tool call inside the MCP layer (not by the global Nest guard), so an auth failure surfaces in-band, not as an HTTP 401.

Key facts:

• Path is exactly POST /mcp — no /api prefix. The global api prefix applies only to Nest controllers; this route is mounted straight on Express.
• Gated by MCP_ENABLED=true. When off, the module/route is never mounted and POST /mcp returns 404.
• MCP is read-only by default: only read-tier tools are registered unless you set MCP_READONLY=false to expose write tools. Per-key sliding-window rate limit: MCP_RATE_LIMIT_MAX (default 60) per MCP_RATE_LIMIT_WINDOW_MS (default 60000).
• Stateless transport (no SSE/session id for normal calls).

Request body — JSON-RPC 2.0 envelope (validated by the MCP SDK, not the Nest ValidationPipe)

Field	Type	Required	Description
jsonrpc	string	Yes	Must be "2.0"
id	string | number | null	No	Request id echoed back; null/absent for notifications
method	string	Yes	initialize, tools/list, tools/call, plus MCP lifecycle methods. Unknown → JSON-RPC error -32601
params	object	No	Method-specific. For tools/call: { name, arguments } where arguments must match the tool's zod inputSchema

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "session_send_text", "arguments": { "sessionId": "default", "to": "6281234567890", "text": "Hello from MCP" } } }

Response 200 — JSON-RPC 2.0 envelope

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": { "content": [ { "type": "text", "text": "{\"success\":true,\"messageId\":\"…\"}" } ] }
}

For tools/call the result is an MCP CallToolResult (content array of text or embedded base64 resource items — payloads over 4096 bytes become a resource). Tool-level failures are returned in-band as CallToolResult with isError:true (HTTP stays 200), including missing/invalid API key (name:'UnauthorizedException') and rate-limit hits (message:'MCP rate limit exceeded').

Errors: in-band JSON-RPC errors -32601 (unknown method), -32602 (invalid params / unknown tool), -32700 (parse error), all at HTTP 200 · 500 only if the transport throws before headers are sent · 404 when MCP_ENABLED is not true

The full catalog of MCP tools (names, tiers, schemas) is documented separately — see doc 24, MCP Integration. This section documents only the transport endpoint.

6.4.12 Search

Base path /api/search. Cross-session full-text message search over an open SearchProvider contract; the built-in database full-text provider (PostgreSQL tsvector/GIN, SQLite FTS5) answers by default with zero external dependencies. Search is on by default; set SEARCH_ENABLED=false to remove the route and module entirely (the index is DB-maintained regardless — see 26 - Global Search). Requires at least OPERATOR role.

Auth: API key (≥ OPERATOR) · Scope: session-scoped — a scoped key's allowedSessions is injected server-side from the key (never from the query), so a scoped key cannot broaden its reach; an ADMIN / null-allowlist key searches all sessions.

GET /api/search

Search messages across sessions (active search provider).

Query parameters

Name	Type	Required	Default	Description
q	string	Yes	—	Search term. Must be non-empty after trim; whitespace-only is rejected with 400. Passed to the active provider's native full-text matcher.
sessionId	string	No	—	Restrict to a single session id (intersected with the key's allowedSessions scope).
chatId	string	No	—	Restrict to a single chat id.
direction	enum (incoming | outgoing)	No	—	Filter by message direction.
type	string	No	—	Filter by stored message type (e.g. text, image, video). Compared against messages.type; not an enum validation, any string is accepted and unmatched values simply return no hits.
from	string	No	—	Filter by sender.
dateFrom	integer (epoch ms)	No	—	Inclusive lower bound on timestamp. A non-numeric value is rejected with 400.
dateTo	integer (epoch ms)	No	—	Inclusive upper bound on timestamp. A non-numeric value is rejected with 400.
limit	integer (≥ 1)	No	50	Max hits to return. Clamped to SEARCH_LIMIT_MAX (default 100). A non-numeric value is rejected with 400.
offset	integer (≥ 0)	No	0	Pagination offset. A non-numeric value is rejected with 400.

Response 200 — SearchResults

{
  "hits": [
    {
      "messageId": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
      "waMessageId": "true_62812...@c.us_3A...",
      "sessionId": "a1b2c3d4-...",
      "chatId": "6281234567890@c.us",
      "body": "full original message body...",
      "snippet": "...order <mark>confirmed</mark> for tomorrow…",
      "timestamp": 1751904000000,
      "type": "text",
      "direction": "incoming",
      "from": "6281234567890@c.us",
      "score": 0.075
    }
  ],
  "total": 23,
  "tookMs": 6,
  "provider": "builtin-fts"
}

• snippet is an XSS-safe text excerpt with <mark>/</mark> highlight markers around the matched term (both dialects emit the same markers). Render it as text, never as HTML.
• total is an exact count for pagination, computed lazily only when the returned page could be full.
• provider names which backend answered (e.g. builtin-fts); it is the registered SearchProvider id, so it changes when a plugin backend is selected via SEARCH_PROVIDER.
• score is optional and provider-specific (rank ordering is stable within a provider; cross-provider scores are not comparable).

Errors: 400 empty/whitespace q, a non-numeric dateFrom/dateTo/limit/offset, or a malformed SQLite FTS5 query (unbalanced quote/paren, bare operator) — Postgres's websearch_to_tsquery is tolerant and has no equivalent · 401 missing/invalid X-API-Key · 403 key role below OPERATOR · 501 no search provider configured (including a non-FTS5 SQLite build, where the provider is absent) · 503 active provider unhealthy (reserved: the built-in provider does not return it; it is the contract surface for a future plugin provider whose search() throws ServiceUnavailableException).

Scoping is authoritative: a scoped API key's allowedSessions is applied server-side and cannot be overridden via the query — there is no sessionIds query parameter, and SearchService overwrites any session scope at the provider boundary.

6.5 Real-time API (WebSocket)

Live events are delivered over a Socket.IO connection (not a raw WebSocket). The server mounts a single Socket.IO namespace, /events, on the same port as the REST API. There are no REST routes in this module.

Connecting

Point a Socket.IO client at <host>:2785 with path-less namespace /events:

ws://<host>:2785/events      (or wss:// behind TLS)

The client must authenticate during the Socket.IO handshake. Two sources are accepted, in this precedence order:

1. Handshake auth (recommended) — io(url, { auth: { apiKey } }). Not written to URLs or access logs.
2. Header — x-api-key: <key>.

The former ?apiKey=<key> query fallback was removed — it leaked the credential into proxy/access logs. Pass the key via the handshake auth field or the x-api-key header only.

If no key is supplied, or validation fails, the server emits an error message (code: "UNAUTHORIZED") on the message event and immediately disconnects the socket. CORS for the namespace reuses the HTTP CORS_ORIGINS policy (dev allows any origin; production uses the allowlist).

Protocol — client → server

All client commands are sent on the Socket.IO event named message using a single flat envelope:

{ type, sessionId, events, requestId }

Field	Type	Applies to	Description
type	"subscribe" | "unsubscribe" | "ping"	all	Command discriminator.
sessionId	string	subscribe, unsubscribe	A session id, or "*" for all sessions.
events	string[]	subscribe	Event names to subscribe to, or ["*"] for all.
requestId	string (optional)	all	Echoed back on the matching server reply for correlation.

A ping carries only { type: "ping", requestId? }.

Protocol — server → client

All server replies and pushed events also arrive on the Socket.IO event named message.

Command acknowledgements are flat and include an ISO-8601 timestamp:

{ "type": "subscribed", "sessionId": "main", "events": ["message.received", "session.status"], "requestId": "r1", "timestamp": "2026-06-25T10:00:00.000Z" }

{ "type": "unsubscribed", "sessionId": "main", "requestId": "r2", "timestamp": "2026-06-25T10:00:01.000Z" }

{ "type": "pong", "requestId": "r3", "timestamp": "2026-06-25T10:00:02.000Z" }

{ "type": "error", "code": "FORBIDDEN_SESSION", "message": "API key is not authorized for this session", "requestId": "r1", "timestamp": "2026-06-25T10:00:00.000Z" }

Live events are pushed as a nested envelope (note: data is under payload, and there is no requestId):

{
  "type": "event",
  "timestamp": "2026-06-25T10:00:05.000Z",
  "payload": {
    "event": "message.received",
    "sessionId": "main",
    "data": { "id": "ABCD1234", "from": "6281234567890@c.us", "body": "hi", "timestamp": 1750000000 }
  }
}

Error code values include UNAUTHORIZED, INVALID_MESSAGE, INVALID_SESSION, INVALID_EVENTS, and FORBIDDEN_SESSION.

Subscribable events

events accepts the wildcard "*" (all of the below) or any of these exact names:

message.received
message.sent
message.ack
message.revoked
message.reaction
session.status
session.qr
session.authenticated
session.disconnected

A subscribe request whose events array contains no recognized name (after filtering) is rejected with INVALID_EVENTS. Unknown names mixed with valid ones are silently dropped; the subscribed reply echoes only the accepted events.

group.* events are NOT subscribable on the socket. They have no engine emit source and are never delivered over Socket.IO (they remain reserved only on the webhook side).

Wildcards and scoping

• sessionId: "*" subscribes to every session; events: ["*"] subscribes to every subscribable event. They combine (e.g. "*" + ["*"] = every event of every session).
• The API key is re-validated on every subscribe (not just at connect), so a key revoked or expired mid-connection is caught — the server replies UNAUTHORIZED and disconnects.
• Per-key session scope is enforced against the fresh key: a key restricted via allowedSessions may NOT subscribe to "*" and may NOT subscribe to a session outside its allowlist — either is rejected with FORBIDDEN_SESSION. An unrestricted key (no allowedSessions) may subscribe to anything, including "*".

Example (socket.io-client)

import { io } from 'socket.io-client';

const socket = io('ws://localhost:2785/events', {
  auth: { apiKey: process.env.OPENWA_API_KEY },
});

socket.on('connect', () => {
  socket.emit('message', {
    type: 'subscribe',
    sessionId: 'main',
    events: ['message.received', 'message.ack', 'session.status'],
    requestId: 'sub-1',
  });
});

socket.on('message', (msg) => {
  if (msg.type === 'event') {
    console.log(`[${msg.payload.event}]`, msg.payload.sessionId, msg.payload.data);
  } else {
    console.log('reply:', msg); // subscribed | unsubscribed | pong | error
  }
});

6.6 Webhook Events & Delivery Semantics

Every registered webhook receives an HTTP POST with a JSON body of this shape:

{
  "event": "message.received",
  "timestamp": "2026-02-02T10:00:00.000Z",
  "sessionId": "my-session",
  "idempotencyKey": "msg_my-session_3EB0ABC123",
  "deliveryId": "dlv_550e8400-e29b-41d4-a716-446655440000",
  "data": { }
}

event, timestamp (ISO-8601 dispatch time), sessionId, idempotencyKey, and deliveryId are always present; data holds the event-specific payload. The same values are mirrored into request headers (below). The HMAC signature is not in the body — it travels in the X-OpenWA-Signature header.

Event catalog

These are the events OpenWA actually emits. A webhook is registered with an events list; an event is delivered to a webhook when its events array includes the event name or "*".

Event	When it fires	data payload sketch
message.received	An inbound message arrives	The full message object: id, from, to, body, type, timestamp (epoch seconds), isGroup, hasMedia, contact{…} (plus optional senderPhone for @lid senders)
message.sent	An outbound message is created/sent from this session	Same message object shape as message.received
message.ack	A delivery/read receipt updates an outbound message	{ id, messageId, status, ack } — status is the canonical state (pending/sent/delivered/read/failed); ack is the deprecated legacy integer derived from it
message.failed	A receipt resolves to failed (dispatched in addition to message.ack)	{ id, messageId, status: "failed", ack: -1 }
message.revoked	A message is deleted/recalled	{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp } — reconcile on revokedId (the original deleted message's id), falling back to id. On whatsapp-web.js id is the revocation notification (a distinct message that won't match a stored id) and revokedId may be absent when the original isn't cached locally; on Baileys the two coincide
message.reaction	A reaction is added, changed, or removed	{ messageId, chatId, reaction, senderId, reactions } — reactions is the post-apply { senderId: emoji } snapshot; reaction is empty when removed
session.qr	A new pairing QR is generated	{ sessionId, qr } (raw QR string)
session.authenticated	The session pairs and becomes ready	{ sessionId, phone, pushName }
session.disconnected	The session disconnects	{ sessionId, reason }
session.status	The session status transitions	{ sessionId, status } where status is one of created / initializing / qr_ready / authenticating / ready / disconnected / failed

STORE_EPHEMERAL_MESSAGES=false affects message.received. When STORE_EPHEMERAL_MESSAGES is set to false, incoming disappearing messages (those with ephemeralDuration > 0) are not persisted nor dispatched — no DB insert, no webhook delivery, and no websocket event. Downstream consumers and the dashboard both stop seeing them. Default is true (backward compatible — store and dispatch everything).

Reserved but not emitted. group.join, group.leave, and group.update are accepted in a webhook's events list (and have reserved idempotency-key formats), but no code path currently emits them — registering for them is harmless but they will never be delivered. Likewise there is no contact.update or presence.update event.

Delivery semantics — at-least-once

Webhook delivery is at-least-once. A consumer can legitimately receive the same logical event more than once because:

• The underlying WhatsApp engine can re-fire an event for a single message.
• A failed delivery (non-2xx response, timeout, or network error) is retried.

Design your handler to be idempotent, keyed on the X-OpenWA-Idempotency-Key header (see below). As a server-side safety net, OpenWA de-duplicates inbound message.received before dispatch (a re-fired event for an already-persisted message is dropped), so one webhook normally sees each inbound message once — but this is best-effort defense-in-depth and does not remove the need for consumer-side idempotency.

HMAC signature

When a webhook is registered with a secret, each delivery carries:

X-OpenWA-Signature: sha256=<hex>

The hex is an HMAC-SHA256 computed over the raw JSON request body (exactly the bytes sent) using the webhook's secret. Verify by recomputing over the raw body — not over a re-serialized parse — and compare in constant time:

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

If no secret is configured the X-OpenWA-Signature header is omitted entirely.

Idempotency & delivery headers

Every delivery includes:

Header	Meaning
X-OpenWA-Event	The event name (mirrors event)
X-OpenWA-Idempotency-Key	Content-derived key; stable across retries of the same occurrence — dedupe on this
X-OpenWA-Delivery-Id	A fresh dlv_<uuid> generated per delivery (differs per retry and per webhook) — for tracing, not dedup
X-OpenWA-Retry-Count	Retry attempt number (0 = first attempt)
X-OpenWA-Signature	HMAC (only when a secret is set)

Idempotency key derivation. The key is content-derived so duplicates of the same logical event collapse to one value:

• message.received / message.sent: msg_{sessionId}_{messageId}
• message.ack: ack_{sessionId}_{messageId}_{status}
• message.failed: failed_{sessionId}_{messageId}_{status}
• message.revoked: rev_{sessionId}_{messageId}
• message.reaction: react_{sessionId}_{messageId}_{senderId}_{occurredAt}
• session.qr: qr_{sessionId}_{hash(qr)}
• session.status: sess_{sessionId}_{status}_{occurredAt}
• session.authenticated: auth_{sessionId}_{hash(data)}_{occurredAt}
• session.disconnected: disc_{sessionId}_{hash(reason)}_{occurredAt}

Recurring lifecycle events (and message.reaction) carry the same content across occurrences — the same phone on every reconnect, a constant disconnect reason, a re-applied emoji — so they are salted with an occurredAt timestamp captured once per dispatch and reused across that dispatch's retries. This gives distinct occurrences distinct keys while keeping retries of one occurrence stable. Message keys are scoped by sessionId because WhatsApp message ids are unique per account, not globally.

Retries with exponential backoff

When the queue is enabled, a non-2xx response, timeout (WEBHOOK_TIMEOUT, default 10000 ms), or network error schedules a retry. The number of attempts comes from the webhook's retryCount (default 3) and the delay grows exponentially from a base of WEBHOOK_RETRY_DELAY (default 5000 ms). Each retry reuses the same idempotencyKey and increments X-OpenWA-Retry-Count. If Redis/BullMQ rejects the initial enqueue, OpenWA logs a webhook:error hook event and falls back to direct delivery with the same inline retry budget. When the queue is disabled, delivery is direct with the same retry budget applied inline.

SSRF guard on registration

Webhook URLs are validated at registration time, not just at delivery. When SSRF protection is enabled (the default), creating or updating a webhook with a URL that resolves to a private/internal/loopback address is rejected synchronously with 400 Bad Request instead of failing silently later at delivery. The SSRF_ALLOWED_HOSTS escape-hatch applies equally to registration and delivery. Operator-supplied custom headers that target reserved names (Content-Type or any X-OpenWA-*) are stripped, so a webhook config cannot forge the signature, event, or idempotency headers.