Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wppconnect-team/wa-js/llms.txt

Use this file to discover all available pages before exploring further.

The WPP.labels module lets you create, edit, delete, and apply colored label tags to chats in a WhatsApp Business account. Labels appear as colored chip badges on conversations in the chat list, making it easy to categorize leads, orders, support tickets, or any other workflow state without changing the chat itself. Every function in this module enforces a Business account check via assertIsBusiness() and will throw immediately on a personal account.
All functions in WPP.labels require a WhatsApp Business account. Calling any function from a standard personal account throws a WPPError before any network request is made. If you need organizational features that work on personal accounts, use WPP.lists instead.

​
Labels vs. lists

FeatureWPP.labelsWPP.lists
Account typeBusiness onlyPersonal and Business
AppearanceColored chip tags on each chatNamed filter tabs at the top of the chat list
Multiple per chatYesNo
Color pickerYesAutomatic
Use WPP.labels when you need per-chat tagging with color coding. Use WPP.lists when you need named tabs that filter the entire chat list.

​
Color system

Labels use a fixed color palette managed internally by WhatsApp Business. Colors are referenced either as:
  • A hex string like '#dfaef0'
  • A decimal index like 16
Use getLabelColorPalette() to see all valid hex values, and getNewLabelColor() to get an automatically chosen next color. colorIsInLabelPalette() validates a color before you attempt to create or edit a label.

​
Functions

​
getAllLabels

Returns every label defined in the Business account. 
WPP.labels.getAllLabels()
Returns Promise<Label[]>
​
id
string
Numeric string identifier for the label (e.g. '76').
​
name
string
Display name of the label.
​
color
string | null
Asserted hex color string, or null.
​
hexColor
string
Hex color derived from colorIndex.
​
colorIndex
number
Integer index into the WhatsApp color palette.
​
count
number
Number of chats that currently have this label applied.
const labels = await WPP.labels.getAllLabels();
for (const label of labels) {
  console.log(`[${label.id}] ${label.name} — ${label.hexColor} (${label.count} chats)`);
}

​
getLabelById

Fetches a single label by its numeric string ID. 
WPP.labels.getLabelById(labelId)
​
labelId
string
required
Numeric string ID of the label (e.g. '76').
Returns Promise<Label> — same shape as an item from getAllLabels. Throws WPPError with code canot_get_label_error if no label with that ID exists. 
const label = await WPP.labels.getLabelById('76');
console.log(label.name, label.hexColor);

​
addNewLabel

Creates a new label with a given name and optional color. If no color is provided, one is chosen automatically from the palette. 
WPP.labels.addNewLabel(labelName, options?)
​
labelName
string
required
Display name for the new label.
​
options
object
Returns Promise<Label> — the newly created label object. Throws WPPError with code color_not_in_pallet if the specified color is not in the WhatsApp palette. 
// Auto color
const newLabel = await WPP.labels.addNewLabel('New Leads');

// Specific hex color
const colored = await WPP.labels.addNewLabel('VIP', { labelColor: '#dfaef0' });

// Specific palette index
const indexed = await WPP.labels.addNewLabel('Urgent', { labelColor: 16 });

​
editLabel

Renames an existing label and/or changes its color. Fields not included in options are preserved. 
WPP.labels.editLabel(id, options?)
​
id
string
required
Numeric string ID of the label to edit.
​
options
object
Returns Promise<Label> — the updated label object. Throws WPPError with code label_not_exist if the ID is not found, or color_not_in_pallet if the color is invalid. 
// Rename only
await WPP.labels.editLabel('76', { name: 'Hot Leads' });

// Change color only
await WPP.labels.editLabel('76', { labelColor: '#ffd429' });

// Rename and recolor
await WPP.labels.editLabel('76', { name: 'Priority', labelColor: 4 });

​
deleteLabel

Deletes one label, or an array of labels, by ID. 
// Single label
WPP.labels.deleteLabel(id)

// Multiple labels
WPP.labels.deleteLabel(ids)
​
id
string
required
Numeric string ID of the label to delete when passing a single value.
​
ids
string[]
required
Array of numeric string IDs when deleting multiple labels in one call.
Returns
  • Promise<DeleteLabelReturn> for a single ID
  • Promise<DeleteLabelReturn[]> for an array of IDs
​
id
string
The label ID that was processed.
​
deleteLabelResult
boolean
true if the label was found and successfully removed, false otherwise.
// Delete a single label
const result = await WPP.labels.deleteLabel('76');
console.log(result.deleteLabelResult); // true or false

