This collection gives a runnable cURL for every OpenWA REST endpoint. 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=....)
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; read-only routes accept any valid key. 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 are the raw payload — no { success, data } envelope. A resource route returns the object directly; a list route returns a bare JSON array. Errors return the NestJS default shape { "statusCode", "message", "error" }. Add Content-Type: application/json only when sending a body.
Sessions · Messages · Webhooks · Groups · Contacts · Chats · Labels · Channels · Catalog · Templates · Plugins · Settings · Auth (API Keys) · Health · Infrastructure · Stats · Metrics · Events (WebSocket).
All examples assume BASE and API_KEY are exported (see 07.1). Paths are prefixed with /api.
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.
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 a single session by ID.
curl -X GET "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a" \
-H "X-API-Key: $API_KEY"Get the QR code (PNG data URL) for authentication.
curl -X GET "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/qr" \
-H "X-API-Key: $API_KEY"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"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"Aggregate session statistics for monitoring.
curl -X GET "$BASE/api/sessions/stats/overview" \
-H "X-API-Key: $API_KEY"Create a new session (OPERATOR).
curl -X POST "$BASE/api/sessions" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "my-bot", "config": { "autoReconnect": true }, "proxyUrl": "http://proxy.example.com:8080", "proxyType": "http" }'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"Stop a session and disconnect (OPERATOR).
curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/stop" \
-H "X-API-Key: $API_KEY"Force-kill a stuck session (OPERATOR).
curl -X POST "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/force-kill" \
-H "X-API-Key: $API_KEY"Request an 8-char pairing code via phone number (OPERATOR).
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" }'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": "1234567890@c.us" }'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": "1234567890@c.us" }'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": "1234567890-123@g.us" }'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": "1234567890@c.us", "state": "typing" }'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"All routes are under /api/sessions/:sessionId/messages. Reads accept any API key; send/write routes need an OPERATOR (or higher) key.
Get persisted message history from the local DB (paginated, filterable).
curl "$BASE/api/sessions/my-session/messages?chatId=628123456789@c.us&limit=20&offset=0" \
-H "X-API-Key: $API_KEY"Fetch chat history live from WhatsApp, bypassing the DB.
curl "$BASE/api/sessions/my-session/628123456789@c.us/history?limit=100&deep=true" \
-H "X-API-Key: $API_KEY"Get reactions for a message, grouped by emoji.
curl "$BASE/api/sessions/my-session/628123456789@c.us/true_628123456789@c.us_3EB0ABCD/reactions" \
-H "X-API-Key: $API_KEY"Get the status and progress of a bulk batch.
curl "$BASE/api/sessions/my-session/messages/batch/batch_a1b2c3d4" \
-H "X-API-Key: $API_KEY"Send a plain text message.
curl -X POST "$BASE/api/sessions/my-session/messages/send-text" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "text": "Hello from OpenWA!" }'Render a stored template ({{vars}} substituted) and send it as text.
curl -X POST "$BASE/api/sessions/my-session/messages/send-template" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "templateName": "order-confirmation", "vars": { "customer": "Alice", "orderId": "1234" } }'Send an image by URL or base64 with an optional caption.
curl -X POST "$BASE/api/sessions/my-session/messages/send-image" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "url": "https://example.com/image.jpg", "caption": "Check out this image!" }'Send a video by URL or base64 with an optional caption.
curl -X POST "$BASE/api/sessions/my-session/messages/send-video" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "url": "https://example.com/clip.mp4", "caption": "video" }'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/my-session/messages/send-audio" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "url": "https://example.com/voice.ogg", "mimetype": "audio/ogg", "ptt": true }'Send a document/file by URL or base64.
curl -X POST "$BASE/api/sessions/my-session/messages/send-document" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "url": "https://example.com/report.pdf", "filename": "report.pdf", "mimetype": "application/pdf" }'Send a location pin.
curl -X POST "$BASE/api/sessions/my-session/messages/send-location" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "latitude": -6.2088, "longitude": 106.8456, "description": "Jakarta", "address": "Central Jakarta" }'Send a contact card (vCard).
curl -X POST "$BASE/api/sessions/my-session/messages/send-contact" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "contactName": "John Doe", "contactNumber": "628987654321" }'Send a sticker by URL or base64 (typically webp).
curl -X POST "$BASE/api/sessions/my-session/messages/send-sticker" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "url": "https://example.com/sticker.webp", "mimetype": "image/webp" }'Reply to a message, quoting a prior one.
curl -X POST "$BASE/api/sessions/my-session/messages/reply" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "quotedMessageId": "true_628123456789@c.us_3EB0ABCD", "text": "Replying to you" }'Forward a message from one chat to another.
curl -X POST "$BASE/api/sessions/my-session/messages/forward" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "fromChatId": "628111111111@c.us", "toChatId": "628222222222@c.us", "messageId": "true_628111111111@c.us_3EB0XYZ" }'Add a reaction (send an empty emoji to remove it).
curl -X POST "$BASE/api/sessions/my-session/messages/react" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "messageId": "true_628123456789@c.us_3EB0ABCD", "emoji": "👍" }'Delete a message (for everyone by default).
curl -X POST "$BASE/api/sessions/my-session/messages/delete" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "messageId": "true_628123456789@c.us_3EB0ABCD", "forEveryone": true }'Send to multiple recipients as an async batch (max 100 messages).
curl -X POST "$BASE/api/sessions/my-session/messages/send-bulk" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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 }
}'Cancel a running bulk batch (no body).
curl -X POST "$BASE/api/sessions/my-session/messages/batch/batch_a1b2c3d4/cancel" \
-H "X-API-Key: $API_KEY"List contacts for a session (paginated window).
curl -X GET "$BASE/api/sessions/main/contacts?limit=100&offset=0" \
-H "X-API-Key: $API_KEY"Check whether a phone number is on WhatsApp.
curl -X GET "$BASE/api/sessions/main/contacts/check/628123456789" \
-H "X-API-Key: $API_KEY"Get a single contact by its WhatsApp id.
curl -X GET "$BASE/api/sessions/main/contacts/6281234567890@c.us" \
-H "X-API-Key: $API_KEY"Get a contact's profile picture URL.
curl -X GET "$BASE/api/sessions/main/contacts/6281234567890@c.us/profile-picture" \
-H "X-API-Key: $API_KEY"Resolve a contact id (e.g. an @lid) to a phone number.
curl -X GET "$BASE/api/sessions/main/contacts/12345678901234@lid/phone" \
-H "X-API-Key: $API_KEY"Block a contact (requires an OPERATOR key). Send an empty body.
curl -X POST "$BASE/api/sessions/main/contacts/6281234567890@c.us/block" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Unblock a contact (requires an OPERATOR key).
curl -X DELETE "$BASE/api/sessions/main/contacts/6281234567890@c.us/block" \
-H "X-API-Key: $API_KEY"List all groups for a session (paginated).
curl -X GET "$BASE/api/sessions/my-session/groups?limit=1000&offset=0" \
-H "X-API-Key: $API_KEY"Get detailed group info including participants.
curl -X GET "$BASE/api/sessions/my-session/groups/120363021234567890@g.us" \
-H "X-API-Key: $API_KEY"Get the group invite code and full invite link.
curl -X GET "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/invite-code" \
-H "X-API-Key: $API_KEY"Create a new group with an initial set of participants (OPERATOR).
curl -X POST "$BASE/api/sessions/my-session/groups" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Project Team", "participants": ["628123456789@c.us", "628987654321@c.us"] }'Add participants to a group (OPERATOR).
curl -X POST "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/participants" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "participants": ["628123456789@c.us"] }'Remove participants from a group (OPERATOR). This DELETE takes a JSON body.
curl -X DELETE "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/participants" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "participants": ["628123456789@c.us"] }'Promote participants to group admin (OPERATOR).
curl -X POST "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/participants/promote" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "participants": ["628123456789@c.us"] }'Demote participants from group admin (OPERATOR).
curl -X POST "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/participants/demote" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "participants": ["628123456789@c.us"] }'Change the group name/subject (OPERATOR).
curl -X PUT "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/subject" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "subject": "New Team Name" }'Change the group description; an empty string clears it (OPERATOR).
curl -X PUT "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/description" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "description": "Internal coordination group." }'Leave a group (OPERATOR).
curl -X POST "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/leave" \
-H "X-API-Key: $API_KEY"Revoke the current invite code and generate a new one (OPERATOR).
curl -X POST "$BASE/api/sessions/my-session/groups/120363021234567890@g.us/invite-code/revoke" \
-H "X-API-Key: $API_KEY"All template routes are nested under a session and require an OPERATOR-level key.
List all templates for a session, newest first.
curl "$BASE/api/sessions/$SESSION_ID/templates" \
-H "X-API-Key: $API_KEY"Get a single template by ID.
curl "$BASE/api/sessions/$SESSION_ID/templates/$TEMPLATE_ID" \
-H "X-API-Key: $API_KEY"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."
}'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 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"Get business catalog info for the session.
curl -X GET "$BASE/api/sessions/my-session/catalog" \
-H "X-API-Key: $API_KEY"List catalog products with pagination.
curl -X GET "$BASE/api/sessions/my-session/catalog/products?page=1&limit=20" \
-H "X-API-Key: $API_KEY"Get a specific catalog product by id (unknown id returns 200 with null).
curl -X GET "$BASE/api/sessions/my-session/catalog/products/PROD_12345" \
-H "X-API-Key: $API_KEY"Send a product card to a chat (OPERATOR key required).
curl -X POST "$BASE/api/sessions/my-session/messages/send-product" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "6281234567890@c.us", "productId": "PROD_12345", "body": "Check out this item!" }'Send the business catalog link to a chat (OPERATOR key required).
curl -X POST "$BASE/api/sessions/my-session/messages/send-catalog" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "6281234567890@c.us", "body": "Browse our full catalog here" }'List subscribed channels/newsletters.
curl -X GET "$BASE/api/sessions/my-session/channels" \
-H "X-API-Key: $API_KEY"Get a single channel by id.
curl -X GET "$BASE/api/sessions/my-session/channels/120363000000000000@newsletter" \
-H "X-API-Key: $API_KEY"Get recent messages from a channel.
curl -X GET "$BASE/api/sessions/my-session/channels/120363000000000000@newsletter/messages?limit=50" \
-H "X-API-Key: $API_KEY"Subscribe to a channel by invite code (OPERATOR key required).
curl -X POST "$BASE/api/sessions/my-session/channels/subscribe" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "inviteCode": "ABC123xyz" }'Unsubscribe from a channel (OPERATOR key required).
curl -X DELETE "$BASE/api/sessions/my-session/channels/120363000000000000@newsletter" \
-H "X-API-Key: $API_KEY"# List all labels for a session (WhatsApp Business only)
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/6281234567890@c.us" \
-H "X-API-Key: $API_KEY"# Add a label to a chat (OPERATOR)
curl -X POST "$BASE/api/sessions/$SESSION_ID/labels/chat/6281234567890@c.us" \
-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/6281234567890@c.us/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/6281234567890@c.us" \
-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" }'# 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"All routes require an API key with OPERATOR role or higher. secret and headers are write-only (never returned). The per-session routes live under /api/sessions/:sessionId/webhooks; the cross-session list is /api/webhooks.
List all webhooks for a session (newest first).
curl -X GET "$BASE/api/sessions/my-session/webhooks" \
-H "X-API-Key: $API_KEY"Get a single webhook by ID, scoped to the session.
curl -X GET "$BASE/api/sessions/my-session/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef" \
-H "X-API-Key: $API_KEY"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"Create a webhook for the session.
curl -X POST "$BASE/api/sessions/my-session/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-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
}'Update a webhook (partial; only provided fields change).
curl -X PUT "$BASE/api/sessions/my-session/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
}'Send a synthetic test payload to the webhook URL and report the result (no request body).
curl -X POST "$BASE/api/sessions/my-session/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef/test" \
-H "X-API-Key: $API_KEY"Delete a webhook (returns 204 no content).
curl -X DELETE "$BASE/api/sessions/my-session/webhooks/f1e2d3c4-b5a6-7890-1234-567890abcdef" \
-H "X-API-Key: $API_KEY"All /api/auth/api-keys routes require an ADMIN key. POST /api/auth/validate accepts any valid key. The plaintext key is returned only by the create call.
List all API keys (newest first).
curl -X GET "$BASE/api/auth/api-keys" \
-H "X-API-Key: $API_KEY"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"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"
}'Update name/role/allowedIps/allowedSessions/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"
}'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"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"Validate the supplied key and report its role (empty body; key read from the header).
curl -X POST "$BASE/api/auth/validate" \
-H "X-API-Key: $API_KEY"Basic health check (status, timestamp, version). Public.
curl "$BASE/api/health"Liveness probe — always { "status": "ok" }. Public.
curl "$BASE/api/health/live"Readiness probe — checks both datasources; 503 while draining or on DB failure. Public.
curl "$BASE/api/health/ready"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"Cross-session aggregate stats. ADMIN key required.
curl "$BASE/api/stats/overview" \
-H "X-API-Key: $API_KEY"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"Per-session stats. Any valid API key (not session-scoped).
curl "$BASE/api/stats/sessions/9f1c2d3e-…" \
-H "X-API-Key: $API_KEY"Read runtime settings (env-derived). ADMIN key required (403 otherwise).
curl "$BASE/api/settings" \
-H "X-API-Key: $API_KEY"Always returns 501 — settings are read-only at runtime. ADMIN key required (still 501).
curl -X PUT "$BASE/api/settings" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "general": { "sessionTimeout": 10 } }'ADMIN-only operations (except the public health check and the MCP transport). Assumes BASE, API_KEY, and — for MCP — that MCP_ENABLED=true.
Public liveness probe.
curl "$BASE/api/infra/health"Aggregate infra status (DB, Redis, queue, storage, engine).
curl "$BASE/api/infra/status" \
-H "X-API-Key: $API_KEY"List available WhatsApp engine plugins.
curl "$BASE/api/infra/engines" \
-H "X-API-Key: $API_KEY"Get the currently active engine type.
curl "$BASE/api/infra/engines/current" \
-H "X-API-Key: $API_KEY"Read saved infrastructure config (secrets omitted).
curl "$BASE/api/infra/config" \
-H "X-API-Key: $API_KEY"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 }
}'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"] }'Export all Data DB rows as JSON for migration.
curl "$BASE/api/infra/export-data" \
-H "X-API-Key: $API_KEY"Replace all Data DB rows with a prior export (destructive, all-or-nothing).
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": []
}
}'File count and total size in the active storage backend.
curl "$BASE/api/infra/storage/files/count" \
-H "X-API-Key: $API_KEY"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"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" }'List all loaded plugins (secrets redacted).
curl "$BASE/api/plugins" \
-H "X-API-Key: $API_KEY"List the remote plugin catalog with install state.
curl "$BASE/api/plugins/catalog" \
-H "X-API-Key: $API_KEY"Get a single plugin by id.
curl "$BASE/api/plugins/chat-flow" \
-H "X-API-Key: $API_KEY"Fetch a plugin's sandboxed config-UI HTML (for an iframe srcdoc).
curl "$BASE/api/plugins/chat-flow/config-ui" \
-H "X-API-Key: $API_KEY"Check a plugin's health.
curl "$BASE/api/plugins/chat-flow/health" \
-H "X-API-Key: $API_KEY"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 "file=@my-plugin.zip"Install a plugin by downloading its .zip from a URL (SSRF-guarded).
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" }'Enable a plugin.
curl -X POST "$BASE/api/plugins/chat-flow/enable" \
-H "X-API-Key: $API_KEY"Disable a plugin.
curl -X POST "$BASE/api/plugins/chat-flow/disable" \
-H "X-API-Key: $API_KEY"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 } }'Set (or clear with {}) a per-session plugin config override.
curl -X PUT "$BASE/api/plugins/chat-flow/config/session-1" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "config": { "replyDelayMs": 3000 } }'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": ["*"] }'Update an installed plugin in place from a URL.
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" }'Uninstall a plugin (built-ins protected).
curl -X DELETE "$BASE/api/plugins/chat-flow" \
-H "X-API-Key: $API_KEY"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; auth is enforced per tool call. 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" \
-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" \
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }'
# Call a tool (arguments must match the tool's zod inputSchema)
curl -X POST "$BASE/mcp" \
-H "X-Api-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "session_send_text", "arguments": { "sessionId": "default", "to": "6281234567890", "text": "Hello from MCP" } } }'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=main 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 || 'main';
const socket = io(`${BASE_WS}/events`, {
auth: { apiKey: API_KEY }, // or transport.headers / ?apiKey=
});
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));