Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

60.1 KB
Raw Blame

07 - API Collection

07.1 Overview

This collection gives a runnable cURL for the primary OpenWA REST endpoints; the complete route list lives in openapi.json at the repository root. The Swagger UI at /api/docs serves the same schema, but it defaults off under NODE_ENV=production — set ENABLE_SWAGGER=true to serve it there. The examples assume two environment variables — set them once and reuse them:

export BASE=http://localhost:2785
export API_KEY=owa_k1_your-api-key-here

(For the metrics endpoint also export METRICS_TOKEN=....)

Authentication

Every request carries the key in the X-API-Key header — REST auth is header-only, an ?apiKey= query value is not accepted. Routes that mutate state need an operator key; API-key and settings management need an admin key. Most read-only routes accept any valid key, but template and webhook reads need operator, plugin reads and infra reads need admin (except GET /api/infra/health, which is public), and the cross-session stats reads — /api/stats/overview and /api/stats/messages — need admin while per-session stats accept any role. Each section states its own requirement. The metrics endpoint uses Authorization: Bearer $METRICS_TOKEN instead.

# the auth header that prefixes nearly every call below
-H "X-API-Key: $API_KEY"

Responses

Responses are the raw payload — no { success, data } envelope. A resource route returns the object directly; most list routes return a bare JSON array, and the object-shaped ones are messages ({ messages, total, unknownTimestampTotal? }), status ({ statuses }), search ({ hits, total, tookMs, provider }), catalog products ({ products, pagination }) and audit ({ data, total }). Errors return the NestJS default shape { "statusCode", "message", "error" }. Add Content-Type: application/json only when sending a body.

Sections

Sessions · Messages · Webhooks · Groups · Contacts · Chats · Labels · Channels · Catalog · Templates · Plugins · Settings · Auth (API Keys) · Health · Infrastructure · Stats · Audit · Metrics · Profile · Search · Media conversion · Events (WebSocket).

07.2 Endpoints

All examples assume BASE and API_KEY are exported (see 07.1). Paths are prefixed with /api.

The :sessionId path segment is always the session UUID returned by POST /api/sessions — never the session name. Session routes (07.3) use :id for that same UUID; everywhere else :id is a different resource's id — a template, webhook, API key or plugin — and never a session. Export the session UUID once alongside the other variables:

export SESSION_ID=8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a

07.3 Sessions

All routes are under $BASE/api/sessions and require X-API-Key: $API_KEY (some require an OPERATOR-role key). Reads come first, then writes.

GET /api/sessions

List all sessions visible to the key. Add limit/offset to page large installations.

curl -X GET "$BASE/api/sessions?limit=100&offset=0" \
  -H "X-API-Key: $API_KEY"

GET /api/sessions/:sessionId

Get a single session by ID.

curl -X GET "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a" \
  -H "X-API-Key: $API_KEY"

GET /api/sessions/:sessionId/qr

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

curl -X GET "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/qr" \
  -H "X-API-Key: $API_KEY"

GET /api/sessions/:sessionId/groups

List groups the session belongs to (paginated).

curl -X GET "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/groups?limit=100&offset=0" \
  -H "X-API-Key: $API_KEY"

GET /api/sessions/:sessionId/chats

List active chats, most-recent first (paginated).

curl -X GET "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats?limit=100&offset=0" \
  -H "X-API-Key: $API_KEY"

GET /api/sessions/stats/overview

Aggregate session statistics for monitoring.

curl -X GET "$BASE/api/sessions/stats/overview" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions

Create a new session (OPERATOR, unscoped key: a key with allowedSessions or allowedChats gets 403).

curl -X POST "$BASE/api/sessions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-bot" }'

With an optional per-session egress proxy — only if your network can't reach WhatsApp directly. The proxy must be a real, reachable host; an unreachable value silently blocks the WhatsApp WebSocket (no QR is ever delivered): on whatsapp-web.js POST /api/sessions/:sessionId/start returns 504 after ~30s; on Baileys the start succeeds and the session keeps retrying.

Setting proxyUrl requires an unscoped ADMIN key; any other key gets 403.

curl -X POST "$BASE/api/sessions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-bot", "proxyUrl": "http://user:[email protected]:8080" }'

GET /api/sessions/:sessionId/proxy

Read a session's masked proxy configuration (credentials never returned).

curl "$BASE/api/sessions/$SESSION_ID/proxy" \
  -H "X-API-Key: $API_KEY"

PATCH /api/sessions/:sessionId/proxy

Update per-session proxy settings (ADMIN, unscoped key). No restart — changes apply on the next start. Send "proxyUrl": null to clear.

curl -X PATCH "$BASE/api/sessions/$SESSION_ID/proxy" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "proxyUrl": "http://user:[email protected]:8080" }'

POST /api/sessions/:sessionId/start

Start a session and initialize the connection (OPERATOR).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/start" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/stop

Stop a session and disconnect (OPERATOR).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/stop" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/logout

Attempt an engine-native unlink of this device, then stop the session (OPERATOR). Requires a running session. A 200 means the unlink operation AND the required local cleanup completed — it is not an independent observation that the handset UI no longer shows the linked device, and a later start needs a fresh QR scan or pairing code. A 502 carries code: 'SESSION_LOGOUT_INCOMPLETE': the session was stopped locally but the logout operation did not complete (no send / no acknowledgement / timeout or transport error / local-cleanup failure); phone is cleared and no success audit is written, so start the session again and retry.

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/logout" \
  -H "X-API-Key: $API_KEY"

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

