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.contact module exposes WhatsApp Web’s internal contact store. Every function operates on a WhatsApp ID (WID) — a string in the format {phone}@c.us for individual contacts, {id}@lid for linked-device identifiers, or {id}@g.us for group IDs. All async functions return a Promise and should be awaited in the browser console or your injection script.
All contact IDs must include the full international phone number without the + prefix, followed by @c.us. For example, a US number +1 555 000 1234 becomes 15550001234@c.us.

​
WPP.contact.get(contactId)

Returns the internal ContactModel for a given WID, or undefined if the contact is not found in the local store. 
get(contactId: string | Wid): Promise<ContactModel | undefined>
​
contactId
string | Wid
required
The WhatsApp ID of the contact. Accepts @c.us, @lid, or @g.us formats.
const contact = await WPP.contact.get('15550001234@c.us');
console.log(contact?.name, contact?.pushname);

// LID format (multi-device)
const contact2 = await WPP.contact.get('123456789@lid');

// Group contact
const groupContact = await WPP.contact.get('120363000000000001@g.us');

​
WPP.contact.list(options?)

Returns an array of all ContactModel objects currently in the local store, with optional filters. 
list(options?: ContactListOptions): Promise<ContactModel[]>
​
options
ContactListOptions
Optional filtering options.
// All contacts
const all = await WPP.contact.list();

// Only saved contacts
const mine = await WPP.contact.list({ onlyMyContacts: true });

// By label name or ID
const labelled = await WPP.contact.list({ withLabels: ['VIP', '3'] });

​
WPP.contact.getStatus(contactId)

Fetches the “About” text (status) set by the contact. Returns null if the contact does not exist or has no status. 
getStatus(contactId: string | Wid): Promise<string | null>
​
contactId
string | Wid
required
The WhatsApp ID of the contact (@c.us format).
const status = await WPP.contact.getStatus('15550001234@c.us');
if (status) {
  console.log('About text:', status);
}

​
WPP.contact.getProfilePictureUrl(contactId, full?)

Returns the URL of the contact’s profile picture. Returns undefined if the contact has no profile picture or if privacy settings prevent access. 
getProfilePictureUrl(contactId: string | Wid, full?: boolean): Promise<string | undefined>
​
contactId
string | Wid
required
The WhatsApp ID of the contact.
​
full
boolean
default:"true"
When true (default), returns the full-resolution image URL. When false, returns the thumbnail URL.
// Full-resolution picture
const url = await WPP.contact.getProfilePictureUrl('15550001234@c.us');
console.log(url);

// Thumbnail only
const thumb = await WPP.contact.getProfilePictureUrl('15550001234@c.us', false);

​
WPP.contact.getBusinessProfile(contactId)

Returns the business profile for a WhatsApp Business account, including verified name, category, and description. 
getBusinessProfile(contactId: string | Wid): Promise<BusinessProfileModel>
​
contactId
string | Wid
required
The WhatsApp ID of the business contact (@c.us format).
const profile = await WPP.contact.getBusinessProfile('15550001234@c.us');
console.log(profile);

​
WPP.contact.getCommonGroups(contactId)

Returns the WIDs of all groups that you and the given contact share. 
getCommonGroups(wid: Wid | string): Promise<Wid[]>
​
wid
string | Wid
required
The WhatsApp ID of the contact (@c.us format).
const groups = await WPP.contact.getCommonGroups('15550001234@c.us');
for (const groupId of groups) {
  console.log('Shared group:', groupId.toString());
}

​
WPP.contact.getPnLidEntry(contactId)

Resolves the mapping between a phone number (@c.us) and its linked-device identifier (@lid), plus any available contact metadata. Only works for @c.us and @lid WIDs — not groups. 
getPnLidEntry(contactId: string | Wid): Promise<PnLidEntryResult>
​
contactId
string | Wid
required
A @c.us or @lid WID to look up.
​
PnLidEntryResult
object
// Resolve by phone number
const entry = await WPP.contact.getPnLidEntry('15550001234@c.us');
console.log('LID:', entry.lid?._serialized);
console.log('Phone:', entry.phoneNumber?._serialized);
console.log('Name:', entry.contact?.name);

// Resolve by LID
const entry2 = await WPP.contact.getPnLidEntry('123456789@lid');
When calling with a @c.us WID and the LID is not cached locally, this function queries the WhatsApp server to retrieve it.

​
WPP.contact.queryWidExists(contactId)

Checks whether a given WID (phone number or LID) is registered on WhatsApp. Results are cached — 5 minutes for hits, 15 seconds for misses. 
queryWidExists(contactId: string | Wid): Promise<QueryWidExistsResult | null>
​
contactId
string | Wid
required
The WID to look up. Accepts @c.us or @lid.
​
QueryWidExistsResult
object
const result = await WPP.contact.queryWidExists('15550001234@c.us');
if (result) {
  console.log('Registered WID:', result.wid.toString());
  console.log('Is business:', result.biz);
} else {
  console.log('Number is not registered on WhatsApp');
}
This is the recommended way to validate a phone number before sending a message or adding to a group. It correctly handles Brazilian 9-digit number variations.