// Delete multiple labels at once
const results = await WPP.labels.deleteLabel(['76', '77', '78']);
results.forEach((r) => console.log(r.id, r.deleteLabelResult));

​
deleteAllLabels

Convenience wrapper that fetches all labels then deletes every one of them in a single operation. 
WPP.labels.deleteAllLabels()
Returns Promise<DeleteLabelReturn[]> — one result entry per deleted label.
deleteAllLabels removes every label from the Business account. Any labels applied to chats will also be detached. This cannot be undone.
const results = await WPP.labels.deleteAllLabels();
console.log(`Deleted ${results.length} labels`);

​
addOrRemoveLabels

Applies or removes one or more labels from one or more chats in a single operation. 
WPP.labels.addOrRemoveLabels(chatIds, options)
​
chatIds
string | Wid | (string | Wid)[]
required
One chat ID or an array of chat IDs to act on (e.g. '15551234567@c.us').
​
options
AddOrRemoveLabelsOptions | AddOrRemoveLabelsOptions[]
required
One operation or an array of operations. Each entry describes a single label action.
Returns Promise<any> — the raw result from LabelStore.addOrRemoveLabels.
You can mix add and remove operations in a single call. This is the most efficient way to relabel a batch of chats — for example, moving them from one pipeline stage to another.
// Add one label to two chats
await WPP.labels.addOrRemoveLabels(
  ['15551111111@c.us', '15552222222@c.us'],
  [{ labelId: '76', type: 'add' }]
);

// Add one label and remove another from a single chat
await WPP.labels.addOrRemoveLabels(
  '15551234567@c.us',
  [
    { labelId: '76', type: 'add' },
    { labelId: '75', type: 'remove' },
  ]
);

​
getLabelColorPalette

Returns the full list of valid label colors as hex strings. 
WPP.labels.getLabelColorPalette()
Returns Promise<string[]> — array of hex color strings in palette order (index 0 is the first color, etc.). Throws WPPError with code canot_get_color_palette if the palette cannot be retrieved. 
const palette = await WPP.labels.getLabelColorPalette();
console.log(palette);
// ['#ff6b6b', '#ffd429', '#dfaef0', ...]

​
getNewLabelColor

Returns the decimal index of the next available (unused) color in the palette, suitable for auto-assigning to a new label. 
WPP.labels.getNewLabelColor()
Returns Promise<number> — a positive decimal integer representing the next color index. Throws WPPError with code cannot_get_color if the color cannot be determined. 
const nextColor = await WPP.labels.getNewLabelColor();
await WPP.labels.addNewLabel('Pipeline Stage 3', { labelColor: nextColor });

​
colorIsInLabelPalette

Validates whether a given color (hex string or decimal index) is part of the official WhatsApp Business label palette. 
WPP.labels.colorIsInLabelPalette(color)
​
color
string | number
required
Color to validate. Accepts a hex string (e.g. '#ffd429') or a decimal index (e.g. 4284794111).
Returns Promise<boolean> — true if the color is valid, false otherwise. 
const valid = await WPP.labels.colorIsInLabelPalette('#ffd429');
console.log(valid); // true or false

const validByIndex = await WPP.labels.colorIsInLabelPalette(4284794111);
console.log(validByIndex);

​
Full workflow example

The following example models a simple CRM pipeline: create the label stages, tag incoming chats, and advance a chat from one stage to the next. 
// 1. Set up pipeline stages
const palette = await WPP.labels.getLabelColorPalette();
const newLead   = await WPP.labels.addNewLabel('New Lead',   { labelColor: palette[0] });
const contacted = await WPP.labels.addNewLabel('Contacted',  { labelColor: palette[1] });
const closed    = await WPP.labels.addNewLabel('Closed',     { labelColor: palette[2] });

// 2. Tag a new enquiry
const chatId = '15551234567@c.us';
await WPP.labels.addOrRemoveLabels(chatId, [{ labelId: newLead.id, type: 'add' }]);

// 3. Advance to "Contacted"
await WPP.labels.addOrRemoveLabels(chatId, [
  { labelId: newLead.id,   type: 'remove' },
  { labelId: contacted.id, type: 'add' },
]);

// 4. Close the lead
await WPP.labels.addOrRemoveLabels(chatId, [
  { labelId: contacted.id, type: 'remove' },
  { labelId: closed.id,    type: 'add' },
]);

Build docs developers (and LLMs) love

Get started for freeTalk to us