Force-kill a stuck session (OPERATOR). Returns 400 when the session is not started (there is no live engine to kill).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/force-kill" \
  -H "X-API-Key: $API_KEY"

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

Request an 8-char pairing code via phone number (OPERATOR). On whatsapp-web.js, request a code only for a number you are prepared to re-link: a request for a number that already has a linked session has been observed to end with WhatsApp revoking that device. The gateway answers 409 for a number that is the stored phone of another of its sessions, and cannot see a link made elsewhere. Baileys was not affected in the same tests and is not refused; link by QR when a session of that number must stay up.

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/pairing-code" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "628123456789" }'

POST /api/sessions/:sessionId/presence/subscribe

Subscribe to presence updates (online/typing) for a chat (OPERATOR). Baileys only — whatsapp-web.js answers 501. The subscription belongs to the connection: re-issue it after a restart or reconnect. Updates arrive as the presence.update webhook/socket event.

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/presence/subscribe" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]" }'

GET /api/sessions/:sessionId/presence/:chatId

Read the last presence report received for a chat (any role). Returns 200 with a null body when nothing has been reported yet — presence is held in memory, never persisted.

curl "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/presence/[email protected]" \
  -H "X-API-Key: $API_KEY"

PUT /api/sessions/:sessionId/presence

Set the account's OWN global presence — appear online or offline (OPERATOR, both engines). A successful call is re-applied once each time that engine's connection opens, including a Baileys transient reconnect. It is dropped whenever the gateway replaces the engine (stop, restart, reconnect recovery, watchdog recycle, takeover), so re-issue it after session.status reports ready. On Baileys a 409 on a ready session means the push name has not synced yet and nothing was sent.

curl -X PUT "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/presence" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "available": false }'

POST /api/sessions/:sessionId/chats/read

Mark a chat as read/seen (OPERATOR).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/read" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "messageIds": ["3EB0C767D26B8A3F1A2B"] }'

messageIds is optional and holds up to 100 ids. Omit it and only the newest received message is acknowledged: the one the engine holds in memory, else, on Baileys after a restart, the newest received message the gateway stored. On Baileys that leaves the earlier messages of a burst unread.

POST /api/sessions/:sessionId/chats/unread

Mark a chat as unread (OPERATOR).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/unread" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]" }'

DELETE /api/sessions/:sessionId/chats/:chatId/messages

Delete every message in a chat, keeping the chat.

curl -X DELETE "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/[email protected]/messages" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/chats/archive

Archive or unarchive a chat.

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/archive" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","archive":true}'

POST /api/sessions/:sessionId/chats/mute

Mute a chat until an epoch-milliseconds timestamp (at most 9007199254740991; a larger one is a 400), or send "muteUntil":null to unmute (OPERATOR).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/mute" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","muteUntil":1800000000000}'

POST /api/sessions/:sessionId/chats/pin

Pin a chat to the top of the list, or unpin it (OPERATOR). WhatsApp allows at most three pinned chats.

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/pin" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","pin":true}'

POST /api/sessions/:sessionId/chats/delete

Delete a chat from the chat list (OPERATOR).

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/delete" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]" }'

POST /api/sessions/:sessionId/chats/typing

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

curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/chats/typing" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "state": "typing" }'

DELETE /api/sessions/:sessionId

Delete a session (OPERATOR). Returns 204 with no body.

curl -X DELETE "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a" \
  -H "X-API-Key: $API_KEY"

07.4 Messages

All routes are under /api/sessions/:sessionId/messages. Reads accept any API key; send/write routes need an OPERATOR (or higher) key.

GET /api/sessions/:sessionId/messages

Get persisted message history from the local DB (paginated, filterable).

curl "$BASE/api/sessions/$SESSION_ID/[email protected]&limit=20&offset=0" \
  -H "X-API-Key: $API_KEY"

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

Fetch chat history live from WhatsApp, bypassing the DB. whatsapp-web.js only: Baileys answers 501.

curl "$BASE/api/sessions/$SESSION_ID/messages/[email protected]/history?limit=100&deep=true" \
  -H "X-API-Key: $API_KEY"

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

Get reactions for a message, grouped by emoji. whatsapp-web.js only: Baileys answers 501.

curl "$BASE/api/sessions/$SESSION_ID/messages/[email protected]/[email protected]_3EB0ABCD/reactions" \
  -H "X-API-Key: $API_KEY"

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

Vote on a poll (whatsapp-web.js only).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/vote-poll" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","pollMessageId":"[email protected]_3EB0ABCD","options":["Pizza"]}'

POST /api/sessions/:sessionId/messages/pin

Pin a message for 24h (default), 7d or 30d.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/pin" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","messageId":"[email protected]_3EB0ABCD","durationSeconds":604800}'

POST /api/sessions/:sessionId/messages/star

Star or unstar a message.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/star" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","messageId":"[email protected]_3EB0ABCD","star":true}'

POST /api/sessions/:sessionId/messages/unpin

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/unpin" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","messageId":"[email protected]_3EB0ABCD"}'

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

Download a message's stored media: the archived file when one exists (CHAT_MEDIA_ARCHIVE_ENABLED, plus CHAT_MEDIA_ARCHIVE_OUTBOUND for media this account sent), else the inline copy on the message row — which covers media sent by this account either way, except a send made by url, whose bytes the gateway does not store (on whatsapp-web.js the own-send echo may still hold them, so that route can answer 200 or 404); 404 when neither holds bytes.

curl "$BASE/api/sessions/$SESSION_ID/messages/[email protected]/[email protected]_3EB0ABCD/media" \
  -H "X-API-Key: $API_KEY" -o media.bin

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

