Feature request: read WhatsApp Lists / labels (chat and message associations)

[betobetico]

Summary

wacli has no way to read WhatsApp Lists (the chat filters in the personal app, called labels at the protocol level). Neither the list a chat belongs to, nor the labels attached to an individual message.

This is not a protocol limitation — whatsmeow already decodes all of it. It is just not wired up in wacli.

Why "labels" are the personal-account Lists

Worth stating explicitly, because "labels" reads like a WhatsApp Business–only feature. It is not: WhatsApp's own protobuf models the personal Lists on top of the label app-state. LabelEditAction in proto/waSyncAction/WAWebProtobufSyncAction.proto carries an enum literally named ListType:

message LabelEditAction {
	enum ListType {
		NONE = 0;
		UNREAD = 1;
		GROUPS = 2;
		FAVORITES = 3;
		PREDEFINED = 4;
		CUSTOM = 5;
		COMMUNITY = 6;
		...
		ARCHIVED = 12;
		LOCKED = 13;
		MENTIONS_AND_REPLIES = 17;
	}

	optional string name = 1;
	optional int32 color = 2;
	optional int32 predefinedID = 3;
	optional bool deleted = 4;
	optional int32 orderIndex = 5;
	optional bool isActive = 6;
	optional ListType type = 7;
	optional bool isImmutable = 8;
	optional int64 muteEndTimeMS = 9;
}

UNREAD, GROUPS, FAVORITES, CUSTOM are exactly the filter chips above the chat list, and orderIndex / isActive are their UI state.

What's already available upstream

App-state indices (appstate/keys.go):

• label_edit — the list/label itself (name, color, order, type)
• label_jid — chat ↔ label association
• label_message — message ↔ label association
• label_reordering, label_sublist

Events (types/events/appstate.go), none of which wacli currently handles:

• events.LabelEdit — LabelID, Action *waSyncAction.LabelEditAction
• events.LabelAssociationChat — JID, LabelID, Action.Labeled
• events.LabelAssociationMessage — JID, MessageID, LabelID, Action.Labeled

Current state in wacli

Checked against main (57124e0, 0.17.3-unreleased):

• internal/store/schema.sql — chats stores archived, pinned, muted_until, unread, unread_count; no label/list column. messages has none either.
• No events.Label* handler anywhere in the tree.
• contact_tags exists but is unrelated: docs/contacts.md states aliases and tags are local to wacli and do not touch WhatsApp.

Proposal

Read-only support would already cover most scripting and agent use cases:

1. Store labels and their associations — e.g. labels(label_id, name, color, type, order_index, is_active, deleted), chat_labels(chat_jid, label_id), message_labels(chat_jid, msg_id, label_id).
2. Handle events.LabelEdit / LabelAssociationChat / LabelAssociationMessage, and hydrate on full sync.
3. Surface it:
   • wacli labels list
   • wacli chats list --label NAME (and label_ids in chats list --json / chats show --json)
   • label_ids in messages list --json / messages search --json

Write support (wacli chats label add|rm) would be a natural follow-up, but read-only is the valuable half.

Use case

Triaging an assistant's WhatsApp inbox by the same Lists the user already curates on their phone, instead of maintaining a parallel taxonomy in contact_tags that never stays in sync.

Caveat

