Skip to main content

Profile

client.profile (WaProfileCoordinator) reads and writes profile fields for your account and looks them up for others.

Profile picture

getProfilePicture(jid, type?, existingId?) returns a WaProfilePictureResult{ url?, directPath?, id?, type? }. The second argument picks between the compact 'preview' variant (default) and the high-resolution 'image' original; both flavors are returned as the same envelope, only the bytes behind url / directPath differ. Pass the cached existingId to let the server short-circuit when the picture hasn’t changed (the result then comes back without the new url/directPath).

About / status text

Push name

pushName is the display name peers see for your account in chats and group participant lists. The change is applied to the local credentials immediately (so client.getCredentials()?.pushName reflects the new value right away) and is routed through an app-state mutation; peers see the new name on your next outgoing message.
Passing an empty string resets the name to the device fingerprint default.

Default disappearing mode

setDisappearingMode sets the account-wide default lifetime applied to new 1:1 chats you start. Existing chats keep their per-chat setting.
For per-group disappearing messages, see Groups → disappearing messages.

Batched lookups

Check if a number is on WhatsApp

Resolve phone numbers to their LID and learn whether each is registered on WhatsApp:

Usernames

setUsername, setUsernameKey, and resolveUsername all run the same local rules that WhatsApp applies (length, allowed characters, 4-digit key shape) and throw on failure before hitting the network — a call that returns without throwing has passed local validation, so setUsername returning false narrows the cause to a server-side outcome (taken, rate-limited). Resolve a handle to its LID with resolveUsername. The result is a discriminated union: 'found' gives you the JID (plus isBusiness / pnJid when applicable), 'key-required' means the server withheld the JID until you supply the 4-digit lookup key, and 'not-found' is terminal.

Privacy

client.privacy (WaPrivacyCoordinator) controls privacy categories and the blocklist.

Privacy settings

Setting names live on WA_PRIVACY_SETTING_TO_CATEGORY, allowed values per setting on WA_PRIVACY_SETTING_VALUES — every setting takes only the values WhatsApp Web accepts for it. The full list: lastSeen, online, profilePicture, about, readReceipts, groupAdd, callAdd, messages, defenseMode, linkedProfiles, pix.
  • linkedProfiles controls who can see the Accounts Center profiles linked to this account. Takes the same visibility values as lastSeen / profilePicture ('all' | 'contacts' | 'contact_blacklist' | 'none'), deny-list included.
  • pix controls who can see the Pix key on the profile (Brazil-only payments surface). Same visibility values as lastSeen.
setPrivacySetting returns the dhash the server echoes back — the version stamp of that category’s disallowed list, present only while the category sits on 'contact_blacklist' (null otherwise). Setting a category to 'contact_blacklist' here only flips the mode; populate the list with setDisallowedList.

Blocklist

WaBlocklistResult now carries entries: readonly WaPrivacyListEntry[] alongside jids — same membership, with a per-entry username?: string handle set only when the server identified the entry that way. block / unblock writes can address a migrated contact by username or display_name (the entry resolves through the same identifier lookup), instead of falling back to unknown_identifier.

Disallowed lists

For settings scoped to a specific list of contacts (e.g. “share with everyone except…”):
setDisallowedList(category, input) carries the mode change and the entries in one stanza (the server has no separate deny-list endpoint). Inputs accept phone jids, LID jids, or bare phone numbers and are resolved to both addressing forms, the same way blockUser does. A migrated contact may be addressed by username or display_name (via the entry’s own identifier resolution) rather than falling back to unknown_identifier. The write is versioned by a dhash read right before sending; if another device mutated the list in between, the server answers 409 and the call refetches the stamp and retries once. The eligible categories are exposed as WA_PRIVACY_DISALLOWED_LIST_CATEGORIES (about, groupAdd, lastSeen, profilePicture, linkedProfiles, pix). WaPrivacyDisallowedListResult mirrors WaBlocklistResult: entries: readonly WaPrivacyListEntry[] accompanies jids with the same membership, adding a per-entry username?: string when the server identified the entry that way.

Reacting to changes on other devices

A privacy change made on the primary (or another companion) surfaces on the privacy event with the full refreshed category set plus any disallowed list the server reported changed. The values come from a fresh read — never from the notification payload — and a burst of changes on the phone collapses into a single event, debounced 1s.
Call client.privacy.refreshFromAccountSync() to force a refresh yourself — the result is both returned and re-emitted as the privacy event, so the client’s view stays consistent regardless of who triggered it. Concurrent calls are deduplicated.

Business

client.business (WaBusinessCoordinator) reads business profiles and verified names, and manages your own business profile. Business account — required to edit your own profile or cover photo; the read methods work for any account.

Typed business hours

WaBusinessHoursDay and WaBusinessHoursMode are union aliases ('sun' | 'mon' | …, 'open_24h' | 'specific_hours' | 'appointment_only'). The values are also frozen on WA_BUSINESS_HOURS_DAYS and WA_BUSINESS_HOURS_MODES. Passing an unknown mode to editBusinessProfile now throws a clear local error instead of the server replying with 406 not-acceptable — closed days are still expressed by omitting them from config, not by a dedicated mode.

Chat settings

Per-chat settings — mute, pin, archive, read, lock, star, clear, delete — live on client.chat and sync across your devices. They have their own guide:

Managing chats

Mute, pin, archive, mark read, lock, star messages, clear, and delete chats.
Last modified on August 19, 2026