Get the status and progress of a bulk batch.

curl "$BASE/api/sessions/$SESSION_ID/messages/batch/batch_a1b2c3d4" \
  -H "X-API-Key: $API_KEY"

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

Send a plain text message.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-text" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "text": "Hello from OpenWA!" }'

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

Render a stored template ({{vars}} substituted) and send it as text.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-template" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "templateName": "order-confirmation", "vars": { "customer": "Alice", "orderId": "1234" } }'

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

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

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-image" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "url": "https://example.com/image.jpg", "caption": "Check out this image!" }'

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

Send a video by URL or base64 with an optional caption.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-video" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "url": "https://example.com/clip.mp4", "caption": "video" }'

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

Send an audio message by URL or base64. Add "ptt": true to send a real WhatsApp voice note (mic bubble + waveform); the server defaults the mimetype to audio/ogg; codecs=opus when ptt is set without one.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-audio" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg", "ptt": true }'

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

Send a document/file by URL or base64.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-document" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "url": "https://example.com/report.pdf", "filename": "report.pdf", "mimetype": "application/pdf" }'

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

Send a location pin.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-location" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "latitude": -6.2088, "longitude": 106.8456, "description": "Jakarta", "address": "Central Jakarta" }'

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

Send a contact card (vCard).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-contact" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "contactName": "John Doe", "contactNumber": "628987654321" }'

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

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

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-sticker" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "url": "https://example.com/sticker.webp", "mimetype": "image/webp" }'

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

Send a native WhatsApp poll (2–12 options; single choice unless allowMultipleAnswers is true).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-poll" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "name": "Where should we meet?", "options": ["Park", "Beach", "Downtown"] }'

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

Reply to a message, quoting a prior one.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/reply" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "quotedMessageId": "[email protected]_3EB0ABCD", "text": "Replying to you" }'

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

Forward a message from one chat to another.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/forward" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fromChatId": "[email protected]", "toChatId": "[email protected]", "messageId": "[email protected]_3EB0XYZ" }'

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

Add a reaction (send an empty emoji to remove it).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/react" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "messageId": "[email protected]_3EB0ABCD", "emoji": "👍" }'

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

Delete a message (for everyone by default).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/delete" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "messageId": "[email protected]_3EB0ABCD", "forEveryone": true }'

POST /api/sessions/:sessionId/messages/edit

Edit the text of a message sent by this account (OPERATOR); the edited message keeps its original id.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/edit" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "messageId": "[email protected]_3EB0ABCD", "body": "Corrected text" }'

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

Send to multiple recipients as an async batch (max 100 messages; exact duplicate entries — same chatId, type, content and variables — are collapsed, first occurrence wins).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-bulk" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "chatId": "[email protected]", "type": "text", "content": { "text": "Hi {{name}}" }, "variables": { "name": "Alice" } },
      { "chatId": "[email protected]", "type": "image", "content": { "image": { "url": "https://example.com/promo.jpg" }, "caption": "Promo" } }
    ],
    "options": { "delayBetweenMessages": 3000, "randomizeDelay": true, "stopOnError": false }
  }'

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

Cancel a running bulk batch (no body).

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/batch/batch_a1b2c3d4/cancel" \
  -H "X-API-Key: $API_KEY"

07.5 Contacts

GET /api/sessions/:sessionId/contacts

List contacts for a session (paginated window).

curl -X GET "$BASE/api/sessions/$SESSION_ID/contacts?limit=100&offset=0" \
  -H "X-API-Key: $API_KEY"

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

Check whether a phone number is on WhatsApp. Requires an OPERATOR key.

curl -X GET "$BASE/api/sessions/$SESSION_ID/contacts/check/628123456789" \
  -H "X-API-Key: $API_KEY"

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

Get a single contact by its WhatsApp id.

curl -X GET "$BASE/api/sessions/$SESSION_ID/contacts/[email protected]" \
  -H "X-API-Key: $API_KEY"

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

Get a contact's profile picture URL.

curl -X GET "$BASE/api/sessions/$SESSION_ID/contacts/[email protected]/profile-picture" \
  -H "X-API-Key: $API_KEY"

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

Resolve a contact id (e.g. an @lid) to a phone number.

curl -X GET "$BASE/api/sessions/$SESSION_ID/contacts/12345678901234@lid/phone" \
  -H "X-API-Key: $API_KEY"

PUT /api/sessions/:sessionId/contacts/:contactId

Save or edit an addressbook contact.

curl -X PUT "$BASE/api/sessions/$SESSION_ID/contacts/[email protected]" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"firstName":"Ada","lastName":"Lovelace"}'

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

Remove an addressbook contact.

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/contacts/[email protected]" \
  -H "X-API-Key: $API_KEY"

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

Block a contact (requires an OPERATOR key). Send an empty body.

curl -X POST "$BASE/api/sessions/$SESSION_ID/contacts/[email protected]/block" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

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

Unblock a contact (requires an OPERATOR key).

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/contacts/[email protected]/block" \
  -H "X-API-Key: $API_KEY"

07.6 Groups

GET /api/sessions/:sessionId/groups

List all groups for a session (paginated).

curl -X GET "$BASE/api/sessions/$SESSION_ID/groups?limit=1000&offset=0" \
  -H "X-API-Key: $API_KEY"

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

Get detailed group info including participants.

curl -X GET "$BASE/api/sessions/$SESSION_ID/groups/[email protected]" \
  -H "X-API-Key: $API_KEY"

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