​
WPP.contact.queryUsernameExists(username, key?)

Checks whether a WhatsApp username (@username) exists. Some accounts protect their username with a PIN — in that case the function returns { keyRequired: true } instead of contact info. 
queryUsernameExists(
  username: string,
  key?: string
): Promise<QueryUsernameExistsResult | QueryUsernameExistsKeyRequired | null>
​
username
string
required
The username to look up, without the @ prefix.
​
key
string
Numeric PIN to unlock a PIN-protected username.
// Basic username lookup
const result = await WPP.contact.queryUsernameExists('someusername');
if (result && 'keyRequired' in result) {
  // Username is PIN-protected — prompt the user for the PIN
  const unlocked = await WPP.contact.queryUsernameExists('someusername', '1234');
} else if (result) {
  console.log('WID:', result.wid.toString());
}

​
WPP.contact.save(contactId, firstName, options?)

Creates a new contact or updates an existing one in the device address book. 
save(
  contactId: string | Wid,
  firstName: string,
  options?: {
    lastName?: string;
    syncAddressBook?: boolean;
  }
): Promise<ContactModel | undefined>
​
contactId
string | Wid
required
The @c.us WID of the contact to save.
​
firstName
string
required
The contact’s first name.
​
options
object
// Create a new contact
await WPP.contact.save('15550001234@c.us', 'Jane', {
  lastName: 'Doe',
  syncAddressBook: true,
});

​
WPP.contact.remove(contactId)

Removes a contact from the device address book. Throws if the contact is not found or is not in your contact list. 
remove(contactId: string | Wid): Promise<ContactModel | undefined>
​
contactId
string | Wid
required
The @c.us or @lid WID of the contact to remove.
await WPP.contact.remove('15550001234@c.us');
This only removes the contact from your address book. It does not block the contact or delete chat history.

​
WPP.contact.reportContact(contactId, spamFlow?, msg?)

Reports a contact or chat to WhatsApp for spam or policy violations. 
reportContact(
  contactId: string | Wid,
  spamFlow?: string,
  msg?: MsgModel
): Promise<ReportContactResult>
​
contactId
string | Wid
required
The WID of the contact to report.
​
spamFlow
string
default:"ChatInfoReport"
The report context. Available values:
ValueDescription
ChatInfoReportReport from chat info screen (default)
MessageMenuReport from a specific message
GroupInfoReportReport from group info screen
ChatFmxCardSafetyToolsReportReport via safety tools
ChatFmxCardSafetyToolsReportSuspiciousReport a suspicious contact
GroupInfoLeaveReportUpsellReport when leaving a group
​
msg
MsgModel
A specific message to include in the report. Requires spamFlow: 'MessageMenu'.
​
ReportContactResult
object
// Basic report
const result = await WPP.contact.reportContact('15550001234@c.us');
console.log('Report ID:', result.reportId);

// Report as suspicious
await WPP.contact.reportContact('15550001234@c.us', 'ChatFmxCardSafetyToolsReportSuspicious');

​
WPP.contact.subscribePresence(ids)

Subscribes to presence updates (online/offline/typing) for one or more contacts or groups. 
subscribePresence(ids: string | string[]): Promise<Wid[]>
​
ids
string | string[]
required
A single WID or an array of WIDs to subscribe to. Accepts @c.us and @g.us.
Returns an array of WIDs for which presence was successfully subscribed. 
// Single contact
await WPP.contact.subscribePresence('15550001234@c.us');

// Multiple contacts at once
const subscribed = await WPP.contact.subscribePresence([
  '15550001234@c.us',
  '15550005678@c.us',
]);

​
WPP.contact.unsubscribePresence(ids)

Stops receiving presence updates for one or more contacts. 
unsubscribePresence(ids: string | string[]): Promise<Wid[]>
​
ids
string | string[]
required
A single WID or an array of WIDs to unsubscribe.
await WPP.contact.unsubscribePresence('15550001234@c.us');

​
WhatsApp ID format reference

Every function in this module accepts a WhatsApp ID (WID) string. The table below summarises the common formats.
Format: {e164_number}@c.us — the phone number in E.164 format without the +, followed by @c.us.
15550001234@c.us   ← US number +1 555 000 1234
447911123456@c.us  ← UK number +44 7911 123456
5511999999999@c.us ← Brazil number +55 11 999999999
Format: {numeric_id}@lid — an internal WhatsApp identifier used in multi-device sessions. Use getPnLidEntry to translate between @c.us and @lid.
Format: {timestamp}-{random}@g.us. Accepted by get, getCommonGroups, and subscribePresence.

Build docs developers (and LLMs) love

Get started for freeTalk to us