Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(label): stop promising that label upsert keeps omitted fields

Yudhi Armyndharisd8466ada7f7d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-14
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 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 depends
only 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 engine
diff --git a/openapi.json b/openapi.json
index 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": 19
diff --git a/sdk/go/labels.go b/sdk/go/labels.go
index 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 SuccessResult
err := 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.go
index 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.java
index 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.java
index 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.ts
index 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.ts
index 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.php
index 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.py
index 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, 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.
"""
return self._http.request(
"PUT", f"/api/sessions/{quote_segment(session_id)}/labels/{quote_segment(label_id)}", body=body
diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.py
index 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.ts
index 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 =>
labels
diff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.ts
index 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.ts
index 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.ts
index 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' })