Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(label): stop promising that label upsert keeps omitted fields
Yudhi Armyndharisd8466ada7f7d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e65265280..f2341a665 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- `PUT /templates/:id` answers 400, not 500, for a `null` `name` or `body`.- `GET /api/search` answers 400, not 500, for a fractional `limit` or `offset`.- `POST /messages/send-template` without `templateId` or `templateName` answers 400 instead of 404.+- The label upsert documentation no longer says omitted fields are kept: the write replaces the whole label, so an omitted name or colour is not preserved.## [0.23.5] - 2026-09-14diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 2bf969dbf..d525ee67a 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -3938,13 +3938,14 @@ Create or update a label.The label id is **yours to choose** and travels in the path. Whether this creates or updates dependsonly on whether that id already exists — reusing one rewrites that label rather than failing.-Omitted fields are left as they are.+The write replaces the whole label, so send every field it should keep: an omitted name or colour+is not preserved.**Request body** — `UpsertLabelDto`| Field | Type | Required | Constraints | Description || ------- | ------ | -------- | ------------ | -------------------------------------------- |-| `name` | string | No | 1–100 chars | Omit to keep the current name |+| `name` | string | No | 1–100 chars | Not preserved when omitted || `color` | number | No | integer 0–19 | WhatsApp's colour **index**, not a hex value |`color` deliberately does not round-trip with the `hexColor` the read routes return: neither enginediff --git a/openapi.json b/openapi.jsonindex 6e61545c8..c8c63d744 100644--- a/openapi.json+++ b/openapi.json@@ -6497,7 +6497,7 @@]},"put": {- "description": "Baileys only. `PUT` rather than `POST` because the label id is chosen by the caller: WhatsApp carries one `label_edit` write keyed on that id, so whether this creates or updates depends purely on whether the id already exists, and there is no server-assigned id to return.\n\n**Choose an unused id to create.** Reusing one silently rewrites that label rather than failing, because the protocol has no create-only form. Fields left out are left alone.\n\nwhatsapp-web.js can read and assign labels but cannot edit one, and answers `501`.",+ "description": "Baileys only. `PUT` rather than `POST` because the label id is chosen by the caller: WhatsApp carries one `label_edit` write keyed on that id, so whether this creates or updates depends purely on whether the id already exists, and there is no server-assigned id to return.\n\n**Choose an unused id to create.** Reusing one silently rewrites that label rather than failing, because the protocol has no create-only form. The write replaces the whole label, so send every field it should keep: an omitted name or colour is not preserved.\n\nwhatsapp-web.js can read and assign labels but cannot edit one, and answers `501`.","operationId": "LabelController_upsertLabel","parameters": [{@@ -15284,14 +15284,14 @@"properties": {"name": {"type": "string",- "description": "Label name. Omit to leave the current name untouched.",+ "description": "Label name. The write replaces the whole label, so an omitted name is not preserved.","example": "VIP customer","minLength": 1,"maxLength": 100},"color": {"type": "number",- "description": "WhatsApp's colour INDEX (0-19), not a hex value — the read path's `hexColor` cannot be translated back, because neither engine exposes the mapping. Omit to leave the colour alone.",+ "description": "WhatsApp's colour INDEX (0-19), not a hex value — the read path's `hexColor` cannot be translated back, because neither engine exposes the mapping. An omitted colour is not preserved.","example": 3,"minimum": 0,"maximum": 19diff --git a/sdk/go/labels.go b/sdk/go/labels.goindex f9c86ee8a..6a16a526b 100644--- a/sdk/go/labels.go+++ b/sdk/go/labels.go@@ -41,7 +41,8 @@ func (s *LabelsService) Chats(ctx context.Context, sessionID, labelID string) ([//// PUT rather than POST because the caller chooses the id: WhatsApp carries one write keyed on it, so// whether this creates or updates depends purely on whether that id already exists. Pick an unused-// id to create — reusing one rewrites that label rather than failing. Omitted fields are left alone.+// id to create — reusing one rewrites that label rather than failing.+// The write replaces the whole label, so an omitted field is not preserved.func (s *LabelsService) Upsert(ctx context.Context, sessionID, labelID string, body UpsertLabelRequest) (*SuccessResult, error) {var out SuccessResulterr := s.client.do(ctx, "PUT", s.base(sessionID)+"/"+pathEscape(labelID), nil, body, &out)diff --git a/sdk/go/types_session.go b/sdk/go/types_session.goindex 5dc777537..d8376481d 100644--- a/sdk/go/types_session.go+++ b/sdk/go/types_session.go@@ -67,11 +67,11 @@ type CustomLinkPreview struct {// UpsertLabelRequest is a label create-or-update body. The id travels in the path, because WhatsApp// keys the write on it.type UpsertLabelRequest struct {- // Name is left alone when nil.+ // Name nil drops the current name: the write replaces the whole label.Name *string `json:"name,omitempty"`// Color is WhatsApp's colour INDEX (0-19), NOT a hex value — it does not round-trip with the- // HexColor labels are read back with, because neither engine exposes the mapping. Nil leaves the- // current colour alone.+ // HexColor labels are read back with, because neither engine exposes the mapping. Nil drops+ // the current colour.Color *int `json:"color,omitempty"`}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpsertLabelRequest.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpsertLabelRequest.javaindex 4a338a3a6..7cb9a70b8 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpsertLabelRequest.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/UpsertLabelRequest.java@@ -3,9 +3,9 @@ package com.rmyndharis.openwa.model;/*** A label create-or-update body. The id travels in the path, because WhatsApp keys the write on it.*- * @param name {@code null} leaves the current name alone+ * @param name {@code null} drops the current name: the write replaces the whole label* @param color WhatsApp's colour INDEX (0-19), NOT a hex value — it does not round-trip with the* {@code hexColor} labels are read back with, because neither engine exposes the mapping;- * {@code null} leaves the current colour alone+ * {@code null} drops the current colour*/public record UpsertLabelRequest(String name, Integer color) {}diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/LabelsResource.java b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/LabelsResource.javaindex 6d9a3e2e2..970f63b9d 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/LabelsResource.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/LabelsResource.java@@ -59,7 +59,7 @@ public final class LabelsResource {* <p>{@code PUT} rather than {@code POST} because you choose the id: WhatsApp carries one write* keyed on it, so whether this creates or updates depends purely on whether that id already* exists. Pick an unused id to create — reusing one rewrites that label rather than failing.- * Omitted fields are left alone.+ * The write replaces the whole label, so an omitted field is not preserved.*/public SuccessResult upsert(String sessionId, String labelId, UpsertLabelRequest body) {return client.request(diff --git a/sdk/javascript/src/resources/labels.ts b/sdk/javascript/src/resources/labels.tsindex 0aaf101d7..0d4cd8fb1 100644--- a/sdk/javascript/src/resources/labels.ts+++ b/sdk/javascript/src/resources/labels.ts@@ -46,7 +46,8 @@ export class LabelsResource {** `PUT`, not `POST`, because you choose the id: WhatsApp carries one write keyed on it, so whether* this creates or updates depends purely on whether that id already exists. Pick an unused id to- * create — reusing one rewrites that label rather than failing. Omitted fields are left alone.+ * create — reusing one rewrites that label rather than failing. The write replaces the whole+ * label, so an omitted field is not preserved.*/upsert(sessionId: string, labelId: string, body: UpsertLabelRequest): Promise<SuccessResult> {return this.client.request<SuccessResult>({diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.tsindex ebabff0d7..5385b3f19 100644--- a/sdk/javascript/src/types.ts+++ b/sdk/javascript/src/types.ts@@ -120,12 +120,12 @@ export interface ChatPresence {* A label create-or-update body. The id travels in the path, because WhatsApp keys the write on it.*/export interface UpsertLabelRequest {- /** Leave out to keep the current name. */+ /** Not preserved when left out: the write replaces the whole label. */name?: string;/*** WhatsApp's colour INDEX (0-19), NOT a hex value — it does not round-trip with the `hexColor`- * labels are read back with, because neither engine exposes the mapping. Leave out to keep the- * current colour.+ * labels are read back with, because neither engine exposes the mapping. Not preserved when+ * left out either.*/color?: number;}diff --git a/sdk/php/src/Resources/LabelsResource.php b/sdk/php/src/Resources/LabelsResource.phpindex a7a05ed7e..3c0f907ba 100644--- a/sdk/php/src/Resources/LabelsResource.php+++ b/sdk/php/src/Resources/LabelsResource.php@@ -49,8 +49,8 @@ class LabelsResource** PUT rather than POST because you choose the id: WhatsApp carries one write keyed on it, so* whether this creates or updates depends purely on whether that id already exists. Pick an- * unused id to create — reusing one rewrites that label rather than failing. Omitted fields are- * left alone.+ * unused id to create — reusing one rewrites that label rather than failing. The write replaces+ * the whole label, so an omitted field is not preserved.** @param array<string,mixed> $body* @return array<string,mixed>diff --git a/sdk/python/openwa/resources/labels.py b/sdk/python/openwa/resources/labels.pyindex c2632a1d7..09762a1b6 100644--- a/sdk/python/openwa/resources/labels.py+++ b/sdk/python/openwa/resources/labels.py@@ -41,8 +41,8 @@ class LabelsResource:PUT rather than POST because you choose the id: WhatsApp carries one write keyed on it, sowhether this creates or updates depends purely on whether that id already exists. Pick an- unused id to create -- reusing one rewrites that label rather than failing. Omitted fields- are left alone.+ unused id to create -- reusing one rewrites that label rather than failing. The write+ replaces the whole label, so an omitted field is not preserved."""return self._http.request("PUT", f"/api/sessions/{quote_segment(session_id)}/labels/{quote_segment(label_id)}", body=bodydiff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.pyindex 2edb29d41..4e1b6870a 100644--- a/sdk/python/openwa/types.py+++ b/sdk/python/openwa/types.py@@ -168,7 +168,7 @@ class ChatPresence(TypedDict, total=False):class UpsertLabelRequest(TypedDict, total=False):"""A label create-or-update body. The id travels in the path -- WhatsApp keys the write on it."""- # Leave out to keep the current name.+ # Not preserved when left out: the write replaces the whole label.name: str# WhatsApp's colour INDEX (0-19), NOT a hex value -- it does not round-trip with the hexColor# labels are read back with, because neither engine exposes the mapping.diff --git a/src/core/agent-tools/tools/label.tools.ts b/src/core/agent-tools/tools/label.tools.tsindex 8bf6ca30f..aac07aa64 100644--- a/src/core/agent-tools/tools/label.tools.ts+++ b/src/core/agent-tools/tools/label.tools.ts@@ -67,14 +67,14 @@ export function labelTools(labels: LabelService): AnyToolDescriptor[] {inputSchema: z.object({sessionId,labelId,- name: z.string().min(1).max(100).optional().describe('Label text; left unchanged when omitted'),+ name: z.string().min(1).max(100).optional().describe('Label text; not preserved when omitted'),color: z.number().int().min(0).max(19).optional()- .describe('WhatsApp colour index 0-19; left unchanged when omitted'),+ .describe('WhatsApp colour index 0-19; not preserved when omitted'),}),handler: input =>labelsdiff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.tsindex 6daf60dc6..92a0b445b 100644--- a/src/engine/adapters/baileys.adapter.ts+++ b/src/engine/adapters/baileys.adapter.ts@@ -628,7 +628,9 @@ export class BaileysAdapter implements IWhatsAppEngine {this.ensureReady();// Unset fields are passed through as undefined rather than stripped: the protobuf encoder skips// a field that is `!= null` false, exactly as it skips a missing one (WAProto/index.js,- // LabelEditAction.encode), so an omitted name really does leave the stored name alone. Colour 0+ // LabelEditAction.encode). That does not make the write partial: the patch is an app-state SET+ // on ['label_edit', id], which replaces the stored action whole, so an omitted name is not kept+ // (Utils/chat-utils.js builds it with OP.SET and the receiver applies it without a merge). Colour 0// is a real WhatsApp colour and survives that check — which is why it must never be tested for// truthiness on the way here.await withQueryDeadline(diff --git a/src/modules/label/dto/upsert-label.dto.ts b/src/modules/label/dto/upsert-label.dto.tsindex b6956ae48..23edc7a5a 100644--- a/src/modules/label/dto/upsert-label.dto.ts+++ b/src/modules/label/dto/upsert-label.dto.ts@@ -8,7 +8,7 @@ import { ToStrictNumber } from '../../../common/utils/strict-boolean';*/export class UpsertLabelDto {@ApiPropertyOptional({- description: 'Label name. Omit to leave the current name untouched.',+ description: 'Label name. The write replaces the whole label, so an omitted name is not preserved.',example: 'VIP customer',minLength: 1,maxLength: 100,@@ -24,7 +24,7 @@ export class UpsertLabelDto {@ApiPropertyOptional({description:"WhatsApp's colour INDEX (0-19), not a hex value — the read path's `hexColor` cannot be " +- 'translated back, because neither engine exposes the mapping. Omit to leave the colour alone.',+ 'translated back, because neither engine exposes the mapping. An omitted colour is not preserved.',example: 3,minimum: 0,maximum: 19,diff --git a/src/modules/label/label.controller.ts b/src/modules/label/label.controller.tsindex 07ad7d496..b0782a083 100644--- a/src/modules/label/label.controller.ts+++ b/src/modules/label/label.controller.ts@@ -87,7 +87,8 @@ export class LabelController {'carries one `label_edit` write keyed on that id, so whether this creates or updates depends ' +'purely on whether the id already exists, and there is no server-assigned id to return.\n\n' +'**Choose an unused id to create.** Reusing one silently rewrites that label rather than ' +- 'failing, because the protocol has no create-only form. Fields left out are left alone.\n\n' ++ 'failing, because the protocol has no create-only form. The write replaces the whole label, so ' ++ 'send every field it should keep: an omitted name or colour is not preserved.\n\n' +'whatsapp-web.js can read and assign labels but cannot edit one, and answers `501`.',})@ApiParam({ name: 'sessionId', description: 'Session ID' })