18 - SDK Design

18.1 Overview

OpenWA ships three 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 contract drift is caught at test time rather than in production.

Language	Package	Install	Notes
JavaScript / TypeScript	`@rmyndharis/openwa`	`npm install @rmyndharis/openwa`	Dual ESM + CJS, bundled `.d.ts` types, Node 18+
Python	`rmyndharis-openwa`	`pip install rmyndharis-openwa`	Synchronous (httpx), PEP 561 typed, Python 3.9+
PHP	`rmyndharis/openwa`	`composer require rmyndharis/openwa`	Synchronous (Guzzle 7), PSR-4, PHP 8.1+

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 three SDKs expose the same resource surface; only the language idioms differ (camelCase methods + objects in JS/PHP, snake_case methods + dicts in Python).
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, 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), plus a timeout error — all instanceof/catch-checkable. See each language's Error Handling subsection.
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 — wrap calls in your own backoff if you need them (especially for 429).

Resource Coverage

All three SDKs expose the same fluent surface:

Resource	Methods
`sessions`	list, get, create, delete, start, stop, forceKill, getQrCode, requestPairingCode, stats
`messages`	list, sendText, sendImage/Video/Audio/Document/Sticker, sendLocation, sendContact, sendTemplate, reply, forward, react, delete, history, reactions, sendBulk, batchStatus, cancelBatch
`contacts`	list, get, check, profilePicture, phone, block, unblock
`groups`	list, get, create, add/remove/promote/demoteParticipants, setSubject, setDescription, leave, inviteCode, revokeInviteCode
`webhooks`	list, get, create, update, delete, test
`chats`	list, markRead, markUnread, delete, sendState
`labels`	list, get, forChat, addToChat, removeFromChat (WhatsApp Business)
`channels`	list, get, messages, subscribe, unsubscribe (Newsletters)
`catalog`	info, products, product, sendProduct, sendCatalog (WhatsApp Business)
`status`	list, fromContact, sendText, sendImage, sendVideo, delete (Stories)
`templates`	list, get, create, update, delete
`health`	check, live, ready

