Labels

The Labels feature manages WhatsApp chat labels (etiquetas) — the colored tags WhatsApp Business uses to organize chats. Outbound calls create, rename, recolor, or delete labels and add or remove a label on a chat. Inbound label changes made on a linked device (such as WhatsApp Web or the phone) are delivered as events. Labels sync across all linked devices via WhatsApp’s app state sync mechanism (the regular collection, action version 3).

Access

Access label operations through the client:

let labels = client.labels();

Create or update a label

create_label

Create a new label or update an existing one. Because app state is an upsert keyed by label_id, calling this with an existing label_id renames or recolors that label.

pub async fn create_label(
    &self,
    label_id: &str,
    name: &str,
    color: i32,
) -> Result<(), AppStateError>

Parameters:

label_id — Stable identifier for the label. Must be non-empty. Reuse the same label_id to update the label later.
name — Display name shown in the WhatsApp UI. Must be non-empty.
color — WhatsApp color index for the label swatch.

Example:

// Create a new "Work" label
client.labels().create_label("5", "Work", 2).await?;

// Rename and recolor the same label later
client.labels().create_label("5", "Clients", 4).await?;

Delete a label

delete_label

Delete a label. Existing chat associations are kept by the server; WhatsApp Web prunes them from its local database on receipt of the delete.

pub async fn delete_label(&self, label_id: &str) -> Result<(), AppStateError>

Parameters:

label_id — The label to delete. Must be non-empty.

Example:

client.labels().delete_label("5").await?;

Associate a label with a chat

add_chat_label

Tag a chat with a label.

pub async fn add_chat_label(
    &self,
    label_id: &str,
    chat_jid: &Jid,
) -> Result<(), AppStateError>

Parameters:

label_id — The label to apply. Must be non-empty.
chat_jid — The chat to label.

Example:

use wacore_binary::jid::Jid;

let chat: Jid = "15551234567@s.whatsapp.net".parse()?;
client.labels().add_chat_label("5", &chat).await?;

remove_chat_label

Remove a label from a chat.

pub async fn remove_chat_label(
    &self,
    label_id: &str,
    chat_jid: &Jid,
) -> Result<(), AppStateError>

Parameters:

label_id — The label to remove. Must be non-empty.
chat_jid — The chat to untag.

Example:

client.labels().remove_chat_label("5", &chat).await?;

Associate a label with a message

add_message_label

Use this to associate a label with a single message. Unlike add_chat_label above, this association is keyed by the message as well as the chat, under the label_message action.

pub async fn add_message_label(
    &self,
    label_id: &str,
    chat_jid: &Jid,
    message_id: &str,
) -> Result<(), AppStateError>

Parameters:

label_id — The label to apply. Must be non-empty.
chat_jid — The chat containing the message.
message_id — The message to label. Must be non-empty.

Example:

client.labels().add_message_label("5", &chat, "MESSAGE_ID").await?;

remove_message_label

Remove a label association from a single message.

pub async fn remove_message_label(
    &self,
    label_id: &str,
    chat_jid: &Jid,
    message_id: &str,
) -> Result<(), AppStateError>

Parameters:

label_id — The label to remove. Must be non-empty.
chat_jid — The chat containing the message.
message_id — The message to unlabel. Must be non-empty.

Example:

client.labels().remove_message_label("5", &chat, "MESSAGE_ID").await?;

Both calls send one mutation per message. There is no batch form on the wire, matching WhatsApp Web’s own builder.

label_message is not in the generated app-state schema registry, because WhatsApp Web’s current live action table no longer builds this mutation (only label_edit and label_jid remain there). It is still a first-class protocol action: the protobuf action registry declares it, and both whatsmeow and Baileys build the identical index. For that reason the schema is hand-maintained separately from the generated set. The wire index is ["label_message", labelId, chatJid, messageId, "0", "0"] on the regular collection at action version 3. The trailing "0", "0" pair is the message-key fromMe/participant tail every message-scoped action carries, and no observed source shows it holding anything but its defaults.

Inbound label events