Get the group invite code and full invite link (OPERATOR).

curl -X GET "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/invite-code" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/groups

Create a new group with an initial set of participants (OPERATOR). Baileys only: whatsapp-web.js answers 501.

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Project Team", "participants": ["[email protected]", "[email protected]"] }'

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

Add participants to a group (OPERATOR).

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/participants" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["[email protected]"] }'

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

Remove participants from a group (OPERATOR). This DELETE takes a JSON body.

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/participants" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["[email protected]"] }'

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

Promote participants to group admin (OPERATOR).

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/participants/promote" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["[email protected]"] }'

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

Demote participants from group admin (OPERATOR).

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/participants/demote" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["[email protected]"] }'

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

Change the group name/subject (OPERATOR).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/subject" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "New Team Name" }'

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

Change the group description; an empty string clears it (OPERATOR).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/description" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Internal coordination group." }'

PUT /api/sessions/:sessionId/groups/:groupId/member-label

Set this account's member label in the group, up to 30 UTF-16 code units (an emoji outside the Basic Multilingual Plane counts as two); an empty string clears it (OPERATOR, Baileys only: whatsapp-web.js answers 501).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/member-label" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Site A Management" }'

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

Leave a group (OPERATOR).

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/leave" \
  -H "X-API-Key: $API_KEY"

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

Revoke the current invite code and generate a new one (OPERATOR).

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/invite-code/revoke" \
  -H "X-API-Key: $API_KEY"

GET /api/sessions/:sessionId/groups/join-info

Preview a group from its invite code WITHOUT joining (both engines). Read-only, so it is safe to call on a code from an untrusted source. There is no participant list — only participantCount, and only when WhatsApp discloses one.

curl "$BASE/api/sessions/$SESSION_ID/groups/join-info?code=XyZ987654321" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/groups/join

Join a group via an invite code — the part after https://chat.whatsapp.com/ (OPERATOR).

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/join" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inviteCode": "XyZ987654321" }'

GET /api/sessions/:sessionId/groups/:groupId/membership-requests

List a group's pending join requests (the queue the group.join_request event announces). The account must be a group admin — WhatsApp refuses the read otherwise (403).

curl "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/membership-requests" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/groups/:groupId/membership-requests/approve

Approve pending join requests (OPERATOR) — the named requesters, or EVERY pending request when the body names none. The response carries a per-requester results list; a partial refusal does not fail the batch.

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/membership-requests/approve" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["[email protected]"] }'

POST /api/sessions/:sessionId/groups/:groupId/membership-requests/reject

Reject pending join requests (OPERATOR). Same body, response shape and batch contract as approve.

curl -X POST "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/membership-requests/reject" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["[email protected]"] }'

07.7 Message Templates

All template routes are nested under a session and require an OPERATOR-level key.

GET /api/sessions/:sessionId/templates

List all templates for a session, newest first.

curl "$BASE/api/sessions/$SESSION_ID/templates" \
  -H "X-API-Key: $API_KEY"

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

Get a single template by ID.

curl "$BASE/api/sessions/$SESSION_ID/templates/$TEMPLATE_ID" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/templates

Create a message template with {{variable}} placeholders.

curl -X POST "$BASE/api/sessions/$SESSION_ID/templates" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-confirmation",
    "body": "Hi {{customer}}, your order {{orderId}} has shipped.",
    "header": "OpenWA Store",
    "footer": "Reply STOP to unsubscribe."
  }'

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

Update a template (partial; only provided fields change).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/templates/$TEMPLATE_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{customer}}, your order {{orderId}} is out for delivery.",
    "footer": "Thanks for shopping with us."
  }'

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

Delete a template by ID (returns 204 empty body).

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/templates/$TEMPLATE_ID" \
  -H "X-API-Key: $API_KEY"

07.8 Catalog & Channels

The catalog routes work on the Baileys engine (WhatsApp Business accounts) — getCatalog/getProducts/getProduct read the session's own catalog and sendProduct sends a native product card. On whatsapp-web.js they raise EngineNotSupportedError (501 Not Implemented) — the library has no catalog API at all; on that engine the readiness check runs first, so a session that exists but is not yet READY returns 409 instead. The per-engine gaps are listed in docs/29-engine-capability-matrix.md. The channel routes that follow are a separate group, and each engine answers 501 for some of them: whatsapp-web.js for subscribe, admin demotion and ownership transfer, Baileys for listing subscribed channels and reading a channel's messages.

GET /api/sessions/:sessionId/catalog

Get business catalog info for the session. On Baileys returns the first catalog collection's metadata (200, or an empty 200 body when the business has no collections); on whatsapp-web.js returns 501.

curl -X GET "$BASE/api/sessions/$SESSION_ID/catalog" \
  -H "X-API-Key: $API_KEY"

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

List catalog products with pagination. Works on Baileys (page/limit over the full catalog walk); returns 501 on whatsapp-web.js.

curl -X GET "$BASE/api/sessions/$SESSION_ID/catalog/products?page=1&limit=20" \
  -H "X-API-Key: $API_KEY"

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

Get a specific catalog product by id. On Baileys returns the product (200) or an empty 200 body for an unknown id; on whatsapp-web.js returns 501.

curl -X GET "$BASE/api/sessions/$SESSION_ID/catalog/products/PROD_12345" \
  -H "X-API-Key: $API_KEY"

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

Send a product card to a chat (OPERATOR key required). On Baileys returns 404 for an unknown product id and 400 when the product has no image; on whatsapp-web.js returns 501.