The operator/admin-only server modules — docker, metrics, infra, plugins, mcp — are intentionally not exposed in the SDKs; all user-facing resources above are. 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.

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() {
  // Start a session and bring the WhatsApp connection up.
  await client.sessions.start('my-session');

  // Send a text message.
  const result = await client.messages.sendText('my-session', {
    chatId: '628123456789@c.us',
    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.
`timeoutMs`	`number`	no	`30000`	Per-request timeout in milliseconds. 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.
`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 API key with the OPERATOR role; a non-operator key receives a 403 (OpenWAForbiddenError).

The top-level client also exposes:

Method	Signature	Description
`auth`	`client.auth()`	Validate the configured API key and resolve its role (`{ valid, role? }`).
`request`	`client.request<T>(options)`	Raw escape hatch — issue an arbitrary request against the API.

`sessions`

Method	Signature	Description
`list`	`list()`	List all sessions (scoped to the key's `allowedSessions`).
`get`	`get(id)`	Get a single session by id.
`create`	`create(body)`	Create a new session (`body.name` required). OPERATOR
`delete`	`delete(id)`	Delete a session. OPERATOR
`start`	`start(id)`	Start a session and initialize the WhatsApp connection.
`stop`	`stop(id)`	Stop a session and disconnect gracefully.
`forceKill`	`forceKill(id)`	Force-kill a stuck session (SIGKILL + teardown).
`getQrCode`	`getQrCode(id)`	Get the current QR code for authentication (live from the engine).
`requestPairingCode`	`requestPairingCode(id, body)`	Request an 8-character pairing code for phone-based login.
`stats`	`stats()`	Aggregate statistics across the key's sessions.

`messages`

Method	Signature	Description
`list`	`list(sessionId, query?)`	List messages (filter by chat/sender); returns `{ messages, total }`.
`sendText`	`sendText(sessionId, { chatId, text })`	Send a text message (`text` max 4096 chars).
`sendImage`	`sendImage(sessionId, body)`	Send an image (`url` or `base64`).
`sendVideo`	`sendVideo(sessionId, body)`	Send a video (`url` or `base64`).
`sendAudio`	`sendAudio(sessionId, body)`	Send an audio file (`url` or `base64`).
`sendDocument`	`sendDocument(sessionId, body)`	Send a document (`url` or `base64`; `filename` recommended).
`sendSticker`	`sendSticker(sessionId, body)`	Send a sticker (`url` or `base64`).
`sendLocation`	`sendLocation(sessionId, body)`	Send a location (`{ chatId, latitude, longitude, description? }`).
`sendContact`	`sendContact(sessionId, body)`	Send a contact card.
`sendTemplate`	`sendTemplate(sessionId, body)`	Render and send a stored message template.
`reply`	`reply(sessionId, body)`	Reply to a specific message.
`forward`	`forward(sessionId, body)`	Forward a message to another chat.
`react`	`react(sessionId, body)`	React to a message (empty `reaction` removes it).
`delete`	`delete(sessionId, body)`	Delete a message.
`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.
`sendBulk`	`sendBulk(sessionId, body)`	Send a batch asynchronously (202 + batch id); poll via `batchStatus`.
`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.
`profilePicture`	`profilePicture(sessionId, contactId)`	Get the contact's profile picture URL (or null).
`phone`	`phone(sessionId, contactId)`	Resolve a contact id (e.g. a `@lid`) to a phone number.
`block`	`block(sessionId, contactId)`	Block a contact. OPERATOR
`unblock`	`unblock(sessionId, contactId)`	Unblock a contact. OPERATOR

`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
`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
`leave`	`leave(sessionId, groupId)`	Leave a group. OPERATOR
`inviteCode`	`inviteCode(sessionId, groupId)`	Get the group invite code and link.
`revokeInviteCode`	`revokeInviteCode(sessionId, groupId)`	Revoke the current invite code and generate a new one. OPERATOR

`chats`

Method	Signature	Description
`list`	`list(sessionId, query?)`	List active chats, most recent first.
`markRead`	`markRead(sessionId, body)`	Mark a chat as read/seen. OPERATOR
`markUnread`	`markUnread(sessionId, body)`	Mark a chat as unread. OPERATOR
`delete`	`delete(sessionId, body)`	Delete a chat from the chat list. OPERATOR
`sendState`	`sendState(sessionId, body)`	Send a chat presence state (typing/recording/paused). OPERATOR

`webhooks`

Method	Signature	Description
`list`	`list(sessionId)`	List all webhooks for a session.
`get`	`get(sessionId, id)`	Get a single webhook by id.
`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.
`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.
`subscribe`	`subscribe(sessionId, body)`	Subscribe to a channel using its invite code. OPERATOR
`unsubscribe`	`unsubscribe(sessionId, channelId)`	Unsubscribe from a channel. OPERATOR

`catalog` (WhatsApp Business)

Method	Signature	Description
`info`	`info(sessionId)`	Get the business catalog info.
`products`	`products(sessionId, query?)`	List catalog products; returns `{ products, pagination }`.
`product`	`product(sessionId, productId)`	Get a single product by id.
`sendProduct`	`sendProduct(sessionId, body)`	Send a product message. OPERATOR
`sendCatalog`	`sendCatalog(sessionId, body)`	Send a catalog link 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.
`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
`delete`	`delete(sessionId, statusId)`	Delete a status update by id. OPERATOR

This is WhatsApp "Status/Stories", distinct from session lifecycle status.

`templates`

Method	Signature	Description
`list`	`list(sessionId)`	List all templates for a session.
`get`	`get(sessionId, id)`	Get a single template by id.
`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

`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). All error classes extend OpenWAError and are exported, so they are instanceof-checkable. A timeout throws OpenWATimeoutError, which extends OpenWAError directly (not OpenWAApiError).

Error class	HTTP status	Meaning
`OpenWAAuthError`	401	Missing or invalid API key.
`OpenWAForbiddenError`	403	The key's role is insufficient (e.g. an OPERATOR-only route).
`OpenWANotFoundError`	404	Resource not found.
`OpenWAConflictError`	409	Conflict — typically the engine is not ready.
`OpenWARateLimitError`	429	Rate limited.
`OpenWANotImplementedError`	501	The active engine does not support this operation.
`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('my-session', {
    chatId: '628123456789@c.us',
    text: 'Hi!',
  });
} catch (err) {
  if (err instanceof OpenWAConflictError) {
    // 409 — engine not ready; start the session first.
  } 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 Content-Type: application/json → defaultHeaders → per-call headers → X-API-Key. The X-API-Key is applied last and cannot be overridden; Content-Type defaults to JSON.
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. 628123456789@c.us).
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 dependency: httpx>=0.25.0,<1.0
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_…",
)

# Create then start a session
client.sessions.create({"name": "my-session"})
client.sessions.start("my-session")

# Send a text message
result = client.messages.send_text("my-session", {
    "chatId": "628123456789@c.us",
    "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 = 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. Raises `ValueError` if empty.
`timeout`	`float`	`30.0`	Per-request timeout in seconds. 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.
`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.
`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.

`client.sessions`

Method	Signature	Description
`list`	`list() -> list[SessionResponse]`	List all sessions.
`get`	`get(session_id) -> SessionResponse`	Get one session.
`create`	`create(body) -> SessionResponse`	Create a session (`body["name"]` required).
`delete`	`delete(session_id) -> None`	Delete a session.
`start`	`start(session_id) -> SessionResponse`	Start (connect) a session.
`stop`	`stop(session_id) -> SessionResponse`	Stop a session.
`force_kill`	`force_kill(session_id) -> SessionResponse`	Force-terminate a session.
`get_qr_code`	`get_qr_code(session_id) -> QrCodeResponse`	Fetch the login QR code.
`request_pairing_code`	`request_pairing_code(session_id, body) -> PairingCodeResponse`	Request a phone-number pairing code.
`stats`	`stats() -> SessionStatsOverview`	Session statistics overview.

`client.messages`

Method	Signature	Description
`list`	`list(session_id, query=None) -> MessageListResponse`	List stored messages.
`send_text`	`send_text(session_id, body) -> MessageResponse`	Send a text message.
`send_image`	`send_image(session_id, body) -> MessageResponse`	Send an image.
`send_video`	`send_video(session_id, body) -> MessageResponse`	Send a video.
`send_audio`	`send_audio(session_id, body) -> MessageResponse`	Send audio.
`send_document`	`send_document(session_id, body) -> MessageResponse`	Send a document.
`send_sticker`	`send_sticker(session_id, body) -> MessageResponse`	Send a sticker.
`send_location`	`send_location(session_id, body) -> MessageResponse`	Send a location.
`send_contact`	`send_contact(session_id, body) -> MessageResponse`	Send a contact card.
`send_template`	`send_template(session_id, body) -> MessageResponse`	Send a stored template.
`reply`	`reply(session_id, body) -> MessageResponse`	Reply to a message.
`forward`	`forward(session_id, body) -> MessageResponse`	Forward a message.
`react`	`react(session_id, body) -> SuccessResult`	React to a message.
`delete`	`delete(session_id, body) -> SuccessResult`	Delete a message.
`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.
`send_bulk`	`send_bulk(session_id, body) -> BulkMessageResponse`	Enqueue a bulk send batch.
`batch_status`	`batch_status(session_id, batch_id) -> BatchStatusResponse`	Get bulk batch status.
`cancel_batch`	`cancel_batch(session_id, batch_id) -> BatchStatusResponse`	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.
`profile_picture`	`profile_picture(session_id, contact_id) -> ProfilePictureResponse`	Get a contact's profile picture.
`phone`	`phone(session_id, contact_id) -> ContactPhoneResponse`	Resolve a contact's phone number.
`block`	`block(session_id, contact_id) -> SuccessResult`	Block a contact. OPERATOR
`unblock`	`unblock(session_id, contact_id) -> SuccessResult`	Unblock a contact. OPERATOR

`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) -> GroupInfo`	Create a group. OPERATOR
`add_participants`	`add_participants(session_id, group_id, participants) -> SuccessResult`	Add participants (`list[str]`). OPERATOR
`remove_participants`	`remove_participants(session_id, group_id, participants) -> SuccessResult`	Remove participants. OPERATOR
`promote_participants`	`promote_participants(session_id, group_id, participants) -> SuccessResult`	Promote to admin. OPERATOR
`demote_participants`	`demote_participants(session_id, group_id, participants) -> SuccessResult`	Demote from admin. 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
`leave`	`leave(session_id, group_id) -> SuccessResult`	Leave the group. OPERATOR
`invite_code`	`invite_code(session_id, group_id) -> InviteCodeResponse`	Get the invite code.
`revoke_invite_code`	`revoke_invite_code(session_id, group_id) -> InviteCodeResponse`	Revoke and regenerate the invite code. OPERATOR

`client.chats`

Method	Signature	Description
`list`	`list(session_id, query=None) -> list[ChatSummary]`	List chats (`query`: `limit`, `offset`).
`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
`delete`	`delete(session_id, body) -> SuccessResult`	Delete a chat. OPERATOR
`send_state`	`send_state(session_id, body) -> SuccessResult`	Send a typing/recording chat state. OPERATOR

`client.webhooks`

Method	Signature	Description
`list`	`list(session_id) -> list[WebhookResponse]`	List webhooks.
`get`	`get(session_id, webhook_id) -> WebhookResponse`	Get one webhook.
`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.
`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[MessageRecord]`	List channel messages.
`subscribe`	`subscribe(session_id, body) -> ChannelRecord`	Subscribe via invite code. OPERATOR
`unsubscribe`	`unsubscribe(session_id, channel_id) -> SuccessResult`	Unsubscribe from a channel. OPERATOR

`client.catalog` (WhatsApp Business)

Method	Signature	Description
`info`	`info(session_id) -> CatalogInfo`	Get catalog info.
`products`	`products(session_id, query=None) -> PaginatedProducts`	List products (paginated).
`product`	`product(session_id, product_id) -> CatalogProduct`	Get one product.
`send_product`	`send_product(session_id, body) -> MessageResponse`	Send a product message. OPERATOR
`send_catalog`	`send_catalog(session_id, body) -> MessageResponse`	Send a catalog link message. 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.
`send_text`	`send_text(session_id, body) -> StatusRecord`	Post a text status. OPERATOR
`send_image`	`send_image(session_id, body) -> StatusRecord`	Post an image status. OPERATOR
`send_video`	`send_video(session_id, body) -> StatusRecord`	Post a video status. OPERATOR
`delete`	`delete(session_id, status_id) -> None`	Delete a status. OPERATOR

`client.templates`

Method	Signature	Description
`list`	`list(session_id) -> list[TemplateRecord]`	List templates.
`get`	`get(session_id, template_id) -> TemplateRecord`	Get one template.
`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.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 inherits from OpenWAError. A non-2xx response raises an OpenWAApiError (or a more specific subclass picked by status); a timeout raises OpenWATimeoutError. The API-error classes carry .status (HTTP code), .body (parsed JSON or raw text), and .error_kind (the NestJS error field).

Exception	Trigger
`OpenWAAuthError`	HTTP `401` — missing or invalid API key
`OpenWAForbiddenError`	HTTP `403` — insufficient role
`OpenWANotFoundError`	HTTP `404` — resource not found
`OpenWAConflictError`	HTTP `409` — typically engine-not-ready
`OpenWARateLimitError`	HTTP `429` — too many requests
`OpenWANotImplementedError`	HTTP `501` — active engine doesn't support the operation
`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("my-session", {
        "chatId": "628123456789@c.us",
        "text": "Hi!",
    })
except OpenWAConflictError:
    print("Session engine not ready yet — start it first.")
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.
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. 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 (guzzlehttp/guzzle: ^7.9).
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_…',
]);