Label behaviour on non-business accounts has been reported as flaky elsewhere (e.g. devlikeapro/waha#1581 mentions labels resetting after re-login). Worth validating against a personal account before committing to a schema.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 17, 2026, 10:42 AM ET / 14:42 UTC.

Summary
The capability remains absent from current main. The new personal-account observations materially strengthen the proposal for custom Lists and chat memberships; initial scope still needs product approval.

Reproducibility: not applicable. as a bug reproduction: this requests a new capability whose absence is confirmed in source. The comment supplies useful personal-account observations for custom chat memberships.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Maintainer decision needed

Question	Recommendation
Should the first supported scope cover custom Lists and chat memberships while deferring favorites, message labels, and write operations?	Sponsor custom Lists first: Approve read-only custom definitions and chat memberships, with explicit hydration semantics and relink validation before release.

Why: The account observations support a narrower useful feature, but accepting that scope and its persistent CLI/data contract requires maintainer intent.

Next step
Approve the initial Lists scope and hydration contract before implementation; this spans sync, persistent storage, and new CLI surface rather than a bounded existing-behavior repair.

Review details

Best possible solution:

Start with read-only custom Lists and current chat memberships using existing app-state sync and identity mapping, with replay-safe storage and fresh-store, upgrade, and relink validation.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this requests a new capability whose absence is confirmed in source. The comment supplies useful personal-account observations for custom chat memberships.

Is this the best way to solve the issue?

Yes, a narrower read-only custom-List implementation is the best-supported starting point; the existing full-sync path can supply events without inventing a parallel taxonomy.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Favorites, message associations, and fresh-relink behavior have not been established by the reported account run.
• The storage contract must distinguish removed memberships and incomplete hydration from a genuinely empty custom List, while handling LID and phone identities consistently.

Codex review notes: model internal, reasoning medium; reviewed against 6f64e5923bc8.

Label changes

Label justifications:

• P2: A concrete inbox-triage improvement now has personal-account observations, without evidence of broken existing functionality.

Evidence reviewed

What I checked:

• Current implementation gap: The sync dispatcher and persistence switch handle chat state, stars, deletions, and call records but not label events; tree searches found no label association storage or output. (internal/app/sync_events.go:109, 6f64e5923bc8)
• Storage and existing alternative: The schema contains no WhatsApp label definitions or memberships. docs/contacts.md explicitly describes contact tags as local metadata, so they do not satisfy the requested phone-synced taxonomy. (internal/store/schema.sql:51, 6f64e5923bc8)
• Existing upstream event transport: Startup already requests a full regular app-state fetch, and internal/wa/session.go enables EmitAppStateEventsOnFullSync. The direct whatsmeow imports and go.mod dependency establish the relevant dependency boundary; no additional startup fetch is evidently necessary. (internal/app/sync_recovery.go:132, 6f64e5923bc8)
• Personal-account observations: Feature request: read WhatsApp Lists / labels (chat and message associations) #394 (comment) reports an instrumented current-main sync with five definitions and fourteen chat association events matching the phone, including a removal and overlapping custom memberships. No message associations were observed; favorites and fresh relinking remain unverified. This is contributor-reported evidence, not an independently executed reproduction.
• Identity integration and related request: Chat rendering already resolves known LIDs and merges mapped duplicates, with focused tests. ResolveLIDToPN has no CLI surface: a consumer holding an unresolved @lid must read whatsmeow's whatsmeow_lid_map directly (v0.18.2) #420 requests a standalone identity lookup; it is adjacent work, not a replacement for Lists support. (cmd/wacli/chats.go:198, 6f64e5923bc8)
• Release and canonical checks: The published v0.18.2 chat documentation has no label filter or output contract. The open-item listing and bounded recent PR listing revealed no implementation candidate for Lists; search endpoints were unavailable, so this is not an exhaustive historical duplicate search. (docs/chats.md:11, cd4370388f03)

Likely related people:

• Myke Matos: Raw commit dfef73c adds internal/app/sync_recovery.go:132 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: dfef73cc0f72; files: internal/app/sync_recovery.go)
• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[giuseppebisemi]

I tested this on a personal (non-Business) account, which the review above lists as unverified.

I built main at 6f64e59 (same schema as v0.18.2) with one extra case in the sync event switch. It appends *events.LabelEdit, *events.LabelAssociationChat and *events.LabelAssociationMessage to an NDJSON file and changes nothing else. I ran sync --once on an account that has been linked for months, then checked the output against the phone app.

You don't need a new sync step. On startup syncAppStateDeltas already does a full sync of regular with EmitAppStateEventsOnFullSync, and every label event came through with FromFullSync: true:

• 5 LabelEdit. Three are predefined (type 1 UNREAD, 2 GROUPS, 3 FAVORITES), with localized names that start with U+200E. Two are CUSTOM (type 5) and carry orderIndex and color.
• 14 LabelAssociationChat, all on the two custom lists. They matched the app exactly, including chats that sit in both lists.
• 0 LabelAssociationMessage. The account has no labeled messages, so I couldn't test that path.

Four things came up that affect the schema:

1. One association arrived with labeled: false, for a chat I had removed from a list. The store has to keep the latest state for each (label_id, chat) pair and filter on labeled = 1. If it appends every event, that chat shows up in the list again.
2. 13 of the 14 chat JIDs were @lid and one was a @g.us group. To get chat names I had to map the LIDs through whatsmeow_lid_map to the phone-number JIDs that chats uses. It's the same gap as ResolveLIDToPN has no CLI surface: a consumer holding an unresolved @lid must read whatsmeow's whatsmeow_lid_map directly (v0.18.2) #420.
3. UNREAD and GROUPS arrive as definitions with no associations, since the app computes them. FAVORITES also had no associations, but my favorites list really is empty, so this run can't tell whether favorites travel as label associations or somewhere else.
4. The definitions and associations came in the same full sync. That makes "definition present, zero associations" a fair signal that a list is empty. I haven't checked what happens on a fresh relink.

I'd ship a read-only first version with CUSTOM list definitions and current chat memberships, which works on a personal account. Favorites, message labels and relink behavior still need someone to test them.