Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): carry the contract's engine and limit caveats on types
Yudhi Armyndharis7946782094c1
diff --git a/sdk/go/types_catalog.go b/sdk/go/types_catalog.goindex ab8801005..e17994422 100644--- a/sdk/go/types_catalog.go+++ b/sdk/go/types_catalog.go@@ -2,7 +2,7 @@ package openwaimport "net/url"-// CatalogInfo describes a business catalog.+// CatalogInfo describes a business catalog. ProductCount counts at most the first 51 products on Baileys.type CatalogInfo struct {ID string `json:"id"`Name string `json:"name"`diff --git a/sdk/go/types_channel.go b/sdk/go/types_channel.goindex 4f1b9e6e9..6e7bade51 100644--- a/sdk/go/types_channel.go+++ b/sdk/go/types_channel.go@@ -31,7 +31,7 @@ type ChannelMessageRecord struct {MediaURL string `json:"mediaUrl,omitempty"`}-// ChannelMessageQuery limits the channel message read (default 50).+// ChannelMessageQuery limits the channel message read (default 50, max 100: a larger value is cut to 100).type ChannelMessageQuery struct {Limit *int}diff --git a/sdk/go/types_contact.go b/sdk/go/types_contact.goindex dfd8cacb6..229cf98ff 100644--- a/sdk/go/types_contact.go+++ b/sdk/go/types_contact.go@@ -7,6 +7,9 @@ import "net/url"// IsBlocked reflects the account's real blocklist on both engines. When the blocklist query fails// the field stays at its default rather than reporting "nobody is blocked", and the gateway logs a// warning — so a false is not proof the contact is unblocked if the session's link is unhealthy.+//+// ProfilePicURL is a cached URL that only Baileys can fill (whatsapp-web.js never sets it) and it is+// often absent there too, so its absence does not say whether the contact has a picture.type ContactRecord struct {ID string `json:"id"`Name *string `json:"name,omitempty"`diff --git a/sdk/go/types_search.go b/sdk/go/types_search.goindex ddc4628c8..9c5762f3c 100644--- a/sdk/go/types_search.go+++ b/sdk/go/types_search.go@@ -3,7 +3,9 @@ package openwaimport "net/url"// SearchQuery is the query for GET /search. Q is required; all else optional.-// DateFrom/DateTo are epoch-ms.+// DateFrom/DateTo are epoch-ms. Q holds at most 1000 characters and 32 words (the server answers 400+// above either). Limit defaults to 50 and is capped at the server's SEARCH_LIMIT_MAX (100 by default);+// Offset is at most 100000 (400 above).type SearchQuery struct {Q stringSessionID *stringdiff --git a/sdk/go/types_session.go b/sdk/go/types_session.goindex 5bdbb0ce0..69ed217f2 100644--- a/sdk/go/types_session.go+++ b/sdk/go/types_session.go@@ -261,7 +261,8 @@ type SessionStatsOverview struct {}// SessionConfig is a session's effective runtime configuration. A nil MaxReconnectAttempts means-// unlimited — not unset.+// unlimited — not unset. AutoRejectCalls works on Baileys only: whatsapp-web.js stores the flag but+// cannot reject a call, so calls keep ringing there.type SessionConfig struct {AutoRejectCalls bool `json:"autoRejectCalls"`MaxReconnectAttempts *int `json:"maxReconnectAttempts"`@@ -269,8 +270,9 @@ type SessionConfig struct {}// UpdateSessionConfigRequest is a partial update of a session's config, merged in any session state-// with no restart, re-link or QR scan. AutoRejectCalls applies immediately; MaxReconnectAttempts and-// ReconnectBaseDelay apply on the next start.+// with no restart, re-link or QR scan. AutoRejectCalls applies immediately, on Baileys only (whatsapp-web.js+// stores the flag but cannot reject a call); MaxReconnectAttempts and ReconnectBaseDelay apply on the+// next start.//// The route needs THREE states per field, not two: a key that is absent leaves the value unchanged, a// key sent as explicit null clears it back to the default, and a value sets it. A `*int` withdiff --git a/sdk/go/types_status.go b/sdk/go/types_status.goindex 9fcb496cf..203314bd7 100644--- a/sdk/go/types_status.go+++ b/sdk/go/types_status.go@@ -47,7 +47,8 @@ type StatusMedia struct {ContentType string}-// StatusFont is a WhatsApp status font family.+// StatusFont is a WhatsApp status font family. whatsapp-web.js honors only 0 to 7 and posts 8, 9 and+// 10 in the default font.type StatusFont intconst (diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/CatalogInfo.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/CatalogInfo.javaindex fdffd9436..66121ff57 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/CatalogInfo.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/CatalogInfo.java@@ -1,6 +1,9 @@package com.rmyndharis.openwa.model;-/** WhatsApp Business catalog metadata. Optional fields are {@code null} when absent. */+/**+ * WhatsApp Business catalog metadata. Optional fields are {@code null} when absent.+ * {@code productCount} counts at most the first 51 products on Baileys.+ */public record CatalogInfo(String id,String name,diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/ChannelMessageQuery.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/ChannelMessageQuery.javaindex 5bf19b611..a0749e3e6 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/ChannelMessageQuery.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/ChannelMessageQuery.java@@ -9,7 +9,7 @@ public record ChannelMessageQuery(Integer limit) {public static final class Builder {private Integer limit;- /** Max messages to return (default 50). */+ /** Max messages to return (default 50, max 100: a larger value is cut to 100). */public Builder limit(Integer v) {this.limit = v;return this;diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/ContactRecord.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/ContactRecord.javaindex d12bce3cb..e4ef54420 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/ContactRecord.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/ContactRecord.java@@ -7,6 +7,9 @@ package com.rmyndharis.openwa.model;* query fails the field stays at its default rather than reporting "nobody is blocked", and the* gateway logs a warning — so a false is not proof the contact is unblocked if the link is* unhealthy.+ *+ * <p>{@code profilePicUrl} is a cached URL that only Baileys can fill (whatsapp-web.js never sets it)+ * and it is often absent there too, so its absence does not say whether the contact has a picture.*/public record ContactRecord(String id,diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SearchQuery.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SearchQuery.javaindex 0be8470ec..4c8b6a3f6 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SearchQuery.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SearchQuery.java@@ -7,6 +7,9 @@ package com.rmyndharis.openwa.model;* <p>{@code dateFrom} / {@code dateTo} are epoch-<strong>milliseconds</strong> (the public* contract), even though {@link SearchHit#timestamp()} is epoch-seconds (it mirrors the stored* {@code messages.timestamp} column).+ *+ * <p>{@code limit} defaults to 50 and is capped at the server's {@code SEARCH_LIMIT_MAX} (100 by+ * default); {@code offset} is at most 100000, and the server answers 400 above it.*/public record SearchQuery(String q,@@ -35,7 +38,10 @@ public record SearchQuery(private Integer limit;private Integer offset;- /** Required. The search term; must be non-empty at {@link #build()} time. */+ /**+ * Required. The search term; must be non-empty at {@link #build()} time. At most 1000+ * characters and 32 words; the server answers 400 above either.+ */public Builder q(String v) {this.q = v;return this;diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SendTextStatusRequest.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SendTextStatusRequest.javaindex c1e07ef8f..db5f1032e 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SendTextStatusRequest.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SendTextStatusRequest.java@@ -32,7 +32,10 @@ public record SendTextStatusRequest(String text, List<String> recipients, Stringreturn this;}- /** Font index supported by WhatsApp status. */+ /**+ * Font index supported by WhatsApp status: 0 (default), 1, 2, 6 (bold), 7, 8, 9 or 10.+ * whatsapp-web.js honors only 0 to 7 and posts 8, 9 and 10 in the default font.+ */public Builder font(Integer v) {this.font = v;return this;diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionConfig.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionConfig.javaindex 0088c94d3..7d0c992cc 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionConfig.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionConfig.java@@ -5,7 +5,8 @@ package com.rmyndharis.openwa.model;** <p>A null {@code maxReconnectAttempts} means unlimited — not unset.*- * @param autoRejectCalls whether incoming calls are auto-rejected+ * @param autoRejectCalls whether incoming calls are auto-rejected; Baileys only, whatsapp-web.js stores+ * the flag but cannot reject a call, so calls keep ringing there* @param maxReconnectAttempts cap on consecutive reconnect attempts; null means unlimited* @param reconnectBaseDelay base delay of the reconnect backoff, in milliseconds*/diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateSessionConfigRequest.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateSessionConfigRequest.javaindex bd1c26e27..9230c2a48 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateSessionConfigRequest.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpdateSessionConfigRequest.java@@ -34,7 +34,10 @@ public record UpdateSessionConfigRequest(private boolean clearMaxReconnectAttempts;private boolean clearReconnectBaseDelay;- /** Auto-reject incoming calls. */+ /**+ * Auto-reject incoming calls. Baileys only: whatsapp-web.js stores the flag but cannot reject a+ * call, so calls keep ringing there.+ */public Builder autoRejectCalls(Boolean v) {this.autoRejectCalls = v;return this;diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.tsindex d5ad3705d..4de14ca32 100644--- a/sdk/javascript/src/types.ts+++ b/sdk/javascript/src/types.ts@@ -171,6 +171,7 @@ export interface GroupJoinInfo {* server always reports a concrete `reconnectBaseDelay` and `autoRejectCalls`.*/export interface SessionConfig {+ /** Baileys only: whatsapp-web.js stores the flag but cannot reject a call, so calls keep ringing there. */autoRejectCalls: boolean;maxReconnectAttempts: number | null;reconnectBaseDelay: number;@@ -182,6 +183,7 @@ export interface SessionConfig {* number can express.*/export interface UpdateSessionConfigRequest {+ /** Baileys only: whatsapp-web.js stores the flag but cannot reject a call, so calls keep ringing there. */autoRejectCalls?: boolean | null;maxReconnectAttempts?: number | null;reconnectBaseDelay?: number | null;@@ -765,6 +767,10 @@ export interface ContactRecord {* unblocked if the link is unhealthy.*/isBlocked?: boolean;+ /**+ * A cached picture URL. Only Baileys can fill it (whatsapp-web.js never sets it) and it is often+ * absent there too, so its absence does not say whether the contact has a picture.+ */profilePicUrl?: string | null;}@@ -1217,7 +1223,10 @@ export interface SendTextStatusRequest {recipients?: string[];/** Hex background color, e.g. `#25D366`. */backgroundColor?: string;- /** WhatsApp status font family: 0 (default), 1, 2, 6 (bold), 7, 8, 9, 10. */+ /**+ * WhatsApp status font family: 0 (default), 1, 2, 6 (bold), 7, 8, 9, 10. whatsapp-web.js honors only+ * 0 to 7 and posts 8, 9 and 10 in the default font.+ */font?: 0 | 1 | 2 | 6 | 7 | 8 | 9 | 10;}@@ -1364,7 +1373,7 @@ export interface ChannelMessageRecord {}export interface ChannelMessageQuery {- /** Max messages to return (default 50). */+ /** Max messages to return (default 50, max 100: a larger value is cut to 100). */limit?: number;}@@ -1379,6 +1388,7 @@ export interface CatalogInfo {id: string;name: string;description?: string | null;+ /** Counts at most the first 51 products on Baileys. */productCount: number;url: string;}@@ -1432,7 +1442,10 @@ export interface SendProductRequest {/** Query parameters for `GET /search`. Only `q` is required; all filters are optional. */export interface SearchParams {- /** Search term (required, non-empty — the server rejects empty/whitespace with 400). */+ /**+ * Search term (required, non-empty — the server rejects empty/whitespace with 400). At most 1000+ * characters and 32 words, punctuation included; the server answers 400 above either.+ */q: string;/** Restrict to a single session. */sessionId?: string;@@ -1448,9 +1461,9 @@ export interface SearchParams {dateFrom?: number;/** Epoch-ms upper bound (inclusive). */dateTo?: number;- /** Max hits to return. */+ /** Max hits to return (default 50; capped at the server's SEARCH_LIMIT_MAX, 100 by default). */limit?: number;- /** Pagination offset. */+ /** Pagination offset (at most 100000; the server answers 400 above). */offset?: number;}diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.pyindex fc3c5a0b3..e5000f8e4 100644--- a/sdk/python/openwa/types.py+++ b/sdk/python/openwa/types.py@@ -40,7 +40,8 @@ MessageDirection = Literal["incoming", "outgoing"]DeliveryStatus = Literal["pending", "sent", "delivered", "read", "failed"]# The three windows WhatsApp accepts for a pinned message: 24 hours, 7 days, 30 days.PinDurationSeconds = Literal[86400, 604800, 2592000]-# WhatsApp status font family: 0 (default), 1, 2, 6 (bold), 7, 8, 9, 10.+# WhatsApp status font family: 0 (default), 1, 2, 6 (bold), 7, 8, 9, 10. whatsapp-web.js honors only+# 0 to 7 and posts 8, 9 and 10 in the default font.StatusFont = Literal[0, 1, 2, 6, 7, 8, 9, 10]BulkMessageType = Literal["text", "image", "video", "audio", "document"]BatchMessageStatus = Literal["pending", "sent", "failed", "cancelled"]@@ -284,7 +285,8 @@ class UpdateSessionProxyRequest(TypedDict, total=False):class SessionConfig(TypedDict):"""A session's effective runtime configuration.- ``None`` on ``maxReconnectAttempts`` means unlimited -- not unset.+ ``None`` on ``maxReconnectAttempts`` means unlimited -- not unset. ``autoRejectCalls`` works on+ Baileys only: whatsapp-web.js stores the flag but cannot reject a call, so calls keep ringing there."""autoRejectCalls: bool@@ -296,7 +298,8 @@ class UpdateSessionConfigRequest(TypedDict, total=False):"""Partial update of a session's config, in any state -- no re-link, no QR scan.Send ``None`` for ``maxReconnectAttempts`` to restore unlimited retries, which no in-range number- can express.+ can express. ``autoRejectCalls`` works on Baileys only: whatsapp-web.js stores the flag but cannot+ reject a call, so calls keep ringing there."""autoRejectCalls: bool | None@@ -754,6 +757,9 @@ class ContactRecord(TypedDict, total=False):``isBlocked`` reflects the account's real blocklist on both engines. When the blocklist queryfails the field stays at its default rather than reporting "nobody is blocked", and the gatewaylogs a warning — so a ``False`` is not proof the contact is unblocked if the link is unhealthy.++ ``profilePicUrl`` is a cached URL that only Baileys can fill (whatsapp-web.js never sets it) and it+ is often absent there too, so its absence does not say whether the contact has a picture."""id: Jid@@ -1372,7 +1378,7 @@ class ChannelMessageRecord(TypedDict, total=False):class ChannelMessageQuery(TypedDict, total=False):- """Max messages to return (default 50)."""+ """Max messages to return (default 50, max 100: a larger value is cut to 100)."""limit: int@@ -1388,6 +1394,7 @@ class CatalogInfo(TypedDict, total=False):id: strname: strdescription: str | None+ # Counts at most the first 51 products on Baileys.productCount: inturl: str@@ -1448,7 +1455,9 @@ class SendProductRequest(TypedDict):# keyword, so the optional keys are declared via the functional TypedDict form# (mirrors ListMessagesQuery / MessageRecord). `dateFrom` / `dateTo` are# epoch-ms; the backend binds them against messages.timestamp (epoch-seconds),-# dividing by 1000 internally.+# dividing by 1000 internally. `q` holds at most 1000 characters and 32 words (400 above either).+# `limit` defaults to 50 and is capped at the server's SEARCH_LIMIT_MAX (100 by default); `offset` is+# at most 100000 (400 above).class _SearchQueryRequired(TypedDict):q: str