Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.go
index ab8801005..e17994422 100644
--- a/sdk/go/types_catalog.go
+++ b/sdk/go/types_catalog.go
@@ -2,7 +2,7 @@ package openwa
import "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.go
index 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.go
index 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.go
index ddc4628c8..9c5762f3c 100644
--- a/sdk/go/types_search.go
+++ b/sdk/go/types_search.go
@@ -3,7 +3,9 @@ package openwa
import "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 string
SessionID *string
diff --git a/sdk/go/types_session.go b/sdk/go/types_session.go
index 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` with
diff --git a/sdk/go/types_status.go b/sdk/go/types_status.go
index 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 int
const (
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.java
index 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.java
index 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.java
index 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.java
index 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.java
index 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, String
return 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.java
index 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.java
index 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.ts
index 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.py
index 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 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.
+
+ ``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: str
name: str
description: str | None
+ # Counts at most the first 51 products on Baileys.
productCount: int
url: 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