curl -X POST "$BASE/api/sessions/$SESSION_ID/messages/send-product" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "[email protected]", "productId": "PROD_12345", "body": "Check out this item!" }'

GET /api/sessions/:sessionId/channels

List subscribed channels/newsletters.

curl -X GET "$BASE/api/sessions/$SESSION_ID/channels" \
  -H "X-API-Key: $API_KEY"

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

Get a single channel by id.

curl -X GET "$BASE/api/sessions/$SESSION_ID/channels/120363000000000000@newsletter" \
  -H "X-API-Key: $API_KEY"

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

Get recent messages from a channel.

curl -X GET "$BASE/api/sessions/$SESSION_ID/channels/120363000000000000@newsletter/messages?limit=50" \
  -H "X-API-Key: $API_KEY"

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

Subscribe to a channel by invite code (OPERATOR key required).

curl -X POST "$BASE/api/sessions/$SESSION_ID/channels/subscribe" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inviteCode": "ABC123xyz" }'

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

Unsubscribe from a channel (OPERATOR key required).

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/channels/120363000000000000@newsletter" \
  -H "X-API-Key: $API_KEY"

07.9 Labels & Status

# List all labels for a session (WhatsApp Business only; Baileys answers 501 for the label reads: list, get and a chat's labels)
curl -X GET "$BASE/api/sessions/$SESSION_ID/labels" \
  -H "X-API-Key: $API_KEY"
# Get a single label by ID
curl -X GET "$BASE/api/sessions/$SESSION_ID/labels/5" \
  -H "X-API-Key: $API_KEY"
# List labels assigned to a chat
curl -X GET "$BASE/api/sessions/$SESSION_ID/labels/chat/[email protected]" \
  -H "X-API-Key: $API_KEY"
# Add a label to a chat (OPERATOR)
curl -X POST "$BASE/api/sessions/$SESSION_ID/labels/chat/[email protected]" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "labelId": "5" }'
# Remove a label from a chat (OPERATOR)
curl -X DELETE "$BASE/api/sessions/$SESSION_ID/labels/chat/[email protected]/5" \
  -H "X-API-Key: $API_KEY"
# Get all status updates (stories) visible to the session
curl -X GET "$BASE/api/sessions/$SESSION_ID/status" \
  -H "X-API-Key: $API_KEY"
# Get status updates posted by a specific contact
curl -X GET "$BASE/api/sessions/$SESSION_ID/status/[email protected]" \
  -H "X-API-Key: $API_KEY"
# Post a text status (OPERATOR)
curl -X POST "$BASE/api/sessions/$SESSION_ID/status/send-text" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello from OpenWA!", "backgroundColor": "#25D366", "font": 2 }'
# Post an image status from a URL (OPERATOR)
curl -X POST "$BASE/api/sessions/$SESSION_ID/status/send-image" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image": { "url": "https://example.com/photo.jpg" }, "caption": "My status" }'
# Post a video status from a URL (OPERATOR)
curl -X POST "$BASE/api/sessions/$SESSION_ID/status/send-video" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "video": { "url": "https://example.com/clip.mp4" }, "caption": "Watch this" }'
# Post a voice-note status (OPERATOR). WhatsApp only plays Ogg/Opus — neither engine
# transcodes, so convert first via media/convert/voice and post the base64 it returns.
# `recipients` (the viewer allow-list) is honored on Baileys only. There is no `caption`.
curl -X POST "$BASE/api/sessions/$SESSION_ID/status/send-voice" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audio": { "base64": "T2dnUwACAAAA..." }, "recipients": ["[email protected]"] }'
# Delete one of the session's own posted statuses (OPERATOR)
curl -X DELETE "$BASE/api/sessions/$SESSION_ID/status/false_status@broadcast_3A1F" \
  -H "X-API-Key: $API_KEY"

07.10 Webhooks (management)

All routes require an API key with OPERATOR role or higher. secret and headers are write-only (never returned by these routes; GET /api/infra/export-data omits them from webhook rows too). The per-session routes live under /api/sessions/:sessionId/webhooks; the cross-session list is /api/webhooks.

GET /api/sessions/:sessionId/webhooks

List all webhooks for a session (newest first).

curl -X GET "$BASE/api/sessions/$SESSION_ID/webhooks" \
  -H "X-API-Key: $API_KEY"

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

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

curl -X GET "$BASE/api/sessions/$SESSION_ID/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef" \
  -H "X-API-Key: $API_KEY"

GET /api/webhooks

List webhooks visible to the calling key (scoped to its allowed sessions). Add limit/offset to page large lists.

curl -X GET "$BASE/api/webhooks?limit=100&offset=0" \
  -H "X-API-Key: $API_KEY"

GET /api/webhooks/delivery-failures

List webhook deliveries that failed or were not sent (attempts 0), most recent first (ADMIN; results stay confined to the key's allowed sessions). A shed or shutdown-refused delivery is replayed by the outbox until its replay budget runs out; an oversize payload or a preflight failure on first dispatch is not replayed. lastStatusCode is null when the failure was a network/timeout/SSRF error rather than a non-2xx response.

curl -X GET "$BASE/api/webhooks/delivery-failures?limit=100&offset=0" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/webhooks

Create a webhook for the session.

curl -X POST "$BASE/api/sessions/$SESSION_ID/webhooks" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "session.status"],
    "secret": "your-webhook-signing-secret",
    "headers": { "X-Custom-Header": "value" },
    "filters": {
      "conditions": [
        { "field": "sender", "operator": "is", "value": ["[email protected]"] },
        { "field": "chatId", "operator": "is", "value": ["[email protected]"] },
        { "field": "body", "operator": "contains", "value": "invoice" }
      ]
    },
    "retryCount": 3
  }'

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

