The username, with or without the leading @
Optionalkey: string
The 4 digit numeric PIN, for PIN-protected usernames
// Basic lookup, with or without the @ prefix
const result = await WPP.contact.queryUsernameExists('@someusername');
if (!result) {
// Username does not exist
} else if ('keyRequired' in result) {
// Username is PIN-protected — prompt the user for the PIN
} else {
console.log(result.wid); // The contact's LID, store this
}
// With PIN
const result = await WPP.contact.queryUsernameExists('someusername', '1234');
Check if a WhatsApp username (@username) exists
A leading
@is optional and stripped before querying. The username is validated locally first, using the same rules as WhatsApp Web, and throws InvalidUsername when malformed — WhatsApp reports a malformed username and an unknown one identically, so validating up front keeps the two distinguishable and avoids a pointless round trip.Some accounts protect their username with a 4 digit PIN. When the account has PIN protection enabled, this function returns
{ keyRequired: true }instead of contact info. Pass the PIN askeyto unlock the result.The returned
widis the contact's LID. Usernames are mutable and the LID is not, so resolve once and store the LID: use it for every later operation instead of looking the username up again.