Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): mark main-only SDK additions in the changelog and design doc

Yudhi Armyndharis303b9c416484
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 259e31cc4..50f48c3e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,12 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Allow chat-restricted API keys to subscribe to chat WebSocket events.
- Allow chat-restricted MCP keys to read and send within their chat allowlist using the REST authorization rules.
- Carry `chatId` in `message.ack` and `message.failed` payloads so a webhook `chatId` or `kind` filter scopes delivery events per chat.
-- Filter stored messages by time, direction, type or message reference, with stable message-time pagination.
+- Filter stored messages by time, direction, type or message reference, with stable message-time pagination; the SDKs take these filters from the next SDK release after 0.5.1.
- Scope built-in message search and group detail/settings to a chat-restricted key's allowed chats; reject plugin search for these keys.
-- Expose poll choices and selection mode in message events, stored messages, history, and dashboard chats.
-- Expose optional last-message types in chat lists and SDKs.
-- Add bounded webhook failure redrive with optional payload retention.
-- Expose caller-supplied send idempotency keys in all five SDKs.
+- Expose poll choices and selection mode in message events, stored messages, history, and dashboard chats; the SDKs type them from the next SDK release after 0.5.1.
+- Expose optional last-message types in chat lists and, from the next SDK release after 0.5.1, in the SDKs.
+- Add bounded webhook failure redrive with optional payload retention; the SDKs expose it from the next SDK release after 0.5.1.
+- Expose caller-supplied send idempotency keys in all five SDKs from the next SDK release after 0.5.1; the 0.5.1 JavaScript and PHP packages ignore the extra argument.
- Add optional 24-hour idempotency keys to twelve single-recipient send routes.
- Add opt-in archive-only chat media with dashboard previews.
- Report RSVPs to WhatsApp events as an `event.response` webhook and WebSocket event on Baileys (#1788, thanks @jelasus).
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 79a9fd856..e999c0487 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -1,5 +1,7 @@
# 18 - SDK Design
+> This document describes `main`. Send idempotency, webhook failure redrive, message-window filters, poll choices, and last-message types are unreleased additions after SDK 0.5.1 and require the corresponding server changes after OpenWA 0.24.0.
+
## 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.
@@ -45,6 +47,8 @@ All five SDKs expose the same fluent surface:
| `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
@@ -1182,4 +1186,4 @@ cd sdk/python && python -m pytest -q
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 unreleased note in §18.1, `sdk/README.md` and the "This README describes `main`" note near the top of that SDK's own README, run the suite above, then tag/publish to the relevant registry.
+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.