18 - SDK Design
This document describes SDK 0.7.0. Send idempotency, webhook failure redrive, message-window filters, poll choices, last-message types, and the event.response webhook event name require OpenWA 0.25.0 or later.
18.1 Overview
OpenWA ships five official, hand-written client libraries for the REST API. They are not generated from an OpenAPI spec — each is written directly against the real API surface (paths, request DTOs, response shapes) and unit-tested with a mocked HTTP transport that asserts on the exact request path, method, and body, so drift in what an SDK sends is caught at test time rather than in production. That mechanism says nothing about what an SDK expects back; see §18.6 for how response shapes are held to the contract.
The import names differ from the dist names where the ecosystem requires it. Python installs rmyndharis-openwa but imports openwa; the client class is OpenWAClient in JS/Python and OpenWA\Client in PHP.
Design Principles
- One client, fluent resources. A single client object (
OpenWAClient / OpenWA\Client) exposes every resource as a property — client.messages.sendText(...), client.sessions.start(...). All five SDKs expose the same resource surface; only the language idioms differ (camelCase methods + objects in JS/PHP/Java, snake_case methods + dicts in Python, exported fields + structs in Go).
- It is a request/response client, not an event SDK. There is no WebSocket, EventEmitter, or
client.on(...). To receive inbound messages and acks, register a webhook (the webhooks resource) and host your own receiver, checking X-OpenWA-Signature with the SDK helper (verifyWebhookSignature in JavaScript, verify_webhook_signature in Python, VerifyWebhookSignature in Go, WebhookSignature.verify in Java, WebhookSignature::verify in PHP), or connect to the real-time Socket.IO API directly (see API Specification §6.5).
- Typed errors. Non-2xx responses raise/throw a typed error mapped from the HTTP status (
401/403/404/409/429/501/503), plus a timeout error — all instanceof/catch-checkable. See each language's Error Handling subsection. A Baileys throttle 503 on a send or a single write means nothing was sent or applied, but a group settings update with several fields applies them one at a time, so a 503 on a later field leaves the earlier ones applied and lists them after already applied: in its message: re-read the settings before retrying, or send one field per request.
- Injectable transport. The HTTP layer is replaceable (
fetch in JS, an httpx transport in Python, a Guzzle client in PHP) — the extension point for retry/observability middleware and for testing without the network.
- Safe by default. Redirects are never followed (so the API key is never re-sent to a redirect target), the auth/JSON headers always take precedence over caller-supplied defaults, path segments are percent-encoded, a base-URL path prefix (e.g. behind a reverse proxy at
/v1) is preserved, and there is a default 30s per-request timeout. No automatic retries by default — in JS, Python, PHP, and Java wrap calls in your own backoff if you need them (especially for 429); the Go SDK additionally ships an opt-in WithRetry(RetryPolicy) that never replays a POST or PATCH after a network error and limits their retries to 429/503.
Resource Coverage
All five SDKs expose the same fluent surface:
| Resource |
Methods |
sessions |
list, get, getConfig, updateConfig, getProxy, updateProxy, create, delete, start, stop, logout, forceKill, getQrCode, requestPairingCode, setOnlinePresence, stats |
messages |
list, sendText, sendImage/Video/Audio/Document/Sticker, sendLocation, sendContact, sendTemplate, sendPoll, reply, forward, clickButton, react, delete, editMessage, history, reactions, media, pin, unpin, star, votePoll, sendBulk, batchStatus, cancelBatch |
contacts |
list, get, check, profilePicture, profilePictures, phone, upsert, delete, block, unblock, listBlocked |
groups |
list, get, create, joinInfo, joinGroup, add/remove/promote/demoteParticipants, setSubject, setDescription, setMemberLabel, getGroupSettings, updateGroupSettings, leave, getPicture, setPicture, deletePicture, inviteCode, revokeInviteCode, getMembershipRequests, approveMembershipRequests, rejectMembershipRequests |
webhooks |
list, listAll, deliveryFailures, redriveDeliveryFailures, get, create, update, delete, test |
chats |
list, subscribePresence, getPresence, markRead, markUnread, archive, pin, mute, clearMessages, delete, sendState |
labels |
list, get, chats, upsert, delete, forChat, addToChat, removeFromChat (WhatsApp Business) |
channels |
list, get, messages, create, delete, mute, subscribe, unsubscribe, demoteAdmin, transferOwnership (Newsletters) |
catalog |
info, products, product, sendProduct (WhatsApp Business) |
status |
list, fromContact, media, sendText, sendImage, sendVideo, sendVoice, delete (Stories) |
search |
search |
templates |
list, get, create, update, delete |
profile |
setProfileName, setProfileStatus, setProfilePicture, deleteProfilePicture |
calls |
rejectCall, createLink |
media |
conversionStatus, convertVoice (OPERATOR), convertVideo (OPERATOR) |
health |
check, live, ready |
The twelve single-recipient send methods (text, image, video, audio, document, sticker, location, contact, template, poll, reply and forward) take an optional per-call idempotency key: a trailing argument in JavaScript, PHP and Java, idempotency_key= in Python and openwa.WithIdempotencyKey(ctx, key) in Go. A retry of the same logical send reuses its key; see each SDK's README.
The SDKs cover the user-facing resources above and stop there. The administrative and operational surfaces are deliberately left out — auth/api-keys, audit, settings, stats, automation, infra, plugins and the integration management routes are predominantly ADMIN-gated; metrics is a @Public() Prometheus scrape gated by METRICS_TOKEN rather than by role; mcp is a Streamable-HTTP transport mounted straight onto the Express adapter; and ingress is the @Public() receiver that integration providers post into. docker has no HTTP surface at all — it is an internal service module. Methods that require an OPERATOR-level key are annotated OPERATOR in the per-language tables below.
18.2 TypeScript / JavaScript SDK
The official JavaScript/TypeScript SDK is published as @rmyndharis/openwa. It is a pure promise-based HTTP client: a single OpenWAClient exposes every API resource as a typed property. There is no event model — the SDK does not open WebSockets, emit events, or expose client.on(...). To receive inbound messages and acks, configure a webhook (see the webhooks resource) and host your own HTTP receiver, checking each delivery with await verifyWebhookSignature(rawBody, signature, secret) and typing its parsed body as WebhookDelivery.
The package ships dual CJS + ESM with bundled .d.ts types, so it is consumable from both require() and import.
Installation
npm install @rmyndharis/openwa
# or
yarn add @rmyndharis/openwa
# or
pnpm add @rmyndharis/openwa
Node 18+ required. The transport uses the global fetch (and AbortController), both built into Node 18 and later. To run on an older runtime, pass your own fetch implementation via the client constructor (see Client Configuration).
Quick Start
import { OpenWAClient } from '@rmyndharis/openwa';
const client = new OpenWAClient({
baseUrl: 'http://localhost:2785',
apiKey: 'owa_k1_…',
});
async function main() {
// Sessions are addressed by the UUID that create() returns, not by name. Create a session once;
// afterwards, find its id with client.sessions.list({ name: 'my-session' }).
const session = await client.sessions.create({ name: 'my-session' });
await client.sessions.start(session.id);
// Link the account before sending: scan sessions.getQrCode (or use sessions.requestPairingCode for a number with no linked session),
// then wait for status 'ready'. An unlinked session answers the send with 409.
// Send a text message.
const result = await client.messages.sendText(session.id, {
chatId: '[email protected]',
text: 'Hello from the OpenWA SDK!',
});
console.log(result.messageId); // -> the WhatsApp message id
}
main();
sendText resolves to a MessageResponse ({ messageId: string; timestamp: number }). timestamp is the Unix epoch value returned by the API — seconds, passed through unchanged.
CommonJS consumers use the same API via require:
const { OpenWAClient } = require('@rmyndharis/openwa');
Client Configuration
The constructor takes a single OpenWAClientOptions object. baseUrl and apiKey are required (the constructor throws synchronously if either is missing).
| Option |
Type |
Required |
Default |
Description |
baseUrl |
string |
yes |
— |
Base URL of the OpenWA API, e.g. http://localhost:2785. A trailing slash is trimmed; a path prefix (e.g. https://host/v1) is preserved. |
apiKey |
string |
yes |
— |
API key sent as the X-API-Key header on every request. Surrounding whitespace is trimmed; a control or non-Latin-1 character is refused when the client is built. |
timeoutMs |
number |
no |
30000 |
Per-request timeout in milliseconds; 0 or Infinity turns it off, and a value that is not a non-negative number throws a TypeError. Overridable per call via RequestOptions.timeoutMs on the raw request() method. |
defaultHeaders |
Record<string, string> |
no |
{} |
Headers merged onto every request. The Content-Type: application/json and X-API-Key headers always take precedence. A value with a control or non-Latin-1 character is refused when the client is built, naming the header. |
fetch |
FetchLike |
no |
globalThis.fetch |
Injectable transport (the WHATWG fetch signature). Use this to wrap requests with retry/observability middleware, or to supply a fetch on runtimes that lack a global one. |
Resources & Methods
All resources are accessed as properties on the client (client.<resource>.<method>). Every method returns a Promise. Methods marked OPERATOR require an OPERATOR-level API key (an ADMIN key satisfies it); a VIEWER key receives a 403 (OpenWAForbiddenError). Some methods are supported by one engine only and answer 501 on the other (a row says so where it matters; section 29.6 of the engine capability matrix lists them all).
The top-level client also exposes:
| Method |
Signature |
Description |
auth |
client.auth() |
Validate the configured API key and resolve its role and the running engine ({ valid, role?, engineType?, scoped? }); a key restricted to selected chats is refused with 403. |
request |
client.request<T>(options) |
Raw escape hatch — issue an arbitrary request against the API. |
sessions
| Method |
Signature |
Description |
list |
list(query?) |
List all sessions (scoped to the key's allowedSessions). The optional query takes limit, offset and name (an exact, case-sensitive match; no match returns an empty list). |
getConfig |
getConfig(id) |
Read a session's engine configuration. |
updateConfig |
updateConfig(id, body) |
Update a session's configuration, in any state, without a restart or re-link; autoRejectCalls applies immediately, the reconnect settings on the next start. OPERATOR |
getProxy |
getProxy(id) |
Read a session's masked proxy configuration (credentials never returned). |
updateProxy |
updateProxy(id, body) |
Update per-session proxy settings; changes apply on the next start, not to a running engine. Send proxyUrl: null to clear. ADMIN |
get |
get(id) |
Get a single session by id. |
create |
create(body) |
Create a new session (body.name required). OPERATOR; setting proxyUrl requires ADMIN |
delete |
delete(id) |
Delete a session. OPERATOR |
start |
start(id) |
Start a session and initialize the WhatsApp connection. OPERATOR |
stop |
stop(id) |
Stop a session and disconnect gracefully. OPERATOR |
logout |
logout(id) |
Attempt an engine-native unlink of this device, then stop the session. A 200 means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later start needs a fresh QR. A 502 (SESSION_LOGOUT_INCOMPLETE) stops locally but leaves the operation incomplete; start and retry. Requires a running session. OPERATOR |
forceKill |
forceKill(id) |
Force-kill a stuck session (SIGKILL + teardown). A 502 (SESSION_FORCE_KILL_INCOMPLETE) stops locally but the engine process may still be running; a retry answers 400, so restart the node to reap it. OPERATOR |
getQrCode |
getQrCode(id) |
Get the current QR code for authentication (live from the engine). OPERATOR |
requestPairingCode |
requestPairingCode(id, body) |
Request an 8-character pairing code for phone-based login. On whatsapp-web.js, not for a number that already has a linked session (WhatsApp can revoke that device; the gateway answers 409 for the stored phone of another of its sessions but cannot see a link made elsewhere); link it by QR instead. OPERATOR |
setOnlinePresence |
setOnlinePresence(id, body) |
Set the account's own global presence (appear online or offline). OPERATOR |
stats |
stats() |
Aggregate statistics across the key's sessions. |
messages
| Method |
Signature |
Description |
list |
list(sessionId, query?) |
List messages. Filters: type, direction, chatId, from, messageId, since (inclusive) and until (exclusive) as epoch milliseconds, orderBy (createdAt, or timestamp, which leaves out rows without a message time), limit, offset, after (keyset cursor: the id of the last row of the previous page; wins over offset) and inlineMedia (false omits inline media payloads). Returns { messages, total, unknownTimestampTotal? }; unknownTimestampTotal counts the rows matching the other filters whose message time is unknown, and is present only with a time bound or orderBy: 'timestamp'. |
sendText |
sendText(sessionId, { chatId, text }) |
Send a text message (text max 4096 chars). OPERATOR |
sendImage |
sendImage(sessionId, body) |
Send an image (url or base64). OPERATOR |
sendVideo |
sendVideo(sessionId, body) |
Send a video (url or base64). OPERATOR |
sendAudio |
sendAudio(sessionId, body) |
Send an audio file (url or base64). OPERATOR |
sendDocument |
sendDocument(sessionId, body) |
Send a document (url or base64; filename recommended). OPERATOR |
sendSticker |
sendSticker(sessionId, body) |
Send a sticker (url or base64). OPERATOR |
sendLocation |
sendLocation(sessionId, body) |
Send a location ({ chatId, latitude, longitude, description? }). OPERATOR |
sendContact |
sendContact(sessionId, body) |
Send a contact card. OPERATOR |
sendTemplate |
sendTemplate(sessionId, body) |
Render and send a stored message template. OPERATOR |
sendPoll |
sendPoll(sessionId, body) |
Send a poll message. OPERATOR |
reply |
reply(sessionId, body) |
Reply to a specific message. OPERATOR |
forward |
forward(sessionId, body) |
Forward a message to another chat. OPERATOR |
clickButton |
clickButton(sessionId, body) |
Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). OPERATOR |
react |
react(sessionId, body) |
React to a message (an empty emoji removes the reaction). OPERATOR |
delete |
delete(sessionId, body) |
Delete a message. OPERATOR |
editMessage |
editMessage(sessionId, body) |
Edit the text of a message already sent. OPERATOR |
history |
history(sessionId, chatId, query?) |
Get message history for a chat (read live from WhatsApp). |
reactions |
reactions(sessionId, chatId, messageId) |
Get reactions for a specific message. |
pin |
pin(sessionId, body) |
Pin a message in its chat. durationSeconds must be 86400, 604800 or 2592000; in a group only admins may pin. OPERATOR |
votePoll |
votePoll(sessionId, body) |
Cast a vote on a poll; options are the option texts, not ids. Not supported on Baileys (501). OPERATOR |
star |
star(sessionId, body) |
Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. OPERATOR |
unpin |
unpin(sessionId, body) |
Unpin a pinned message. OPERATOR |
media |
media(sessionId, chatId, messageId) |
Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. 404 when neither holds bytes. |
sendBulk |
sendBulk(sessionId, body) |
Send a batch asynchronously (202 + batch id); poll via batchStatus. OPERATOR |
batchStatus |
batchStatus(sessionId, batchId) |
Poll the status/progress of a bulk-send batch. |
cancelBatch |
cancelBatch(sessionId, batchId) |
Cancel a running batch. OPERATOR |
Media bodies share the SendMediaRequest shape: { chatId, url? | base64?, mimetype?, filename?, caption? } (url and base64 are mutually exclusive; base64 requires mimetype).
contacts
| Method |
Signature |
Description |
list |
list(sessionId, query?) |
List contacts known to the session. |
get |
get(sessionId, contactId) |
Get details for a single contact by JID. |
check |
check(sessionId, number) |
Check whether a phone number is registered on WhatsApp. OPERATOR |
profilePicture |
profilePicture(sessionId, contactId) |
Get the contact's profile picture URL (or null). |
profilePictures |
profilePictures(sessionId, ids) |
Profile picture URLs for up to 50 contacts; ids skipped after a timeout are absent. |
phone |
phone(sessionId, contactId) |
Resolve a contact id (e.g. a @lid) to a phone number. |
block |
block(sessionId, contactId) |
Block a contact. OPERATOR |
upsert |
upsert(sessionId, contactId, body) |
Save a contact to the account's addressbook, or edit an existing entry. OPERATOR |
delete |
delete(sessionId, contactId) |
Remove a contact from the account's addressbook. OPERATOR |
unblock |
unblock(sessionId, contactId) |
Unblock a contact. OPERATOR |
listBlocked |
listBlocked(sessionId) |
List the ids this account has blocked. Session-wide, so it takes no contact id. |
groups
| Method |
Signature |
Description |
list |
list(sessionId, query?) |
List all groups for the session. |
get |
get(sessionId, groupId) |
Get detailed group info including participants. |
create |
create(sessionId, body) |
Create a new group. OPERATOR |
joinInfo |
joinInfo(sessionId, code) |
Preview a group from its invite code WITHOUT joining. Read-only, so it is safe to call on a code from an untrusted source. |
joinGroup |
joinGroup(sessionId, body) |
Join a group via its invite code. OPERATOR |
addParticipants |
addParticipants(sessionId, groupId, participants) |
Add participants (string[]) to a group. OPERATOR |
removeParticipants |
removeParticipants(sessionId, groupId, participants) |
Remove participants from a group. OPERATOR |
promoteParticipants |
promoteParticipants(sessionId, groupId, participants) |
Promote participants to group admin. OPERATOR |
demoteParticipants |
demoteParticipants(sessionId, groupId, participants) |
Demote participants from group admin. OPERATOR |
setSubject |
setSubject(sessionId, groupId, subject) |
Update the group subject (name). OPERATOR |
setDescription |
setDescription(sessionId, groupId, description) |
Update the group description (empty clears it). OPERATOR |
setMemberLabel |
setMemberLabel(sessionId, groupId, label) |
Set this account's member label in the group (empty clears it; Baileys only, whatsapp-web.js answers 501). OPERATOR |
getGroupSettings |
getGroupSettings(sessionId, groupId) |
Get the group settings (announce / locked / ephemeral timer / who may add members). |
updateGroupSettings |
updateGroupSettings(sessionId, groupId, body) |
Update the group settings (at least one field required). OPERATOR |
leave |
leave(sessionId, groupId) |
Leave a group. OPERATOR |
getPicture |
getPicture(sessionId, groupId) |
The group's picture URL, or null when it has none. |
setPicture |
setPicture(sessionId, groupId, body) |
Set the group's picture. OPERATOR |
deletePicture |
deletePicture(sessionId, groupId) |
Remove the group's picture. OPERATOR |
inviteCode |
inviteCode(sessionId, groupId) |
Get the group invite code and link. OPERATOR |
revokeInviteCode |
revokeInviteCode(sessionId, groupId) |
Revoke the current invite code and generate a new one. OPERATOR |
getMembershipRequests |
getMembershipRequests(sessionId, groupId) |
List a group's pending join requests. Requires group admin. |
approveMembershipRequests |
approveMembershipRequests(sessionId, groupId, participants?) |
Approve pending join requests; omit the list to approve all. OPERATOR |
rejectMembershipRequests |
rejectMembershipRequests(sessionId, groupId, participants?) |
Reject pending join requests; omit the list to reject all. OPERATOR |
chats
| Method |
Signature |
Description |
list |
list(sessionId, query?) |
List active chats, most recent first. |
subscribePresence |
subscribePresence(sessionId, body) |
Subscribe to a chat's presence; updates then arrive as presence.update events. The subscription belongs to the connection and does not survive a reconnect. OPERATOR |
getPresence |
getPresence(sessionId, chatId) |
The last presence reported for a chat, or null when none has been. Held in memory, so a restart clears it. |
markRead |
markRead(sessionId, body) |
Mark a chat as read/seen. OPERATOR |
markUnread |
markUnread(sessionId, body) |
Mark a chat as unread. OPERATOR |
archive |
archive(sessionId, body) |
Archive or unarchive a chat. success: false means the engine declined. OPERATOR |
pin |
pin(sessionId, body) |
Pin a chat to the top of the list, or unpin it. success: false means WhatsApp declined — three pins maximum. OPERATOR |
mute |
mute(sessionId, body) |
Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with null. OPERATOR |
clearMessages |
clearMessages(sessionId, chatId) |
Delete every message in a chat, keeping the chat itself. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. OPERATOR |
delete |
delete(sessionId, body) |
Delete a chat from the chat list. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. OPERATOR |
sendState |
sendState(sessionId, body) |
Send a chat presence state (typing/recording/paused). OPERATOR |
webhooks
| Method |
Signature |
Description |
listAll |
listAll(query?) |
List webhooks across EVERY session the key can see, not one session's. OPERATOR |
deliveryFailures |
deliveryFailures(query?) |
Deliveries that exhausted their retries (attempts > 0), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (attempts: 0); a later successful delivery removes the row; the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. ADMIN |
redriveDeliveryFailures |
redriveDeliveryFailures(body?) |
Replay the rows deliveryFailures marks replayable (kept while WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS > 0), fewest attempts first, then oldest, one bounded batch per call, reusing each stored idempotency key; returns delivered/failed/skipped/remaining counts; enqueued is always 0. ADMIN |
list |
list(sessionId) |
List all webhooks for a session. OPERATOR |
get |
get(sessionId, id) |
Get a single webhook by id. OPERATOR |
create |
create(sessionId, body) |
Create a new webhook. OPERATOR |
update |
update(sessionId, id, body) |
Update a webhook. OPERATOR |
delete |
delete(sessionId, id) |
Delete a webhook. OPERATOR |
test |
test(sessionId, id) |
Trigger a test dispatch to the webhook URL and report the result. OPERATOR |
labels (WhatsApp Business)
| Method |
Signature |
Description |
list |
list(sessionId) |
List all labels available in the business account. |
get |
get(sessionId, labelId) |
Get a single label by id. |
chats |
chats(sessionId, labelId) |
Every chat carrying a label. whatsapp-web.js only — Baileys answers 501. |
upsert |
upsert(sessionId, labelId, body) |
Create or update a label. Baileys only — whatsapp-web.js answers 501. OPERATOR |
delete |
delete(sessionId, labelId) |
Delete a label. OPERATOR |
forChat |
forChat(sessionId, chatId) |
Get the labels currently applied to a chat. |
addToChat |
addToChat(sessionId, chatId, body) |
Add a label to a chat. OPERATOR |
removeFromChat |
removeFromChat(sessionId, chatId, labelId) |
Remove a label from a chat. OPERATOR |
channels (Newsletters)
| Method |
Signature |
Description |
list |
list(sessionId) |
List all channels/newsletters the session is subscribed to. |
get |
get(sessionId, channelId) |
Get a single channel by id. |
messages |
messages(sessionId, channelId, query?) |
Get recent messages from a channel. |
create |
create(sessionId, body) |
Create a channel this account owns. OPERATOR |
delete |
delete(sessionId, channelId) |
Delete a channel this account owns. Irreversible, and every subscriber loses it — distinct from unsubscribe. OPERATOR |
mute |
mute(sessionId, channelId, body) |
Mute or unmute a channel's notifications. OPERATOR |
subscribe |
subscribe(sessionId, body) |
Subscribe to a channel using its invite code. OPERATOR |
unsubscribe |
unsubscribe(sessionId, channelId) |
Unsubscribe from a channel. OPERATOR |
demoteAdmin |
demoteAdmin(sessionId, channelId, body) |
Demote a channel admin back to a subscriber; no promote counterpart exists. OPERATOR |
transferOwnership |
transferOwnership(sessionId, channelId, body) |
Hand a channel to a new owner. Irreversible. OPERATOR |
catalog (WhatsApp Business)
| Method |
Signature |
Description |
info |
info(sessionId) |
Get the business catalog info, or null when the account has no catalog. |
products |
products(sessionId, query?) |
List catalog products; returns { products, pagination }. |
product |
product(sessionId, productId) |
Get a single product by id, or null when no product in the catalog carries that id. |
sendProduct |
sendProduct(sessionId, body) |
Send a product message. OPERATOR |
status (Stories)
| Method |
Signature |
Description |
list |
list(sessionId) |
Get all status updates ({ statuses }). |
fromContact |
fromContact(sessionId, contactId) |
Get status updates from a specific contact. |
media |
media(sessionId, statusId) |
Fetch the stored media bytes for a status update (404 when there is none). |
sendText |
sendText(sessionId, body) |
Post a text status update. OPERATOR |
sendImage |
sendImage(sessionId, body) |
Post an image status update. OPERATOR |
sendVideo |
sendVideo(sessionId, body) |
Post a video status update. OPERATOR |
sendVoice |
sendVoice(sessionId, body) |
Post an audio status as a voice note. WhatsApp plays one only as Ogg/Opus and neither engine transcodes, so convert with media.convertVoice first. OPERATOR |
delete |
delete(sessionId, statusId) |
Delete a status update by id. OPERATOR |
This is WhatsApp "Status/Stories", distinct from session lifecycle status.
search
| Method |
Signature |
Description |
search |
search(params) |
Search persisted messages across sessions via the active search provider; a scoped key's reach is bounded by its allowedSessions. OPERATOR |
templates
| Method |
Signature |
Description |
list |
list(sessionId) |
List all templates for a session. OPERATOR |
get |
get(sessionId, id) |
Get a single template by id. OPERATOR |
create |
create(sessionId, body) |
Create a new template. OPERATOR |
update |
update(sessionId, id, body) |
Update a template. OPERATOR |
delete |
delete(sessionId, id) |
Delete a template. OPERATOR |
profile
| Method |
Signature |
Description |
setProfileName |
setProfileName(sessionId, name) |
Set the account display name. OPERATOR |
setProfileStatus |
setProfileStatus(sessionId, status) |
Set the account about/status text (empty clears it). OPERATOR |
setProfilePicture |
setProfilePicture(sessionId, body) |
Set the account profile picture (url or base64 + mimetype). OPERATOR |
deleteProfilePicture |
deleteProfilePicture(sessionId) |
Remove the account profile picture. OPERATOR |
calls
| Method |
Signature |
Description |
rejectCall |
rejectCall(sessionId, callId) |
Reject a ringing incoming call (callId comes from the call.received event). Baileys only: whatsapp-web.js answers 501. OPERATOR |
createLink |
createLink(sessionId, body) |
Create a shareable WhatsApp call link (startTime is epoch MILLISECONDS). OPERATOR |
media
| Method |
Signature |
Description |
conversionStatus |
conversionStatus(sessionId) |
Whether conversion is switched on for this deployment AND the ffmpeg binary can be run. |
convertVoice |
convertVoice(sessionId, input) |
Convert audio into a WhatsApp voice note (Ogg/Opus, mono, tuned for speech). OPERATOR |
convertVideo |
convertVideo(sessionId, input) |
Convert video into an MP4 every WhatsApp client accepts (baseline H.264 + AAC). OPERATOR |
health
| Method |
Signature |
Description |
check |
check() |
General health (also returns the running version). |
live |
live() |
Kubernetes liveness probe ({ status }). |
ready |
ready() |
Kubernetes readiness probe — checks both DB connections. |
Error Handling
On a non-2xx response the SDK throws a typed OpenWAApiError subclass carrying .status (HTTP status), .body (parsed JSON error envelope, or raw text), and .errorKind (the NestJS error field, undefined when the gateway omits it — which is the norm for a validation rejection in production, where disableErrorMessages is on). All error classes extend OpenWAError and are exported, so they are instanceof-checkable. A timeout throws OpenWATimeoutError, which extends OpenWAError directly (not OpenWAApiError). An API error also carries .code (the body's code, e.g. SEND_PACING_LIMITED), .retryAfterSeconds (the body's retryAfterSeconds, else the Retry-After header) and .headers (the response Headers).
| Error class |
HTTP status |
Meaning |
OpenWAAuthError |
401 |
Missing or invalid API key. |
OpenWAForbiddenError |
403 |
The key's role or scope refuses the call (e.g. an OPERATOR-only route, or a session, IP or chat outside the key's allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
OpenWANotFoundError |
404 |
Resource not found. |
OpenWAConflictError |
409 |
Conflict: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see code). |
OpenWARateLimitError |
429 |
Rate limited. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and retryAfterSeconds carries its Retry-After header. A 429 whose code is "SEND_PACING_LIMITED" is usually not transient: do not retry it before retryAfterSeconds, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (SEND_PACING_BREAKER_COOLDOWN_MS, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. |
OpenWANotImplementedError |
501 |
The active engine does not support this operation. |
OpenWAServiceUnavailableError |
503 |
The gateway could not complete the request now (transport failure, draining, or on Baileys a WhatsApp throttle (429) or timeout (408)). Back off and retry later, though a catalog 503 can persist because WhatsApp may never answer that query; 501 is permanent. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |
OpenWAApiError |
any other |
Generic non-2xx (the base API error, e.g. 400; also surfaced for unfollowed 3xx redirects). |
OpenWATimeoutError |
— |
The request exceeded the configured timeout. |
import {
OpenWAClient,
OpenWAConflictError,
OpenWANotFoundError,
OpenWARateLimitError,
OpenWATimeoutError,
OpenWAApiError,
} from '@rmyndharis/openwa';
try {
await client.messages.sendText(sessionId, {
chatId: '[email protected]',
text: 'Hi!',
});
} catch (err) {
if (err instanceof OpenWAConflictError) {
// 409: a conflicting state, typically a session that is not ready (start it first), or a keyed send pending or unconfirmed (see err.code).
} else if (err instanceof OpenWANotFoundError) {
// 404 — session/chat does not exist.
} else if (err instanceof OpenWARateLimitError) {
// 429 — back off and retry.
} else if (err instanceof OpenWATimeoutError) {
// request timed out.
} else if (err instanceof OpenWAApiError) {
console.error(`API error ${err.status}:`, err.body);
} else {
throw err; // network/transport error
}
}
Notable Behaviors
- Redirects are never followed. The transport uses
redirect: 'manual', so a 3xx surfaces to the caller as an error (via OpenWAApiError) rather than being followed — this guarantees the X-API-Key header is never re-sent to a redirect target (potentially a different origin).
- Auth and JSON headers take precedence. Request headers are merged in the order
defaultHeaders → per-call headers → Content-Type: application/json → X-API-Key. Both Content-Type and X-API-Key are applied last, so neither can be overridden by a caller-supplied header.
- Path segments are percent-encoded. Ids (session, chat, message, etc.) are encoded so a value cannot break out of its path position, while keeping the WhatsApp-safe characters
@, :, and + readable (e.g. [email protected]).
- Empty and dot segments are refused. An empty,
. or .. id rejects with a TypeError and nothing is sent, because fetch would otherwise resolve it to the parent resource. A raw request()/requestBytes() path with a . or .. segment rejects with a TypeError, and so does one that does not begin with /; a trailing or double slash in a raw path is sent as written.
- Base-URL path prefix is preserved. A
baseUrl such as https://gateway.example.com/v1 keeps its /v1 prefix on every request; only a trailing slash is trimmed.
- No automatic retries. A failed request rejects immediately — the SDK does not retry, even on
429. Wrap calls in your own backoff if you need retries.
- Injectable transport. Supply a custom
fetch to wrap outbound calls with retry, logging, or observability middleware, or to run on a runtime without a global fetch. This is also the recommended way to unit-test without monkey-patching globals.
- Dual CJS + ESM. The package exposes both an
import (ESM) and require (CommonJS) entry point with bundled type declarations, so it works in either module system without configuration.
18.3 Python SDK
The Python SDK is a synchronous client built on httpx. It ships its own type hints (PEP 561) so editors and type-checkers see the full surface without stubs. There is no async client and no event/streaming model — every call is a blocking method that returns a plain dict/list (or None for a 204), and request payloads are plain dicts.
Installation
The PyPI distribution name and the import package differ:
pip install rmyndharis-openwa
from openwa import OpenWAClient
- Distribution (PyPI):
rmyndharis-openwa
- Import package:
openwa
- Client class:
OpenWAClient
- Python:
>=3.9 (per pyproject.toml)
- Runtime dependencies:
httpx>=0.27.1,<1.0, plus typing_extensions>=4.0 on Python < 3.11
- Typed: ships
py.typed markers for openwa and openwa.resources (PEP 561)
Quick Start
from openwa import OpenWAClient
client = OpenWAClient(
base_url="http://localhost:2785",
api_key="owa_k1_…",
)
# Sessions are addressed by the UUID that create() returns, not by name. Create a session once;
# afterwards, find its id with client.sessions.list({"name": "my-session"}).
session = client.sessions.create({"name": "my-session"})
client.sessions.start(session["id"])
# Link the account before sending: scan sessions.get_qr_code (or use sessions.request_pairing_code for a number with no linked session),
# then wait for status "ready". An unlinked session answers the send with 409.
# Send a text message
result = client.messages.send_text(session["id"], {
"chatId": "[email protected]",
"text": "Hello from the OpenWA Python SDK!",
})
print(result["messageId"])
client.close()
OpenWAClient is also a context manager, so the connection pool is closed for you:
with OpenWAClient(base_url="http://localhost:2785", api_key="owa_k1_…") as client:
print(client.health.check())
Client Configuration
Constructor signature (from client.py):
OpenWAClient(
base_url: str,
api_key: str,
*,
timeout: float | httpx.Timeout | tuple[float | None, float | None, float | None, float | None] | None = 30.0,
default_headers: Mapping[str, str] | None = None,
transport: httpx.BaseTransport | None = None,
)
| Parameter |
Type |
Default |
Description |
base_url |
str |
(required) |
Gateway base URL, e.g. http://localhost:2785. Raises ValueError if empty. A trailing / is stripped; any path prefix is preserved. |
api_key |
str |
(required) |
API key sent as the X-API-Key header. Surrounding whitespace is trimmed; raises ValueError if empty or if it holds a control or non-ASCII character. |
timeout |
float | httpx.Timeout | tuple | None |
30.0 |
Seconds per network operation, not per call; 0, inf or None turns it off. An httpx.Timeout or a (connect, read, write, pool) tuple sets the operations apart. A breach raises OpenWATimeoutError. |
default_headers |
Mapping[str, str] | None |
None |
Extra headers applied to every request. Applied first, so the SDK's X-API-Key and Content-Type: application/json always win. A name must be an HTTP token and a value text without a control or non-ASCII character (surrounding spaces are trimmed); ValueError names the header, never the value. |
transport |
httpx.BaseTransport | None |
None |
Optional httpx transport override (e.g. httpx.MockTransport) sharing the one connection pool. Useful for testing. |
The client also exposes a few non-resource members:
| Member |
Signature |
Description |
auth |
auth() -> AuthValidateResponse |
POST /api/auth/validate — validate the configured API key; a key restricted to selected chats is refused with 403. |
request |
request(method, path, *, query=None, body=None) -> Any |
Raw escape hatch; path begins with /. |
close |
close() -> None |
Close the underlying httpx.Client. |
Resources & Methods
Resources are accessed as properties on the client (e.g. client.messages). All methods are snake_case; body/query arguments are plain dicts. Methods marked OPERATOR require an OPERATOR-level API key. Some methods are supported by one engine only and answer 501 on the other (a row says so where it matters; section 29.6 of the engine capability matrix lists them all).
client.sessions
| Method |
Signature |
Description |
list |
list(query=None) -> list[SessionResponse] |
List all sessions. The optional query takes limit, offset and name (an exact, case-sensitive match; no match returns an empty list). |
get_config |
get_config(session_id) -> SessionConfig |
Read a session's engine configuration. |
update_config |
update_config(session_id, body) -> SessionConfig |
Update a session's configuration, in any state, without a restart or re-link; autoRejectCalls applies immediately, the reconnect settings on the next start. OPERATOR |
get_proxy |
get_proxy(session_id) -> SessionProxy |
Read a session's masked proxy configuration (credentials never returned). |
update_proxy |
update_proxy(session_id, body) -> SessionProxy |
Update per-session proxy settings; changes apply on the next start. Send proxyUrl: null to clear. ADMIN |
get |
get(session_id) -> SessionResponse |
Get one session. |
create |
create(body) -> SessionResponse |
Create a session (body["name"] required). OPERATOR; setting proxyUrl requires ADMIN |
delete |
delete(session_id) -> None |
Delete a session. OPERATOR |
start |
start(session_id) -> SessionResponse |
Start (connect) a session. OPERATOR |
stop |
stop(session_id) -> SessionResponse |
Stop a session. OPERATOR |
logout |
logout(session_id) -> SessionResponse |
Attempt an engine-native unlink of this device, then stop the session. A 200 means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later start needs a fresh QR. A 502 (SESSION_LOGOUT_INCOMPLETE) stops locally but leaves the operation incomplete; start and retry. Requires a running session. OPERATOR |
force_kill |
force_kill(session_id) -> SessionResponse |
Force-terminate a session. A 502 (SESSION_FORCE_KILL_INCOMPLETE) stops locally but the engine process may still be running; a retry answers 400, so restart the node to reap it. OPERATOR |
get_qr_code |
get_qr_code(session_id) -> QrCodeResponse |
Fetch the login QR code. OPERATOR |
request_pairing_code |
request_pairing_code(session_id, body) -> PairingCodeResponse |
Request a phone-number pairing code. On whatsapp-web.js, not for a number that already has a linked session (WhatsApp can revoke that device; the gateway answers 409 for the stored phone of another of its sessions but cannot see a link made elsewhere); link it by QR instead. OPERATOR |
set_online_presence |
set_online_presence(session_id, body) -> SuccessResult |
Set the account's own global presence (appear online or offline). OPERATOR |
stats |
stats() -> SessionStatsOverview |
Session statistics overview. |
client.messages
| Method |
Signature |
Description |
list |
list(session_id, query=None) -> MessageListResponse |
List stored messages; the query takes the same keys as the JavaScript client's messages.list, and the response carries unknownTimestampTotal under the same conditions. |
send_text |
send_text(session_id, body) -> MessageResponse |
Send a text message. OPERATOR |
send_image |
send_image(session_id, body) -> MessageResponse |
Send an image. OPERATOR |
send_video |
send_video(session_id, body) -> MessageResponse |
Send a video. OPERATOR |
send_audio |
send_audio(session_id, body) -> MessageResponse |
Send audio. OPERATOR |
send_document |
send_document(session_id, body) -> MessageResponse |
Send a document. OPERATOR |
send_sticker |
send_sticker(session_id, body) -> MessageResponse |
Send a sticker. OPERATOR |
send_location |
send_location(session_id, body) -> MessageResponse |
Send a location. OPERATOR |
send_contact |
send_contact(session_id, body) -> MessageResponse |
Send a contact card. OPERATOR |
send_template |
send_template(session_id, body) -> MessageResponse |
Send a stored template. OPERATOR |
send_poll |
send_poll(session_id, body) -> MessageResponse |
Send a poll message. OPERATOR |
reply |
reply(session_id, body) -> MessageResponse |
Reply to a message. OPERATOR |
forward |
forward(session_id, body) -> MessageResponse |
Forward a message. OPERATOR |
click_button |
click_button(session_id, body) -> MessageResponse |
Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). OPERATOR |
react |
react(session_id, body) -> SuccessResult |
React to a message. OPERATOR |
delete |
delete(session_id, body) -> SuccessResult |
Delete a message. OPERATOR |
edit_message |
edit_message(session_id, body) -> MessageResponse |
Edit the text of a message already sent. OPERATOR |
history |
history(session_id, chat_id, query=None) -> list[ChatHistoryMessage] |
Fetch chat history. |
reactions |
reactions(session_id, chat_id, message_id) -> list[ReactionRecord] |
List reactions on a message. |
pin |
pin(session_id, body) -> SuccessResult |
Pin a message in its chat. durationSeconds must be 86400, 604800 or 2592000; in a group only admins may pin. OPERATOR |
vote_poll |
vote_poll(session_id, body) -> SuccessResult |
Cast a vote on a poll; options are the option texts, not ids. Not supported on Baileys (501). OPERATOR |
star |
star(session_id, body) -> SuccessResult |
Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. OPERATOR |
unpin |
unpin(session_id, body) -> SuccessResult |
Unpin a pinned message. OPERATOR |
media |
media(session_id, chat_id, message_id) -> MessageMedia |
Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. 404 when neither holds bytes. |
send_bulk |
send_bulk(session_id, body) -> BulkMessageResponse |
Enqueue a bulk send batch. OPERATOR |
batch_status |
batch_status(session_id, batch_id) -> BatchStatusResponse |
Get bulk batch status. |
cancel_batch |
cancel_batch(session_id, batch_id) -> BatchCancelResponse |
Cancel a running batch. OPERATOR |
client.contacts
| Method |
Signature |
Description |
list |
list(session_id, query=None) -> list[ContactRecord] |
List contacts (query: limit, offset). |
get |
get(session_id, contact_id) -> ContactRecord |
Get one contact. |
check |
check(session_id, number) -> CheckNumberResponse |
Check whether a number is on WhatsApp. OPERATOR |
profile_picture |
profile_picture(session_id, contact_id) -> ProfilePictureResponse |
Get a contact's profile picture. |
profile_pictures |
profile_pictures(session_id, ids) -> ProfilePicturesResponse |
Profile picture URLs for up to 50 contacts; ids skipped after a timeout are absent. |
phone |
phone(session_id, contact_id) -> ContactPhoneResponse |
Resolve a contact's phone number. |
block |
block(session_id, contact_id) -> SuccessResult |
Block a contact. OPERATOR |
upsert |
upsert(session_id, contact_id, body) -> SuccessResult |
Save a contact to the account's addressbook, or edit an existing entry. OPERATOR |
delete |
delete(session_id, contact_id) -> SuccessResult |
Remove a contact from the account's addressbook. OPERATOR |
unblock |
unblock(session_id, contact_id) -> SuccessResult |
Unblock a contact. OPERATOR |
list_blocked |
list_blocked(session_id) -> list[str] |
List the ids this account has blocked. Session-wide, so it takes no contact id. |
client.groups
| Method |
Signature |
Description |
list |
list(session_id, query=None) -> list[GroupSummary] |
List groups (query: limit, offset). |
get |
get(session_id, group_id) -> GroupInfo |
Get group details. |
create |
create(session_id, body) -> GroupSummary |
Create a group. OPERATOR |
join_info |
join_info(session_id, code) -> GroupJoinInfo |
Preview a group from its invite code WITHOUT joining. Read-only, so it is safe to call on a code from an untrusted source. |
join_group |
join_group(session_id, body) -> JoinGroupResponse |
Join a group via its invite code. OPERATOR |
add_participants |
add_participants(session_id, group_id, participants) -> ParticipantsResult |
Add participants (list[str]). A partial refusal still answers 200, so check results. OPERATOR |
remove_participants |
remove_participants(session_id, group_id, participants) -> ParticipantsResult |
Remove participants. A partial refusal still answers 200, so check results. OPERATOR |
promote_participants |
promote_participants(session_id, group_id, participants) -> ParticipantsResult |
Promote to admin. A partial refusal still answers 200, so check results. OPERATOR |
demote_participants |
demote_participants(session_id, group_id, participants) -> ParticipantsResult |
Demote from admin. A partial refusal still answers 200, so check results. OPERATOR |
set_subject |
set_subject(session_id, group_id, subject) -> SuccessResult |
Set group subject. OPERATOR |
set_description |
set_description(session_id, group_id, description) -> SuccessResult |
Set group description. OPERATOR |
set_member_label |
set_member_label(session_id, group_id, label) -> SuccessResult |
Set this account's member label in the group (empty clears it; Baileys only). OPERATOR |
get_group_settings |
get_group_settings(session_id, group_id) -> GroupSettings |
Get the group settings (announce / locked / ephemeral timer / who may add members). |
update_group_settings |
update_group_settings(session_id, group_id, body) -> SuccessResult |
Update the group settings (at least one field required). OPERATOR |
leave |
leave(session_id, group_id) -> SuccessResult |
Leave the group. OPERATOR |
get_picture |
get_picture(session_id, group_id) -> dict[str, Any] |
The group's picture URL, or null when it has none. |
set_picture |
set_picture(session_id, group_id, body) -> SuccessResult |
Set the group's picture. OPERATOR |
delete_picture |
delete_picture(session_id, group_id) -> SuccessResult |
Remove the group's picture. OPERATOR |
invite_code |
invite_code(session_id, group_id) -> InviteCodeResponse |
Get the invite code. OPERATOR |
revoke_invite_code |
revoke_invite_code(session_id, group_id) -> InviteCodeResponse |
Revoke and regenerate the invite code. OPERATOR |
get_membership_requests |
get_membership_requests(session_id, group_id) -> list[GroupMembershipRequest] |
List a group's pending join requests. Requires group admin. |
approve_membership_requests |
approve_membership_requests(session_id, group_id, participants=None) -> ParticipantsResult |
Approve pending join requests; omit the list to approve all. OPERATOR |
reject_membership_requests |
reject_membership_requests(session_id, group_id, participants=None) -> ParticipantsResult |
Reject pending join requests; omit the list to reject all. OPERATOR |
client.chats
| Method |
Signature |
Description |
list |
list(session_id, query=None) -> list[ChatSummary] |
List chats (query: limit, offset). |
subscribe_presence |
subscribe_presence(session_id, body) -> SuccessResult |
Subscribe to a chat's presence; updates then arrive as presence.update events. The subscription belongs to the connection and does not survive a reconnect. OPERATOR |
get_presence |
get_presence(session_id, chat_id) -> ChatPresence | None |
The last presence reported for a chat, or null when none has been. Held in memory, so a restart clears it. |
mark_read |
mark_read(session_id, body) -> SuccessResult |
Mark a chat as read. OPERATOR |
mark_unread |
mark_unread(session_id, body) -> SuccessResult |
Mark a chat as unread. OPERATOR |
archive |
archive(session_id, body) -> SuccessResult |
Archive or unarchive a chat. success: false means the engine declined. OPERATOR |
pin |
pin(session_id, body) -> SuccessResult |
Pin a chat to the top of the list, or unpin it. success: false means WhatsApp declined — three pins maximum. OPERATOR |
mute |
mute(session_id, body) -> SuccessResult |
Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with null. OPERATOR |
clear_messages |
clear_messages(session_id, chat_id) -> SuccessResult |
Delete every message in a chat, keeping the chat itself. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. OPERATOR |
delete |
delete(session_id, body) -> SuccessResult |
Delete a chat. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. OPERATOR |
send_state |
send_state(session_id, body) -> SuccessResult |
Send a typing/recording chat state. OPERATOR |
client.webhooks
| Method |
Signature |
Description |
list_all |
list_all(query=None) -> list[WebhookResponse] |
List webhooks across EVERY session the key can see, not one session's. OPERATOR |
delivery_failures |
delivery_failures(query=None) -> list[WebhookDeliveryFailure] |
Deliveries that exhausted their retries (attempts > 0), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (attempts: 0); a later successful delivery removes the row; the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. ADMIN |
redrive_delivery_failures |
redrive_delivery_failures(body=None) -> WebhookRedriveResult |
Replay the rows delivery_failures marks replayable (kept while WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS > 0), fewest attempts first, then oldest, one bounded batch per call, reusing each stored idempotency key; returns delivered/failed/skipped/remaining counts; enqueued is always 0. ADMIN |
list |
list(session_id) -> list[WebhookResponse] |
List webhooks. OPERATOR |
get |
get(session_id, webhook_id) -> WebhookResponse |
Get one webhook. OPERATOR |
create |
create(session_id, body) -> WebhookResponse |
Create a webhook. OPERATOR |
update |
update(session_id, webhook_id, body) -> WebhookResponse |
Update a webhook. OPERATOR |
delete |
delete(session_id, webhook_id) -> None |
Delete a webhook. OPERATOR |
test |
test(session_id, webhook_id) -> WebhookTestResult |
Send a test delivery. OPERATOR |
client.labels (WhatsApp Business)
| Method |
Signature |
Description |
list |
list(session_id) -> list[LabelRecord] |
List labels. |
get |
get(session_id, label_id) -> LabelRecord |
Get one label. |
chats |
chats(session_id, label_id) -> list[ChatSummary] |
Every chat carrying a label. whatsapp-web.js only — Baileys answers 501. |
upsert |
upsert(session_id, label_id, body) -> SuccessResult |
Create or update a label. Baileys only — whatsapp-web.js answers 501. OPERATOR |
delete |
delete(session_id, label_id) -> SuccessResult |
Delete a label. OPERATOR |
for_chat |
for_chat(session_id, chat_id) -> list[LabelRecord] |
Labels applied to a chat. |
add_to_chat |
add_to_chat(session_id, chat_id, body) -> SuccessResult |
Add a label to a chat. OPERATOR |
remove_from_chat |
remove_from_chat(session_id, chat_id, label_id) -> SuccessResult |
Remove a label from a chat. OPERATOR |
client.channels (Newsletters)
| Method |
Signature |
Description |
list |
list(session_id) -> list[ChannelRecord] |
List subscribed channels. |
get |
get(session_id, channel_id) -> ChannelRecord |
Get one channel. |
messages |
messages(session_id, channel_id, query=None) -> list[ChannelMessageRecord] |
List channel messages. |
create |
create(session_id, body) -> ChannelRecord |
Create a channel this account owns. OPERATOR |
delete |
delete(session_id, channel_id) -> SuccessResult |
Delete a channel this account owns. Irreversible, and every subscriber loses it — distinct from unsubscribe. OPERATOR |
mute |
mute(session_id, channel_id, body) -> SuccessResult |
Mute or unmute a channel's notifications. OPERATOR |
subscribe |
subscribe(session_id, body) -> ChannelRecord |
Subscribe via invite code. OPERATOR |
unsubscribe |
unsubscribe(session_id, channel_id) -> SuccessResult |
Unsubscribe from a channel. OPERATOR |
demote_admin |
demote_admin(session_id, channel_id, body) -> SuccessResult |
Demote a channel admin back to a subscriber; no promote counterpart exists. OPERATOR |
transfer_ownership |
transfer_ownership(session_id, channel_id, body) -> SuccessResult |
Hand a channel to a new owner. Irreversible. OPERATOR |
client.catalog (WhatsApp Business)
| Method |
Signature |
Description |
info |
info(session_id) -> CatalogInfo | None |
Get catalog info, or None when the account has no catalog. |
products |
products(session_id, query=None) -> PaginatedProducts |
List products (paginated). |
product |
product(session_id, product_id) -> CatalogProduct | None |
Get one product, or None when no product has that id. |
send_product |
send_product(session_id, body) -> ProductMessageResponse |
Send a product message; the message id is under id, not messageId. OPERATOR |
client.status (Stories)
| Method |
Signature |
Description |
list |
list(session_id) -> dict[str, list[StatusRecord]] |
List all status updates. |
from_contact |
from_contact(session_id, contact_id) -> dict[str, list[StatusRecord]] |
Status updates from one contact. |
media |
media(session_id, status_id) -> StatusMedia |
Fetch the stored media bytes for a status update. |
send_text |
send_text(session_id, body) -> StatusResult |
Post a text status. OPERATOR |
send_image |
send_image(session_id, body) -> StatusResult |
Post an image status. OPERATOR |
send_video |
send_video(session_id, body) -> StatusResult |
Post a video status. OPERATOR |
send_voice |
send_voice(session_id, body) -> StatusResult |
Post an audio status as a voice note. WhatsApp plays one only as Ogg/Opus and neither engine transcodes, so convert with media.convert_voice first. OPERATOR |
delete |
delete(session_id, status_id) -> None |
Delete a status. OPERATOR |
client.search
| Method |
Signature |
Description |
search |
search(params) -> SearchResults |
Search persisted messages across sessions via the active search provider. OPERATOR |
client.templates
| Method |
Signature |
Description |
list |
list(session_id) -> list[TemplateRecord] |
List templates. OPERATOR |
get |
get(session_id, template_id) -> TemplateRecord |
Get one template. OPERATOR |
create |
create(session_id, body) -> TemplateRecord |
Create a template. OPERATOR |
update |
update(session_id, template_id, body) -> TemplateRecord |
Update a template. OPERATOR |
delete |
delete(session_id, template_id) -> None |
Delete a template. OPERATOR |
client.profile
| Method |
Signature |
Description |
set_profile_name |
set_profile_name(session_id, body) -> SuccessResult |
Set the account display name. OPERATOR |
set_profile_status |
set_profile_status(session_id, body) -> SuccessResult |
Set the account about/status text (empty clears it). OPERATOR |
set_profile_picture |
set_profile_picture(session_id, body) -> SuccessResult |
Set the account profile picture (url or base64 + mimetype). OPERATOR |
delete_profile_picture |
delete_profile_picture(session_id) -> SuccessResult |
Remove the account profile picture. OPERATOR |
client.calls
| Method |
Signature |
Description |
reject_call |
reject_call(session_id, call_id) -> SuccessResult |
Reject a ringing incoming call. Baileys only: whatsapp-web.js answers 501. OPERATOR |
create_link |
create_link(session_id, body) -> CallLinkResponse |
Create a shareable WhatsApp call link (startTime is epoch MILLISECONDS). OPERATOR |
client.media
| Method |
Signature |
Description |
conversion_status |
conversion_status(session_id) -> MediaConversionAvailability |
Whether conversion is switched on for this deployment AND the ffmpeg binary can be run. |
convert_voice |
convert_voice(session_id, *, url=None, base64=None) -> ConvertedMedia |
Convert audio into a WhatsApp voice note (Ogg/Opus, mono, tuned for speech). OPERATOR |
convert_video |
convert_video(session_id, *, url=None, base64=None) -> ConvertedMedia |
Convert video into an MP4 every WhatsApp client accepts (baseline H.264 + AAC). OPERATOR |
client.health
| Method |
Signature |
Description |
check |
check() -> HealthResponse |
Aggregate health check. |
live |
live() -> dict[str, str] |
Liveness probe. |
ready |
ready() -> HealthReadyResponse |
Readiness probe. |
Error Handling
Every error the SDK raises itself inherits from OpenWAError. A non-2xx response raises an OpenWAApiError (or a more specific subclass picked by status); a timeout raises OpenWATimeoutError. A connection failure (refused, reset, DNS, TLS) surfaces as httpx.TransportError and an invalid argument as ValueError, so a catch-all names those as well. The API-error classes carry .status (HTTP code), .body (parsed JSON or raw text), and .error_kind (the NestJS error field), plus .code (the body's code), .retry_after_seconds (the body's retryAfterSeconds, else the Retry-After header) and .headers (the response headers).
| Exception |
Trigger |
OpenWAAuthError |
HTTP 401 — missing or invalid API key |
OpenWAForbiddenError |
HTTP 403 — the key's role or scope (session, IP or chat allow-list) refuses the call, or WhatsApp itself refused the operation (for example, missing group admin rights) |
OpenWANotFoundError |
HTTP 404 — resource not found |
OpenWAConflictError |
HTTP 409: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see code) |
OpenWARateLimitError |
HTTP 429 — too many requests. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and retry_after_seconds carries its Retry-After header. A 429 whose code is "SEND_PACING_LIMITED" is usually not transient: do not retry it before retry_after_seconds, which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (SEND_PACING_BREAKER_COOLDOWN_MS, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. |
OpenWANotImplementedError |
HTTP 501 — active engine doesn't support the operation |
OpenWAServiceUnavailableError |
HTTP 503 — the gateway could not complete the request now (transport failure, draining, or on Baileys a WhatsApp throttle (429) or timeout (408)); back off and retry later, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on |
OpenWAApiError |
any other non-2xx status (incl. unfollowed 3xx) |
OpenWATimeoutError |
request exceeded timeout (has a .timeout attribute) |
from openwa import (
OpenWAClient,
OpenWAConflictError,
OpenWANotFoundError,
OpenWARateLimitError,
OpenWATimeoutError,
OpenWAApiError,
)
client = OpenWAClient(base_url="http://localhost:2785", api_key="owa_k1_…")
try:
client.messages.send_text(session_id, {
"chatId": "[email protected]",
"text": "Hi!",
})
except OpenWAConflictError as e:
print(f"Conflict: typically the session is not ready yet (start it first); see e.code ({e.code}).")
except OpenWANotFoundError:
print("Session does not exist.")
except OpenWARateLimitError:
print("Rate limited — back off and retry.")
except OpenWATimeoutError as e:
print(f"Timed out after {e.timeout}s")
except OpenWAApiError as e:
print(f"API error {e.status} ({e.error_kind}): {e.body}")
Notable Behaviors
- Redirects are never followed.
follow_redirects is forced off so the X-API-Key header is never re-sent to a redirect target. An unfollowed 3xx therefore surfaces as an OpenWAApiError rather than a success.
- Auth/JSON headers always win.
default_headers are applied first; the SDK then sets Content-Type: application/json and X-API-Key, so caller headers can never clobber them.
- Path segments are percent-encoded. Each path value (session/chat/message id, etc.) is encoded so a
/, #, or ? can't break out of its position; already-safe id characters @, :, + are left readable. Boolean query params are serialized lowercase (true/false); None query values are dropped.
- Empty and dot segments are refused. An empty,
. or .. id raises ValueError before anything is sent, because httpx would otherwise resolve it to the parent resource. A raw request() path that does not begin with / raises ValueError too.
- Base-URL path prefix is preserved. A trailing
/ is stripped from base_url, but any path prefix (e.g. when running behind a reverse proxy) is kept on every request.
- No automatic retries. Each call issues exactly one request; retry/backoff is the caller's responsibility. Wrap or inject a custom
transport for retry or observability middleware.
- Testable transport injection. Pass
transport=httpx.MockTransport(handler) to intercept requests in tests — no global monkey-patching.
- 204 / non-JSON handling. A
204 (or empty body) returns None; a 2xx body that isn't valid JSON is returned as raw text instead of raising.
- PEP 561 typed. The package ships
py.typed, so type-checkers consume the bundled hints directly.
18.4 PHP SDK
The PHP SDK is a hand-written, synchronous client built on Guzzle 7.9+ or 8. It mirrors the full user-facing API surface: every resource method maps to one REST endpoint, request/response payloads are plain associative arrays, and non-2xx responses are translated into a typed OpenWA*Exception hierarchy.
Installation
composer require rmyndharis/openwa
Requirements:
- PHP 8.1+ (
declare(strict_types=1) throughout; typed properties, match).
- Guzzle 7.9+ or 8 (
guzzlehttp/guzzle: ^7.9 || ^8.0).
- PSR-4 autoloaded under the
OpenWA\ namespace ("OpenWA\\": "src/").
Quick Start
<?php
require 'vendor/autoload.php';
use OpenWA\Client;
$client = new Client([
'baseUrl' => 'http://localhost:2785',
'apiKey' => 'owa_k1_…',
]);
// Sessions are addressed by the UUID that create() returns, not by name. Create a session once;
// afterwards, find its id with $client->sessions->list(['name' => 'my-session']).
$session = $client->sessions->create(['name' => 'my-session']);
$client->sessions->start($session['id']);
// Link the account before sending: scan sessions->getQrCode (or use sessions->requestPairingCode for a number with no linked session),
// then wait for status 'ready'. An unlinked session answers the send with 409.
$result = $client->messages->sendText($session['id'], [
'chatId' => '[email protected]',
'text' => 'Hello from the OpenWA PHP SDK!',
]);
echo $result['messageId'];
The entry class is OpenWA\Client. It validates that baseUrl and apiKey are present (throwing OpenWAException otherwise), constructs the shared HTTP transport, and exposes each resource as a public property: $client->sessions, $client->messages, $client->search, $client->contacts, $client->groups, $client->webhooks, $client->chats, $client->status, $client->health, $client->labels, $client->channels, $client->catalog, $client->templates, $client->profile, $client->calls, $client->media.
Two escape hatches sit on the client itself:
| Method |
Signature |
Description |
auth |
auth(): array |
POST /api/auth/validate — validate the configured key and resolve its role; a key restricted to selected chats is refused with 403. |
request |
request(string $method, string $path, array $query = [], mixed $body = null): mixed |
Raw request against any path (advanced use); returns decoded JSON or null for empty/204. |
Client Configuration
The constructor takes a single associative $config array:
| Key |
Type |
Default |
Description |
baseUrl |
string |
— (required) |
API base URL, e.g. http://localhost:2785. A trailing / is stripped; any path prefix (e.g. /v1 behind a proxy) is preserved. |
apiKey |
string |
— (required) |
Sent as the X-API-Key header on every request. Surrounding whitespace is trimmed; a control or non-ASCII character is refused. |
timeout |
float |
30.0 |
Per-request timeout in seconds, applied to an injected httpClient too. On Guzzle 8 it is also sent as read_timeout (the stream handler's idle bound, 0 for none), replacing the injected client's own. The SDK has no separate idle setting. |
httpClient |
?\GuzzleHttp\ClientInterface |
null |
Inject a Guzzle client (e.g. one built on a MockHandler) for testing or middleware. When null, a default Guzzle client is created with the configured timeout. On Guzzle 8 the SDK timeout replaces this client's read_timeout (see timeout). |
defaultHeaders |
array<string,scalar|list> |
[] |
Extra headers applied on every request, under the SDK's auth/JSON headers (which always win). A name must be an HTTP token; a value is text, a scalar or null (sent as text) or a non-empty list of those, without a control or non-ASCII character. |
allowInsecureHttp |
bool |
false |
Skip the error_log() warning written for an http:// baseUrl whose host is not localhost (e.g. a private Docker network or a TLS-terminating proxy). |
Missing baseUrl or apiKey, a key or default header value with a control or non-ASCII character, or a default header name that is not an HTTP token throws OpenWA\Exceptions\OpenWAException from the constructor. So does an empty list as a header value, by header name, because Guzzle 8 cannot represent a header with zero values; use '' for an empty value.
Resources & Methods
All payloads are associative arrays; all listed methods are synchronous and return the decoded JSON (an array), except the void deletes. Methods marked OPERATOR require an operator-level API key. Some methods are supported by one engine only and answer 501 on the other (a row says so where it matters; section 29.6 of the engine capability matrix lists them all).
sessions
| Method |
Signature |
Description |
list |
list(array $query = []): array |
List all sessions. The optional query takes limit, offset and name (an exact, case-sensitive match; no match returns an empty list). |
getConfig |
getConfig(string $id): array |
Read a session's engine configuration. |
updateConfig |
updateConfig(string $id, array $body): array |
Update a session's configuration, in any state, without a restart or re-link; autoRejectCalls applies immediately, the reconnect settings on the next start. OPERATOR |
getProxy |
getProxy(string $id): array |
Read a session's masked proxy configuration (credentials never returned). |
updateProxy |
updateProxy(string $id, array $body): array |
Update per-session proxy settings; changes apply on the next start. Send proxyUrl: null to clear. ADMIN |
get |
get(string $id): array |
Get one session. |
create |
create(array $body): array |
Create a session ($body['name'] required). OPERATOR; setting proxyUrl requires ADMIN |
delete |
delete(string $id): void |
Delete a session. OPERATOR |
start |
start(string $id): array |
Start a session. OPERATOR |
stop |
stop(string $id): array |
Stop a session. OPERATOR |
logout |
logout(string $id): array |
Attempt an engine-native unlink of this device, then stop the session. A 200 means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later start needs a fresh QR. A 502 (SESSION_LOGOUT_INCOMPLETE) stops locally but leaves the operation incomplete; start and retry. Requires a running session. OPERATOR |
forceKill |
forceKill(string $id): array |
Force-kill a session. A 502 (SESSION_FORCE_KILL_INCOMPLETE) stops locally but the engine process may still be running; a retry answers 400, so restart the node to reap it. OPERATOR |
getQrCode |
getQrCode(string $id): array |
Fetch the current QR code. OPERATOR |
requestPairingCode |
requestPairingCode(string $id, array $body): array |
Request a phone-pairing code. On whatsapp-web.js, not for a number that already has a linked session (WhatsApp can revoke that device; the gateway answers 409 for the stored phone of another of its sessions but cannot see a link made elsewhere); link it by QR instead. OPERATOR |
setOnlinePresence |
setOnlinePresence(string $id, array $body): array |
Set the account's own global presence (appear online or offline). OPERATOR |
stats |
stats(): array |
GET /api/sessions/stats/overview. |
messages
| Method |
Signature |
Description |
list |
list(string $sessionId, array $query = []): array |
List stored messages; the query takes the same keys as the JavaScript client's messages.list, and the response carries unknownTimestampTotal under the same conditions. |
sendText |
sendText(string $sessionId, array $body): array |
Send a text message (send-text). OPERATOR |
sendImage |
sendImage(string $sessionId, array $body): array |
Send an image. OPERATOR |
sendVideo |
sendVideo(string $sessionId, array $body): array |
Send a video. OPERATOR |
sendAudio |
sendAudio(string $sessionId, array $body): array |
Send audio. OPERATOR |
sendDocument |
sendDocument(string $sessionId, array $body): array |
Send a document. OPERATOR |
sendSticker |
sendSticker(string $sessionId, array $body): array |
Send a sticker. OPERATOR |
sendLocation |
sendLocation(string $sessionId, array $body): array |
Send a location. OPERATOR |
sendContact |
sendContact(string $sessionId, array $body): array |
Send a contact card. OPERATOR |
sendTemplate |
sendTemplate(string $sessionId, array $body): array |
Send a stored template. OPERATOR |
sendPoll |
sendPoll(string $sessionId, array $body): array |
Send a native poll (2–12 options). OPERATOR |
reply |
reply(string $sessionId, array $body): array |
Reply to a message. OPERATOR |
forward |
forward(string $sessionId, array $body): array |
Forward a message. OPERATOR |
clickButton |
clickButton(string $sessionId, array $body): array |
Tap a button or list row on a stored WhatsApp Business prompt (Baileys only). OPERATOR |
react |
react(string $sessionId, array $body): array |
React to a message. OPERATOR |
delete |
delete(string $sessionId, array $body): array |
Delete a message. OPERATOR |
editMessage |
editMessage(string $sessionId, array $body): array |
Edit the text of a message already sent ($body needs chatId, messageId, body). OPERATOR |
history |
history(string $sessionId, string $chatId, array $query = []): array |
Fetch chat history. |
reactions |
reactions(string $sessionId, string $chatId, string $messageId): array |
List reactions on a message. |
pin |
pin(string $sessionId, array $body): array |
Pin a message in its chat. durationSeconds must be 86400, 604800 or 2592000; in a group only admins may pin. OPERATOR |
votePoll |
votePoll(string $sessionId, array $body): array |
Cast a vote on a poll; options are the option texts, not ids. Not supported on Baileys (501). OPERATOR |
star |
star(string $sessionId, array $body): array |
Star or unstar a message. Best-effort on whatsapp-web.js, which silently ignores a message it will not star. OPERATOR |
unpin |
unpin(string $sessionId, array $body): array |
Unpin a pinned message. OPERATOR |
media |
media(string $sessionId, string $chatId, string $messageId): array |
Fetch a message's stored media bytes: the archived file when one exists, else the inline copy on the message row. 404 when neither holds bytes. |
sendBulk |
sendBulk(string $sessionId, array $body): array |
Enqueue a bulk send batch. OPERATOR |
batchStatus |
batchStatus(string $sessionId, string $batchId): array |
Get bulk batch status. |
cancelBatch |
cancelBatch(string $sessionId, string $batchId): array |
Cancel a bulk batch. OPERATOR |
contacts
| Method |
Signature |
Description |
list |
list(string $sessionId, array $query = []): array |
List contacts. |
get |
get(string $sessionId, string $contactId): array |
Get one contact. |
check |
check(string $sessionId, string $number): array |
Check whether a number is on WhatsApp. OPERATOR |
profilePicture |
profilePicture(string $sessionId, string $contactId): array |
Get a contact's profile picture. |
profilePictures |
profilePictures(string $sessionId, array $ids): array |
Profile picture URLs for up to 50 contacts; ids skipped after a timeout are absent. |
phone |
phone(string $sessionId, string $contactId): array |
Resolve a contact's phone number. |
block |
block(string $sessionId, string $contactId): array |
Block a contact. OPERATOR |
upsert |
upsert(string $sessionId, string $contactId, array $body): array |
Save a contact to the account's addressbook, or edit an existing entry. OPERATOR |
delete |
delete(string $sessionId, string $contactId): array |
Remove a contact from the account's addressbook. OPERATOR |
unblock |
unblock(string $sessionId, string $contactId): array |
Unblock a contact. OPERATOR |
listBlocked |
listBlocked(string $sessionId): array |
List the ids this account has blocked. Session-wide, so it takes no contact id. |
groups
| Method |
Signature |
Description |
list |
list(string $sessionId, array $query = []): array |
List groups. |
get |
get(string $sessionId, string $groupId): array |
Get one group. |
create |
create(string $sessionId, array $body): array |
Create a group. OPERATOR |
joinInfo |
joinInfo(string $sessionId, string $code): array |
Preview a group from its invite code WITHOUT joining. Read-only, so it is safe to call on a code from an untrusted source. |
joinGroup |
joinGroup(string $sessionId, string $inviteCode): array |
Join a group via its invite code. OPERATOR |
addParticipants |
addParticipants(string $sessionId, string $groupId, array $participants): array |
Add participants. OPERATOR |
removeParticipants |
removeParticipants(string $sessionId, string $groupId, array $participants): array |
Remove participants. OPERATOR |
promoteParticipants |
promoteParticipants(string $sessionId, string $groupId, array $participants): array |
Promote to admin. OPERATOR |
demoteParticipants |
demoteParticipants(string $sessionId, string $groupId, array $participants): array |
Demote admins. OPERATOR |
setSubject |
setSubject(string $sessionId, string $groupId, string $subject): array |
Update the group subject. OPERATOR |
setDescription |
setDescription(string $sessionId, string $groupId, string $description): array |
Update the group description. OPERATOR |
setMemberLabel |
setMemberLabel(string $sessionId, string $groupId, string $label): array |
Set this account's member label in the group (empty clears it; Baileys only). OPERATOR |
getGroupSettings |
getGroupSettings(string $sessionId, string $groupId): array |
Get the group settings (only the ones the active engine supports are present). |
updateGroupSettings |
updateGroupSettings(string $sessionId, string $groupId, array $settings): array |
Update the group settings (at least one of announce, locked, ephemeralSeconds, memberAddMode). OPERATOR |
leave |
leave(string $sessionId, string $groupId): array |
Leave the group. OPERATOR |
getPicture |
getPicture(string $sessionId, string $groupId): array |
The group's picture URL, or null when it has none. |
setPicture |
setPicture(string $sessionId, string $groupId, array $body): array |
Set the group's picture. OPERATOR |
deletePicture |
deletePicture(string $sessionId, string $groupId): array |
Remove the group's picture. OPERATOR |
inviteCode |
inviteCode(string $sessionId, string $groupId): array |
Get the invite code. OPERATOR |
revokeInviteCode |
revokeInviteCode(string $sessionId, string $groupId): array |
Revoke and regenerate the invite code. OPERATOR |
getMembershipRequests |
getMembershipRequests(string $sessionId, string $groupId): array |
List a group's pending join requests. Requires group admin. |
approveMembershipRequests |
approveMembershipRequests(string $sessionId, string $groupId, ?array $participants = null): array |
Approve pending join requests; omit the list to approve all. OPERATOR |
rejectMembershipRequests |
rejectMembershipRequests(string $sessionId, string $groupId, ?array $participants = null): array |
Reject pending join requests; omit the list to reject all. OPERATOR |
chats
| Method |
Signature |
Description |
list |
list(string $sessionId, array $query = []): array |
List chats. |
subscribePresence |
subscribePresence(string $sessionId, array $body): array |
Subscribe to a chat's presence; updates then arrive as presence.update events. The subscription belongs to the connection and does not survive a reconnect. OPERATOR |
getPresence |
getPresence(string $sessionId, string $chatId): ?array |
The last presence reported for a chat, or null when none has been. Held in memory, so a restart clears it. |
markRead |
markRead(string $sessionId, array $body): array |
Mark chat(s) read. OPERATOR |
markUnread |
markUnread(string $sessionId, array $body): array |
Mark chat(s) unread. OPERATOR |
archive |
archive(string $sessionId, array $body): array |
Archive or unarchive a chat. success: false means the engine declined. OPERATOR |
pin |
pin(string $sessionId, array $body): array |
Pin a chat to the top of the list, or unpin it. success: false means WhatsApp declined — three pins maximum. OPERATOR |
mute |
mute(string $sessionId, array $body): array |
Mute a chat until an absolute epoch-MILLISECONDS timestamp, or unmute with null. OPERATOR |
clearMessages |
clearMessages(string $sessionId, string $chatId): array |
Delete every message in a chat, keeping the chat itself. On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. OPERATOR |
delete |
delete(string $sessionId, array $body): array |
Delete chat(s). On success the gateway also deletes its stored copy of the chat's messages (rows, inline and archived media, search entries); export the history first if you need it. OPERATOR |
sendState |
sendState(string $sessionId, array $body): array |
Send a typing/recording state. OPERATOR |
webhooks
| Method |
Signature |
Description |
listAll |
listAll(array $query = []): array |
List webhooks across EVERY session the key can see, not one session's. OPERATOR |
deliveryFailures |
deliveryFailures(array $query = []) |
Deliveries that exhausted their retries (attempts > 0), or were shed, oversize, failed preflight or refused at shutdown, possibly between retries (attempts: 0); a later successful delivery removes the row; the diagnostic for a webhook that stopped arriving. A delivery a smart filter suppressed never reaches this log. ADMIN |
redriveDeliveryFailures |
redriveDeliveryFailures(array $body = []): array |
Replay the rows deliveryFailures marks replayable (kept while WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS > 0), fewest attempts first, then oldest, one bounded batch per call, reusing each stored idempotency key; returns delivered/failed/skipped/remaining counts; enqueued is always 0. ADMIN |
list |
list(string $sessionId): array |
List webhooks. OPERATOR |
get |
get(string $sessionId, string $id): array |
Get one webhook. OPERATOR |
create |
create(string $sessionId, array $body): array |
Create a webhook. OPERATOR |
update |
update(string $sessionId, string $id, array $body): array |
Update a webhook. OPERATOR |
delete |
delete(string $sessionId, string $id): void |
Delete a webhook. OPERATOR |
test |
test(string $sessionId, string $id): array |
Send a test event. OPERATOR |
labels (WhatsApp Business)
| Method |
Signature |
Description |
list |
list(string $sessionId): array |
List labels. |
get |
get(string $sessionId, string $labelId): array |
Get one label. |
chats |
chats(string $sessionId, string $labelId): array |
Every chat carrying a label. whatsapp-web.js only — Baileys answers 501. |
upsert |
upsert(string $sessionId, string $labelId, array $body): array |
Create or update a label. Baileys only — whatsapp-web.js answers 501. OPERATOR |
delete |
delete(string $sessionId, string $labelId): array |
Delete a label. OPERATOR |
forChat |
forChat(string $sessionId, string $chatId): array |
List labels applied to a chat. |
addToChat |
addToChat(string $sessionId, string $chatId, array $body): array |
Add a label to a chat ($body needs labelId). OPERATOR |
removeFromChat |
removeFromChat(string $sessionId, string $chatId, string $labelId): array |
Remove a label from a chat. OPERATOR |
channels (Newsletters)
| Method |
Signature |
Description |
list |
list(string $sessionId): array |
List channels. |
get |
get(string $sessionId, string $channelId): array |
Get one channel. |
messages |
messages(string $sessionId, string $channelId, array $query = []): array |
Recent channel messages. |
create |
create(string $sessionId, array $body): array |
Create a channel this account owns. OPERATOR |
delete |
delete(string $sessionId, string $channelId): array |
Delete a channel this account owns. Irreversible, and every subscriber loses it — distinct from unsubscribe. OPERATOR |
mute |
mute(string $sessionId, string $channelId, array $body): array |
Mute or unmute a channel's notifications. OPERATOR |
subscribe |
subscribe(string $sessionId, array $body): array |
Subscribe via invite code ($body needs inviteCode). OPERATOR |
unsubscribe |
unsubscribe(string $sessionId, string $channelId): array |
Unsubscribe from a channel. OPERATOR |
demoteAdmin |
demoteAdmin(string $sessionId, string $channelId, array $body): array |
Demote a channel admin back to a subscriber; no promote counterpart exists. OPERATOR |
transferOwnership |
transferOwnership(string $sessionId, string $channelId, array $body): array |
Hand a channel to a new owner. Irreversible. OPERATOR |
catalog (WhatsApp Business)
| Method |
Signature |
Description |
info |
info(string $sessionId): ?array |
Get catalog info, or null when the account has no catalog. |
products |
products(string $sessionId, array $query = []): array |
List products (e.g. ['page' => 1, 'limit' => 20]). |
product |
product(string $sessionId, string $productId): ?array |
Get one product, or null when no product has that id. |
sendProduct |
sendProduct(string $sessionId, array $body): array |
Send a product message (chatId + productId). OPERATOR |
status (Stories)
| Method |
Signature |
Description |
list |
list(string $sessionId): array |
List status updates. |
fromContact |
fromContact(string $sessionId, string $contactId): array |
Status updates from one contact. |
media |
media(string $sessionId, string $statusId): array |
Fetch the stored media bytes for a status update ({data, contentType}; 404 when there is none). |
sendText |
sendText(string $sessionId, array $body): array |
Post a text status. OPERATOR |
sendImage |
sendImage(string $sessionId, array $body): array |
Post an image status. OPERATOR |
sendVideo |
sendVideo(string $sessionId, array $body): array |
Post a video status. OPERATOR |
sendVoice |
sendVoice(string $sessionId, array $body): array |
Post an audio status as a voice note. WhatsApp plays one only as Ogg/Opus and neither engine transcodes, so convert with media.convertVoice first. OPERATOR |
delete |
delete(string $sessionId, string $statusId): void |
Delete a status. OPERATOR |
search
| Method |
Signature |
Description |
search |
search(array $params): array |
Search persisted messages across sessions via the active search provider ($params['q'] required). OPERATOR |
templates
| Method |
Signature |
Description |
list |
list(string $sessionId): array |
List templates. OPERATOR |
get |
get(string $sessionId, string $templateId): array |
Get one template. OPERATOR |
create |
create(string $sessionId, array $body): array |
Create a template ($body needs name and body; header/footer optional). OPERATOR |
update |
update(string $sessionId, string $templateId, array $body): array |
Update a template. OPERATOR |
delete |
delete(string $sessionId, string $templateId): void |
Delete a template. OPERATOR |
profile
| Method |
Signature |
Description |
setProfileName |
setProfileName(string $sessionId, string $name): array |
Set the account display name. OPERATOR |
setProfileStatus |
setProfileStatus(string $sessionId, string $status): array |
Set the account about/status text (empty clears it). OPERATOR |
setProfilePicture |
setProfilePicture(string $sessionId, array $body): array |
Set the account profile picture (url or base64 + mimetype). OPERATOR |
deleteProfilePicture |
deleteProfilePicture(string $sessionId): array |
Remove the account profile picture. OPERATOR |
calls
| Method |
Signature |
Description |
rejectCall |
rejectCall(string $sessionId, string $callId): array |
Reject a ringing incoming call (404 when it is not found or no longer ringing). Baileys only: whatsapp-web.js answers 501. OPERATOR |
createLink |
createLink(string $sessionId, array $body): array |
Create a shareable WhatsApp call link (startTime is epoch MILLISECONDS). OPERATOR |
media
| Method |
Signature |
Description |
conversionStatus |
conversionStatus(string $sessionId): array |
Whether conversion is switched on for this deployment AND the ffmpeg binary can be run. |
convertVoice |
convertVoice(string $sessionId, array $media): array |
Convert audio into a WhatsApp voice note (Ogg/Opus, mono, tuned for speech). OPERATOR |
convertVideo |
convertVideo(string $sessionId, array $media): array |
Convert video into an MP4 every WhatsApp client accepts (baseline H.264 + AAC). OPERATOR |
health
| Method |
Signature |
Description |
check |
check(): array |
GET /api/health. |
live |
live(): array |
Liveness probe. |
ready |
ready(): array |
Readiness probe. |
Error Handling
All exceptions the SDK raises itself live in OpenWA\Exceptions and descend from OpenWAException (which extends PHP's \Exception). A transport failure that is not a timeout (a refused connection, a reset, a TLS verification failure) surfaces as one of Guzzle's own GuzzleHttp\Exception\TransferException subclasses and an invalid argument as InvalidArgumentException, so a catch-all names those as well. The subclass depends on the Guzzle major (a reset is a RequestException on Guzzle 7 and a NetworkException, which is not a RequestException, on Guzzle 8), so catch TransferException rather than a subclass. On Guzzle 7's stream handler (a host without ext-curl) a timeout of 0 still leaves PHP's default_socket_timeout before the response headers, and that wait ends with such a failure too, not an OpenWATimeoutException (see the PHP README). That handler also bounds each wait rather than the whole call: a silence in the body can last up to about twice the timeout before it is cut off, and a body that keeps trickling bytes is not cut off at all, while cURL and Guzzle 8's stream handler bound the whole call. Any non-2xx response is raised as an OpenWAApiException; the static classify() factory picks the most specific subclass by status code. An OpenWAApiException carries the HTTP status (getStatus(): int), the parsed error body (getBody(): mixed), and the NestJS error kind when present (getErrorKind(): ?string), plus the body's code (getErrorCode(): ?string), the retry delay in seconds from the body's retryAfterSeconds or the Retry-After header (getRetryAfterSeconds(): ?int) and the response headers (getHeaders(): array).
| Exception |
Extends |
Trigger |
OpenWAException |
\Exception |
Base for the SDK's own errors (also thrown for missing baseUrl/apiKey and for a key or default header the HTTP layer would refuse); a transport failure other than a timeout is Guzzle's own (TransferException). |
OpenWAApiException |
OpenWAException |
Any non-2xx (including unfollowed 3xx and other 4xx/5xx). |
OpenWAAuthException |
OpenWAApiException |
401 — missing/invalid API key. |
OpenWAForbiddenException |
OpenWAApiException |
403 — the key's role or scope refuses the call (e.g. operator-only endpoint, or a session, IP or chat outside its allow-lists), or WhatsApp itself refused the operation (for example, missing group admin rights). |
OpenWANotFoundException |
OpenWAApiException |
404 — resource not found. |
OpenWAConflictException |
OpenWAApiException |
409: a conflicting state, typically a session that is not ready, or a keyed send pending or unconfirmed (see code). |
OpenWARateLimitException |
OpenWAApiException |
429 — rate limited. The global rate limiter's 429 lifts when its window expires (seconds for the per-second tier, up to an hour for the hourly tier by default), and getRetryAfterSeconds() carries its Retry-After header. A 429 whose getErrorCode() is "SEND_PACING_LIMITED" is usually not transient: do not retry it before getRetryAfterSeconds(), which then comes from the body: a few seconds when only sends still in flight caused it, the rest of the failure breaker's cooldown (SEND_PACING_BREAKER_COOLDOWN_MS, 15 minutes by default) after a run of send failures, otherwise up to the next UTC day. |
OpenWANotImplementedException |
OpenWAApiException |
501 — active engine does not support the operation. |
OpenWAServiceUnavailableException |
OpenWAApiException |
503 — the gateway could not complete the request now (transport failure, draining, or on Baileys a WhatsApp throttle (429) or timeout (408)); back off and retry later, though a catalog 503 can persist because WhatsApp may never answer that query. In a routed deployment a forward that fails before reaching the owner node answers 503, and a 503 from the owner itself is relayed unchanged (a bounded write it covers may still have been applied); a forward that fails after the request was sent answers 502 or 504, which the owner may already have acted on. |
OpenWATimeoutException |
OpenWAException |
Request exceeded the timeout (getTimeout(): float). Not an API error — has no status/body. |
<?php
use OpenWA\Client;
use OpenWA\Exceptions\OpenWAConflictException;
use OpenWA\Exceptions\OpenWARateLimitException;
use OpenWA\Exceptions\OpenWATimeoutException;
use OpenWA\Exceptions\OpenWAApiException;
try {
$result = $client->messages->sendText($sessionId, [
'chatId' => '[email protected]',
'text' => 'Hello!',
]);
} catch (OpenWAConflictException $e) {
// 409: a conflicting state, typically a session that is not ready yet, or a keyed send pending or unconfirmed (see getErrorCode())
} catch (OpenWARateLimitException $e) {
// 429 — back off and retry yourself (no auto-retry)
} catch (OpenWATimeoutException $e) {
fwrite(STDERR, "timed out after {$e->getTimeout()}s\n");
} catch (OpenWAApiException $e) {
// any other non-2xx
fwrite(STDERR, "API {$e->getStatus()}: {$e->getMessage()}\n");
var_dump($e->getBody());
}
Notable Behaviors
- Redirects are never followed. Guzzle is configured with
allow_redirects => false, so a 3xx surfaces as an OpenWAApiException rather than being followed — the X-API-Key header is never re-sent to a redirect target.
- Auth/JSON headers take precedence.
defaultHeaders are merged in first, then X-API-Key, Content-Type: application/json, and Accept: application/json are applied on top, so they can't be clobbered.
- Path segments are percent-encoded. Ids (session/chat/message/group ids) pass through
encodeSegment(), which rawurlencodes the value but keeps the WhatsApp-id-safe characters @, :, and + readable — so a value containing /, #, or ? cannot break out of its path position.
- Empty and dot segments are refused. An empty,
. or .. id throws InvalidArgumentException before anything is sent, because the HTTP stack would otherwise resolve it to the parent resource. A raw request() path that does not begin with / throws InvalidArgumentException too.
- Base-URL path prefix is preserved. The base URL has its trailing
/ trimmed and requests are issued against an absolute baseUrl . $path; Guzzle's base_uri is intentionally unset, so a prefix like /v1 behind a reverse proxy is retained.
- Null query values are dropped. Absent optional query parameters (
null) are filtered out before the request, so they are never sent.
- No automatic retries. A failed request throws immediately; wrap calls in your own backoff if you need retries (notably for
429). The injectable httpClient is the extension point for retry/observability middleware.
- Empty/204 responses return
null. A 204 or empty body decodes to null; resource methods that promise an array coalesce this to [] (or to the resource object for single-item gets).
- Testing without the network. Inject a Guzzle client built on a
GuzzleHttp\Handler\MockHandler via the httpClient config key — no global state, no live calls. The shipped test suite asserts on the exact path, method, and body.
- PSR-4 autoloading. Everything lives under the
OpenWA\ namespace mapped to src/; composer require rmyndharis/openwa wires up the autoloader.
18.5 n8n Community Node
OpenWA's n8n integration is not part of these SDK packages. It is a separate community node maintained in its own repository, which speaks the same REST + webhook contract documented in API Specification:
- An action/HTTP path that calls the REST endpoints (e.g.
POST /api/sessions/:id/messages/send-text) with the X-API-Key header.
- A trigger path that registers a webhook (the
webhooks resource) and receives inbound events, verifying the X-OpenWA-Signature HMAC.
For installation and node-by-node configuration, see the dedicated n8n Integration guide. Because the node consumes the public API contract, the verified route/event reference in docs 06 and §6.6 (Webhook Events) is the authority for what it can call and receive.
18.6 SDK Versioning & Releases
Versioning
The five SDKs are versioned independently of the gateway and of each other, each following SemVer. An SDK version does not track the gateway version — check the registry for the current one rather than inferring it from the gateway's. Pin the SDK version your code is tested against and treat a major SDK bump as potentially breaking.
| SDK |
Registry |
Package |
| JavaScript/TypeScript |
npm |
@rmyndharis/openwa |
| Python |
PyPI |
rmyndharis-openwa |
| PHP |
Packagist |
rmyndharis/openwa |
| Java |
Maven Central |
com.rmyndharis:openwa |
| Go |
(none — module path) |
github.com/rmyndharis/OpenWA/sdk/go |
Contract-drift protection
The wire types live in a dedicated module (types.ts / types.py) so they can later be regenerated by an OpenAPI codegen pass without touching the hand-written resource methods.
Requests. Each SDK's test suite mocks the HTTP transport and asserts on the exact request path, method, and body — so a drift between an SDK method and the real API (the class of bug that once shipped messages/text instead of the real messages/send-text) breaks a test rather than reaching users.
Responses. That is a different problem, and for a long time nothing covered it — #754 is the proof: the status, label, and channel record types drifted from the engine interface for releases without a single test noticing, because asserting the request says nothing about the reply. openapi:check does not cover it either, because it only keeps the snapshot in step with the code. The schemas of those records (LabelDto, ChannelDto, ChannelMessageDto, StatusDto and StatusListResponseDto) are in openapi.json, and check:contract-shapes compares the SDKs' label, channel and status records with them field by field. A second check is sdk/javascript/test/wire-contract.test-d.ts — a type-level test where tsc --noEmit (run by npm test ahead of vitest) fails if a record type stops matching the engine-neutral shape as it arrives over JSON. Its Wire* types are maintained by hand: sdk-ci.yml re-runs the job when whatsapp-engine.interface.ts changes, but keeping the two in step is a human step, not a generated one.
Release process
# JavaScript (the tests need Node 22.12+; the published package runs on Node 18+)
cd sdk/javascript && npm test && npm run build && npm run smoke # smoke = require()+import() packaging plus request check
# Python
cd sdk/python && python -m pytest -q
# PHP
cd sdk/php && composer install && ./vendor/bin/phpunit
CI runs all five suites (sdk-ci.yml), path-filtered to sdk/** plus the server-side contract surfaces the SDKs are written against — src/**/dto/**, src/**/*.controller.ts, src/**/*.service.ts and whatsapp-engine.interface.ts — so a change to the wire contract re-runs them. The PHP package is mirrored to its own Packagist repository via a git subtree split, and that mirror publish is gated on the PHP tests passing, so a broken SDK cannot auto-publish. Bump the version, record the change in the root CHANGELOG.md [Unreleased] section prefixed with the SDK's name (for example Java SDK:), drop the methods it ships from the note at the top of this document, sdk/README.md and the "This document describes main" note near the top of that SDK's own README, run the suite above, then tag/publish to the relevant registry.