Update a webhook (partial; only provided fields change).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["*"],
    "active": false,
    "retryCount": 5,
    "filters": null
  }'

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

Send a synthetic test payload to the webhook URL and report the result (no request body).

curl -X POST "$BASE/api/sessions/$SESSION_ID/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef/test" \
  -H "X-API-Key: $API_KEY"

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

Delete a webhook (returns 204 no content).

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef" \
  -H "X-API-Key: $API_KEY"

07.11 API Keys

All /api/auth/api-keys routes require an unscoped ADMIN key: one with allowedSessions or allowedChats set is refused with 403. POST /api/auth/validate accepts any valid key except one its allowedIps refuses or one restricted with allowedChats, each of which gets 403. The plaintext key is returned only by the create call.

GET /api/auth/api-keys

List all API keys (newest first).

curl -X GET "$BASE/api/auth/api-keys" \
  -H "X-API-Key: $API_KEY"

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

Get one API key by id.

curl -X GET "$BASE/api/auth/api-keys/3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33" \
  -H "X-API-Key: $API_KEY"

POST /api/auth/api-keys

Create a key; the response includes the full plaintext key once.

curl -X POST "$BASE/api/auth/api-keys" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

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

Update name/role/allowedIps/allowedSessions/allowedChats/expiresAt.

curl -X PUT "$BASE/api/auth/api-keys/3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renamed Bot",
    "role": "viewer",
    "allowedIps": ["203.0.113.5"],
    "expiresAt": "2028-01-01T00:00:00Z"
  }'

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

Deactivate a key without deleting it (no body).

curl -X POST "$BASE/api/auth/api-keys/3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33/revoke" \
  -H "X-API-Key: $API_KEY"

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

Permanently delete a key (returns 204, no body).

curl -X DELETE "$BASE/api/auth/api-keys/3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33" \
  -H "X-API-Key: $API_KEY"

POST /api/auth/validate

Validate the supplied key and report its role and the running engine (engineType); empty body, key read from the header.

curl -X POST "$BASE/api/auth/validate" \
  -H "X-API-Key: $API_KEY"

07.12 System (Health, Metrics, Stats, Settings, Audit)

GET /api/health

Basic health check (status, timestamp). Public. The running version is added only when the request carries a valid API key, so an unauthenticated probe gets status and timestamp alone.

curl "$BASE/api/health"

# With the version field:
curl -H "X-API-Key: $API_KEY" "$BASE/api/health"

GET /api/health/live

Liveness probe — always { "status": "ok" }. Public.

curl "$BASE/api/health/live"

GET /api/health/ready

Readiness probe — checks both datasources; 503 while draining or on DB failure. Public.

curl "$BASE/api/health/ready"

GET /api/metrics

Prometheus scrape. Gated by the metrics bearer token (not the API key); 404 when METRICS_TOKEN is unset.

curl "$BASE/api/metrics" \
  -H "Authorization: Bearer $METRICS_TOKEN"

GET /api/stats/overview

Cross-session aggregate stats. ADMIN key required.

curl "$BASE/api/stats/overview" \
  -H "X-API-Key: $API_KEY"

GET /api/stats/messages

Message stats over a period (24h | 7d | 30d, default 24h). ADMIN key required.

curl "$BASE/api/stats/messages?period=7d" \
  -H "X-API-Key: $API_KEY"

GET /api/stats/sessions/:sessionId

Per-session stats. Any role; a session-restricted key can only read stats for its allowed sessions.

curl "$BASE/api/stats/sessions/$SESSION_ID" \
  -H "X-API-Key: $API_KEY"

GET /api/settings

Read runtime settings (env-derived). ADMIN key required (403 otherwise).

curl "$BASE/api/settings" \
  -H "X-API-Key: $API_KEY"

GET /api/audit

List audit-log entries, newest first (ADMIN; rows stay confined to the key's allowed sessions). Unlike the other list routes the body is { "data", "total" } — the page plus the unpaginated match count. Filters: action, severity (info | warn | error), sessionId, apiKeyId, plus limit (default 50, max 200) and offset.

curl -X GET "$BASE/api/audit?action=session_started&limit=50" \
  -H "X-API-Key: $API_KEY"

07.13 Administration (Infrastructure, Plugins, MCP)

ADMIN-only operations (except the public health check and the MCP transport). Assumes BASE, API_KEY, and — for MCP — that MCP_ENABLED=true.

GET /api/infra/health

Public liveness probe. It answers 503 from the moment shutdown teardown begins; GET /api/health/live keeps answering.

curl "$BASE/api/infra/health"

GET /api/infra/status

Aggregate infra status (DB, Redis, queue, storage, engine).

curl "$BASE/api/infra/status" \
  -H "X-API-Key: $API_KEY"

GET /api/infra/engines

List available WhatsApp engine plugins.

curl "$BASE/api/infra/engines" \
  -H "X-API-Key: $API_KEY"

GET /api/infra/engines/current

Get the currently active engine type.

curl "$BASE/api/infra/engines/current" \
  -H "X-API-Key: $API_KEY"

GET /api/infra/config

Read effective infrastructure config (secrets omitted) — each field resolves with the boot precedence (environment / .env over data/.env.generated).

curl "$BASE/api/infra/config" \
  -H "X-API-Key: $API_KEY"

PUT /api/infra/config

Merge-save infrastructure config to data/.env.generated.

curl -X PUT "$BASE/api/infra/config" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "database": { "type": "postgres", "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", "s3Bucket": "my-bucket", "s3Region": "ap-southeast-1", "s3AccessKey": "AKIA...", "s3SecretKey": "...", "s3Endpoint": "https://s3.example.com" },
    "engine": { "type": "whatsapp-web.js", "headless": true }
  }'