$client->sessions->start('my-session');

$result = $client->messages->sendText('my-session', [
    'chatId' => '628123456789@c.us',
    '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->contacts, $client->groups, $client->webhooks, $client->chats, $client->status, $client->health, $client->labels, $client->channels, $client->catalog, $client->templates.

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.
`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.
`timeout`	`float`	`30.0`	Per-request timeout in seconds.
`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.
`defaultHeaders`	`array<string,string>`	`[]`	Extra headers applied on every request, under the SDK's auth/JSON headers (which always win).

Missing baseUrl or apiKey throws OpenWA\Exceptions\OpenWAException from the constructor.

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.

`sessions`

Method	Signature	Description
`list`	`list(): array`	List all sessions.
`get`	`get(string $id): array`	Get one session.
`create`	`create(array $body): array`	Create a session (`$body['name']` required).
`delete`	`delete(string $id): void`	Delete a session.
`start`	`start(string $id): array`	Start a session.
`stop`	`stop(string $id): array`	Stop a session.
`forceKill`	`forceKill(string $id): array`	Force-kill a session.
`getQrCode`	`getQrCode(string $id): array`	Fetch the current QR code.
`requestPairingCode`	`requestPairingCode(string $id, array $body): array`	Request a phone-pairing code.
`stats`	`stats(): array`	`GET /api/sessions/stats/overview`.

`messages`

Method	Signature	Description
`list`	`list(string $sessionId, array $query = []): array`	List stored messages.
`sendText`	`sendText(string $sessionId, array $body): array`	Send a text message (`send-text`).
`sendImage`	`sendImage(string $sessionId, array $body): array`	Send an image.
`sendVideo`	`sendVideo(string $sessionId, array $body): array`	Send a video.
`sendAudio`	`sendAudio(string $sessionId, array $body): array`	Send audio.
`sendDocument`	`sendDocument(string $sessionId, array $body): array`	Send a document.
`sendSticker`	`sendSticker(string $sessionId, array $body): array`	Send a sticker.
`sendLocation`	`sendLocation(string $sessionId, array $body): array`	Send a location.
`sendContact`	`sendContact(string $sessionId, array $body): array`	Send a contact card.
`sendTemplate`	`sendTemplate(string $sessionId, array $body): array`	Send a stored template.
`reply`	`reply(string $sessionId, array $body): array`	Reply to a message.
`forward`	`forward(string $sessionId, array $body): array`	Forward a message.
`react`	`react(string $sessionId, array $body): array`	React to a message.
`delete`	`delete(string $sessionId, array $body): array`	Delete a message.
`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.
`sendBulk`	`sendBulk(string $sessionId, array $body): array`	Enqueue a bulk send batch.
`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.
`profilePicture`	`profilePicture(string $sessionId, string $contactId): array`	Get a contact's profile picture.
`phone`	`phone(string $sessionId, string $contactId): array`	Resolve a contact's phone number.
`block`	`block(string $sessionId, string $contactId): array`	Block a contact. OPERATOR
`unblock`	`unblock(string $sessionId, string $contactId): array`	Unblock a contact. OPERATOR

`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
`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
`leave`	`leave(string $sessionId, string $groupId): array`	Leave the group. OPERATOR
`inviteCode`	`inviteCode(string $sessionId, string $groupId): array`	Get the invite code.
`revokeInviteCode`	`revokeInviteCode(string $sessionId, string $groupId): array`	Revoke and regenerate the invite code. OPERATOR

`chats`

Method	Signature	Description
`list`	`list(string $sessionId, array $query = []): array`	List chats.
`markRead`	`markRead(string $sessionId, array $body): array`	Mark chat(s) read. OPERATOR
`markUnread`	`markUnread(string $sessionId, array $body): array`	Mark chat(s) unread. OPERATOR
`delete`	`delete(string $sessionId, array $body): array`	Delete chat(s). OPERATOR
`sendState`	`sendState(string $sessionId, array $body): array`	Send a typing/recording state. OPERATOR

`webhooks`

Method	Signature	Description
`list`	`list(string $sessionId): array`	List webhooks.
`get`	`get(string $sessionId, string $id): array`	Get one webhook.
`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.
`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.
`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

`catalog` (WhatsApp Business)

Method	Signature	Description
`info`	`info(string $sessionId): array`	Get catalog info.
`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.
`sendProduct`	`sendProduct(string $sessionId, array $body): array`	Send a product message (`chatId` + `productId`). OPERATOR
`sendCatalog`	`sendCatalog(string $sessionId, array $body): array`	Send a catalog link (`chatId`). 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.
`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
`delete`	`delete(string $sessionId, string $statusId): void`	Delete a status. OPERATOR

`templates`

Method	Signature	Description
`list`	`list(string $sessionId): array`	List templates.
`get`	`get(string $sessionId, string $templateId): array`	Get one template.
`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

`health`

Method	Signature	Description
`check`	`check(): array`	`GET /api/health`.
`live`	`live(): array`	Liveness probe.
`ready`	`ready(): array`	Readiness probe.

Error Handling

All exceptions live in OpenWA\Exceptions and descend from OpenWAException (which extends PHP's \Exception). 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).

Exception	Extends	Trigger
`OpenWAException`	`\Exception`	Base for all SDK errors (also thrown for missing `baseUrl`/`apiKey`).
`OpenWAApiException`	`OpenWAException`	Any non-2xx (including unfollowed 3xx and other 4xx/5xx).
`OpenWAAuthException`	`OpenWAApiException`	`401` — missing/invalid API key.
`OpenWAForbiddenException`	`OpenWAApiException`	`403` — insufficient role (e.g. operator-only endpoint).
`OpenWANotFoundException`	`OpenWAApiException`	`404` — resource not found.
`OpenWAConflictException`	`OpenWAApiException`	`409` — conflict (e.g. engine not ready).
`OpenWARateLimitException`	`OpenWAApiException`	`429` — rate limited.
`OpenWANotImplementedException`	`OpenWAApiException`	`501` — active engine does not support the operation.
`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('my-session', [
        'chatId' => '628123456789@c.us',
        'text'   => 'Hello!',
    ]);
} catch (OpenWAConflictException $e) {
    // 409 — engine not ready yet
} 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 (chat/message/group ids, session names) 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.
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 three SDKs are versioned independently of the gateway and of each other, each following SemVer. They are currently published at 0.1.0 while the gateway is at 0.7.3; an SDK version does not track the gateway version. 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`

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. Until then, 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.

Release process

# JavaScript
cd sdk/javascript && npm test && npm run build && npm run smoke   # smoke = require()+import() packaging check
# Python
cd sdk/python && python -m pytest -q
# PHP
cd sdk/php && composer install && ./vendor/bin/phpunit

CI runs all three suites (path-filtered to sdk/**). 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, update the SDK's CHANGELOG, run the suite above, then tag/publish to the relevant registry.

FilesExpand file tree

18-sdk-design.md

Latest commit

History

18-sdk-design.md

File metadata and controls

18 - SDK Design

18.1 Overview

Design Principles

Resource Coverage

18.2 TypeScript / JavaScript SDK

Installation

Quick Start

Client Configuration

Resources & Methods

sessions

messages

contacts

groups

chats

webhooks

labels (WhatsApp Business)

channels (Newsletters)

catalog (WhatsApp Business)

status (Stories)

templates

health

Error Handling

Notable Behaviors

18.3 Python SDK

Installation

Quick Start

Client Configuration

Resources & Methods

client.sessions

client.messages

client.contacts

client.groups

client.chats

client.webhooks

client.labels (WhatsApp Business)

client.channels (Newsletters)

client.catalog (WhatsApp Business)

client.status (Stories)

client.templates

client.health

Error Handling

Notable Behaviors

18.4 PHP SDK

Installation

Quick Start

Client Configuration

Resources & Methods

sessions

messages

contacts

groups

chats

webhooks

labels (WhatsApp Business)

channels (Newsletters)

catalog (WhatsApp Business)

status (Stories)

templates

health

Error Handling

Notable Behaviors

18.5 n8n Community Node

18.6 SDK Versioning & Releases

Versioning

Contract-drift protection

Release process

`sessions`

`messages`

`contacts`

`groups`

`chats`

`webhooks`

`labels` (WhatsApp Business)

`channels` (Newsletters)

`catalog` (WhatsApp Business)

`status` (Stories)

`templates`

`health`

`client.sessions`

`client.messages`

`client.contacts`

`client.groups`

`client.chats`

`client.webhooks`

`client.labels` (WhatsApp Business)

`client.channels` (Newsletters)

`client.catalog` (WhatsApp Business)

`client.status` (Stories)

`client.templates`

`client.health`

`sessions`

`messages`

`contacts`

`groups`

`chats`

`webhooks`

`labels` (WhatsApp Business)

`channels` (Newsletters)

`catalog` (WhatsApp Business)

`status` (Stories)

`templates`

`health`