Label changes made on a linked device are delivered through the event bus. All three events carry the underlying app state action so you can read the new name, color, deleted flag, or labeled state directly.

use wacore::types::events::Event;

.on_event(|event, _client| async move {
    match &*event {
        Event::LabelEditUpdate(update) => {
            if update.action.deleted == Some(true) {
                println!("Label {} deleted", update.label_id);
            } else {
                println!(
                    "Label {} = {:?} (color {:?})",
                    update.label_id,
                    update.action.name,
                    update.action.color,
                );
            }
        }
        Event::LabelAssociationUpdate(update) => {
            let attached = update.action.labeled == Some(true);
            println!(
                "Label {} {} chat {}",
                update.label_id,
                if attached { "added to" } else { "removed from" },
                update.chat_jid,
            );
        }
        Event::MessageLabelAssociationUpdate(update) => {
            let attached = update.action.labeled == Some(true);
            println!(
                "Label {} {} message {} in chat {}",
                update.label_id,
                if attached { "added to" } else { "removed from" },
                update.message_id,
                update.chat_jid,
            );
        }
        _ => {}
    }
})

from_full_sync is true when the event came from an initial app state full sync, so you can suppress UI notifications during bootstrap.

App state sync

Action	Collection	Action version
Create / update / delete label	`regular`	3
Add / remove chat label association	`regular`	3
Add / remove message label association	`regular`	3

App state sync requires the relevant encryption keys, which arrive during initial sync after pairing. Outbound label calls may fail if invoked immediately after pairing before sync completes.

create_label, delete_label, add_chat_label, and remove_chat_label are thin wrappers over the same app-state send path as chat actions. They share its conflict-retry behavior, added in PR #1158. A call that loses a version race with another linked device is no longer silently dropped. The client applies the winning patches, rebuilds the mutation, and resends. It retries up to 5 times before returning Err. See Chat actions — App state sync for the full explanation.

Error handling

All methods return Result<(), AppStateError>. If you pass an empty label_id (or an empty name to create_label), the call fails immediately with AppStateError::InvalidRequest before any network work is done. A call can also return AppStateError::Internal if no app state sync key is available yet, a network error occurred, or an app-state version conflict with another device could not be resolved after 5 rebuild-and-resend attempts (see App state sync above).

use whatsapp_rust::AppStateError;

if let Err(AppStateError::InvalidRequest(msg)) = client.labels().create_label("", "Work", 0).await {
    eprintln!("Validation failed: {msg}"); // "label_id cannot be empty"
}

Complete example

use whatsapp_rust::Client;
use wacore_binary::jid::Jid;
use std::sync::Arc;

async fn tag_vip_chats(client: &Arc<Client>) -> anyhow::Result<()> {
    let vip: Jid = "15551234567@s.whatsapp.net".parse()?;
    let lead: Jid = "15559876543@s.whatsapp.net".parse()?;

    // Create a "VIP" label (color index 3)
    client.labels().create_label("vip", "VIP", 3).await?;

    // Tag two chats
    client.labels().add_chat_label("vip", &vip).await?;
    client.labels().add_chat_label("vip", &lead).await?;

    // Later: drop one of the chats from the label
    client.labels().remove_chat_label("vip", &lead).await?;

    Ok(())
}

Core

Messaging

Features

Storage & Backends

Core Modules

Access

Create or update a label

create_label

Delete a label

delete_label

Associate a label with a chat

add_chat_label

remove_chat_label

Associate a label with a message

add_message_label

remove_message_label

Inbound label events

App state sync

Error handling

Complete example

See also

​Access

​Create or update a label

​create_label

​Delete a label

​delete_label

​Associate a label with a chat

​add_chat_label

​remove_chat_label

​Associate a label with a message

​add_message_label

​remove_message_label

​Inbound label events

​App state sync

​Error handling

​Complete example

​See also

Access

Create or update a label

create_label

Delete a label

delete_label

Associate a label with a chat

add_chat_label

remove_chat_label

Associate a label with a message

add_message_label

remove_message_label

Inbound label events

App state sync

Error handling

Complete example

See also