POST /api/infra/restart

Request a graceful restart, optionally orchestrating Docker profiles.

curl -X POST "$BASE/api/infra/restart" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profiles": ["postgres", "redis"], "profilesToRemove": ["minio"] }'

GET /api/infra/export-data

Export all Data DB rows as JSON for migration.

curl "$BASE/api/infra/export-data" \
  -H "X-API-Key: $API_KEY"

POST /api/infra/import-data

Replace all Data DB rows with a prior export (destructive, all-or-nothing). Every one of the 16 migration tables is emptied first, so a key you omit restores empty rather than untouched — send a body produced by GET /api/infra/export-data, not a hand-built subset. All 16 keys are shown below for that reason.

curl -X POST "$BASE/api/infra/import-data" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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": [],
      "lidMappings": [], "chatStates": [], "pluginInstances": [], "conversationMappings": [], "ingressEvents": [],
      "webhookDeliveryFailures": [], "webhookOutboxEvents": [], "integrationDeliveryFailures": [], "statusUpdates": [],
      "automationRules": []
    }
  }'

GET /api/infra/storage/files/count

File count and total size in the active storage backend.

curl "$BASE/api/infra/storage/files/count" \
  -H "X-API-Key: $API_KEY"

GET /api/infra/storage/export

Export all storage files to a tar.gz; returns its server-side path.

curl "$BASE/api/infra/storage/export" \
  -H "X-API-Key: $API_KEY"

POST /api/infra/storage/import

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

curl -X POST "$BASE/api/infra/storage/import" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filePath": "./data/exports/storage-export-1750000000000-abc.tar.gz" }'

GET /api/plugins

List all loaded plugins (secrets redacted).

curl "$BASE/api/plugins" \
  -H "X-API-Key: $API_KEY"

GET /api/plugins/catalog

List the remote plugin catalog with install state.

curl "$BASE/api/plugins/catalog" \
  -H "X-API-Key: $API_KEY"

GET /api/plugins/:id

Get a single plugin by id.

curl "$BASE/api/plugins/chat-flow" \
  -H "X-API-Key: $API_KEY"

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

Fetch a plugin's sandboxed config-UI HTML. The dashboard renders it in an opaque-origin iframe, uses a postMessage bridge for config, and retains any schema form as a fallback.

curl "$BASE/api/plugins/chat-flow/config-ui" \
  -H "X-API-Key: $API_KEY"

GET /api/plugins/:id/health

Check a plugin's health.

curl "$BASE/api/plugins/chat-flow/health" \
  -H "X-API-Key: $API_KEY"

POST /api/plugins/install

Install a plugin from an uploaded .zip (multipart, field file, max 5 MB).

curl -X POST "$BASE/api/plugins/install" \
  -H "X-API-Key: $API_KEY" \
  -F "[email protected]"

POST /api/plugins/install-url

Install a plugin by downloading its .zip from a URL (SSRF-guarded). Under NODE_ENV=production the URL needs a #sha256= pin by default; the digest below is a placeholder for the SHA-256 of the .zip.

curl -X POST "$BASE/api/plugins/install-url" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://github.com/openwa-plugins/chat-flow/releases/download/v1.0.0/chat-flow.zip#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }'

POST /api/plugins/:id/enable

Enable a plugin.

curl -X POST "$BASE/api/plugins/chat-flow/enable" \
  -H "X-API-Key: $API_KEY"

POST /api/plugins/:id/disable

Disable a plugin.

curl -X POST "$BASE/api/plugins/chat-flow/disable" \
  -H "X-API-Key: $API_KEY"

PUT /api/plugins/:id/config

Update a plugin's base configuration.

curl -X PUT "$BASE/api/plugins/chat-flow/config" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "apiKey": "sk-...", "replyDelayMs": 1500 } }'

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

Set a per-session plugin config override, or clear it by sending { "config": {} }. The override is stored under the session UUID and resolved against the UUID carried by each event, so an id that is not a live session's UUID never takes effect.

curl -X PUT "$BASE/api/plugins/chat-flow/config/$SESSION_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "replyDelayMs": 3000 } }'

PUT /api/plugins/:id/sessions

Set which sessions a session-scoped plugin is activated for (["*"] = all).

curl -X PUT "$BASE/api/plugins/chat-flow/sessions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessions": ["*"] }'

POST /api/plugins/:id/update

Update an installed plugin in place from a URL. The URL follows the same pin rule as install-url; the digest below is a placeholder for the SHA-256 of the .zip.

curl -X POST "$BASE/api/plugins/chat-flow/update" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/plugins/chat-flow-1.1.0.zip#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }'

DELETE /api/plugins/:id

Uninstall a plugin (built-ins protected).

curl -X DELETE "$BASE/api/plugins/chat-flow" \
  -H "X-API-Key: $API_KEY"

POST /mcp

MCP JSON-RPC 2.0 transport (no /api prefix; gated by MCP_ENABLED=true). The API key goes via X-Api-Key or Authorization: Bearer on every request, initialize and tools/list included (a missing or invalid key answers 401, a key carrying allowedIps 403); role and session scope are checked per tool call. The server is read-only by default — write tools such as MessageSendText are only mounted when MCP_READONLY=false. Every POST must send Accept: application/json, text/event-stream (otherwise 406), and the reply arrives as an SSE frame: an event: message line, then a data: line holding the JSON-RPC response. See doc 24 for the tool catalog.

# Initialize handshake
curl -X POST "$BASE/mcp" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "openwa-collection", "version": "1.0.0" } } }'

# List available tools
curl -X POST "$BASE/mcp" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }'

# Call a tool (arguments must match the tool's zod inputSchema; requires MCP_READONLY=false)
curl -X POST "$BASE/mcp" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "MessageSendText", "arguments": { "sessionId": "'"$SESSION_ID"'", "chatId": "[email protected]", "text": "Hello from MCP" } } }'

07.14 Profile (own account)

Manage the linked account's own profile. All routes are nested under a session and require an OPERATOR key.

PUT /api/sessions/:sessionId/profile/name

Set the account display name (max 25 chars).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/profile/name" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ACME Support" }'

PUT /api/sessions/:sessionId/profile/status

Set the account about/status text (max 139 chars; empty string clears it).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/profile/status" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "We reply within one business day" }'

PUT /api/sessions/:sessionId/profile/picture

Set the account profile picture from a URL or base64 image (same media DTO conventions as message sends).

curl -X PUT "$BASE/api/sessions/$SESSION_ID/profile/picture" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/avatar.png" }'

DELETE /api/sessions/:sessionId/profile/picture

Remove the account profile picture (WhatsApp's default avatar takes over). Removing a picture that is already absent is a no-op and also answers 200.

curl -X DELETE "$BASE/api/sessions/$SESSION_ID/profile/picture" \
  -H "X-API-Key: $API_KEY"

07.15 Search

Cross-session full-text message search (OPERATOR or higher). On by default; SEARCH_ENABLED=false removes the route and module entirely. A scoped key's allowedSessions is applied server-side and cannot be widened via the query. See doc 26 for the provider contract.

GET /api/search

Search messages across sessions. q is required (non-empty after trim); optional filters are sessionId, chatId, direction (incoming | outgoing), type, from, dateFrom/dateTo (epoch ms), plus limit (default 50, clamped to SEARCH_LIMIT_MAX = 100) and offset (at most 100000). match is word (the default, whole words) or contains (any part of a word, ignoring case and accents), which answers 501 unless the server sets SEARCH_CONTAINS_ENABLED=true and 400 without a term of 3 or more characters or with more than 64 characters in its terms. q is at most 1000 characters and 32 words with no NUL character, and any other answers 400. A key restricted to selected chats gets 403 for a chatId outside its list and for a plugin search provider. Hit snippet fields carry <mark> highlight markers — render them as text, never as HTML.

curl -X GET "$BASE/api/search?q=invoice&direction=incoming&limit=20" \
  -H "X-API-Key: $API_KEY"

07.16 Media conversion (opt-in)

Server-side transcoding into the shapes WhatsApp clients actually play. Disabled by default; set MEDIA_CONVERSION_ENABLED=true, and ffmpeg must be runnable (the official Docker image ships it) or the routes answer 503; video conversion needs ffmpeg 4.4 or newer. Nothing is converted implicitly — run media through here first, then post the result.

GET /api/sessions/:sessionId/media/convert

Report whether conversion is switched on and runnable here ({ "available": true }). Any role.

curl "$BASE/api/sessions/$SESSION_ID/media/convert" \
  -H "X-API-Key: $API_KEY"

POST /api/sessions/:sessionId/media/convert/voice

Convert audio (or a video's audio track) into a WhatsApp voice note — Ogg/Opus, mono, 48 kHz (OPERATOR). Exactly one of url / base64. Post the returned base64 to messages/send-audio with ptt: true (or to status/send-voice).

curl -X POST "$BASE/api/sessions/$SESSION_ID/media/convert/voice" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/voice-memo.mp3" }'

POST /api/sessions/:sessionId/media/convert/video

Convert video into a baseline H.264/AAC MP4 every WhatsApp client accepts (OPERATOR); same request body and errors as the voice endpoint. Both responses are bounded by MEDIA_CONVERSION_MAX_OUTPUT_BYTES (default 50 MiB).

curl -X POST "$BASE/api/sessions/$SESSION_ID/media/convert/video" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/clip.mov" }'

07.17 Real-time (WebSocket)

Events are delivered over Socket.IO on the /events namespace (not a raw WebSocket). Use the socket.io-client package. Set BASE_WS (e.g. ws://localhost:2785) and API_KEY.

npm install socket.io-client
// realtime.mjs — run: BASE_WS=ws://localhost:2785 API_KEY=... SESSION_ID=<session-uuid> node realtime.mjs
import { io } from 'socket.io-client';

const BASE_WS = process.env.BASE_WS || 'ws://localhost:2785';
const API_KEY = process.env.API_KEY;
const SESSION_ID = process.env.SESSION_ID; // the session UUID, or '*' (unrestricted keys only)

const socket = io(`${BASE_WS}/events`, {
  auth: { apiKey: API_KEY }, // or the x-api-key header
});

socket.on('connect', () => {
  console.log('connected:', socket.id);
  socket.emit('message', {
    type: 'subscribe',
    sessionId: SESSION_ID,
    events: ['*'], // or e.g. ['message.received', '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(`[${msg.type}]`, msg); // subscribed | unsubscribed | pong | error
  }
});

socket.on('connect_error', err => console.error('connect_error:', err.message));
socket.on('disconnect', reason => console.log('disconnected:', reason));