Get All Contacts

Digging for Gold: Retrieving Your Address Book

The /v2/contacts/all endpoint is the heavy lifter of the Contacts API. It downloads, filters, and paginates the entire list of entities your WhatsApp account knows about.

🏗️ What is "All"?

When you ask for "All Contacts", WhatsApp doesn't just return your saved address book. It returns a mix of:

1. Saved Contacts: People in your phone's address book (with names).
2. Unsaved Interactions: People who messaged you, but you never saved properly.
3. Business Identities: Official Business Accounts (OBAs) you have interacted with.
4. Legacy Groups: Occasionally, old group metadata might appear here (though usually filtered).

The ID Mix

You will see two types of IDs in the response:

• @c.us (Standard): 123456789@c.us. This is a normal phone number.
• @lid (Lookup ID): 123456789@lid. This is a privacy-preserving identifier used by some modern WhatsApp features.
  • Advice: If you see an @lid, store it alongside the @c.us if possible, but your UI should primarily index on the phone number (@c.us) for human readability.

⚡ Pagination & Performance

If your bot has been running for 5 years, this list could contain 50,000 entries.

• Default Limit: The API defaults to returning a manageable chunk (e.g., 50 or 100).
• Max Limit: You can request up to 1000 contacts per call, but this increases latency.

The Pagination Loop

To fetch everything, use a while loop:

let allContacts = [];
let offset = 0;
while (true) {
    const batch = await api.getContacts({ limit: 1000, offset: offset });
    if (batch.length === 0) break;
    allContacts.push(...batch);
    offset += 1000;
}

🔍 Filtering & Sorting

The API provides server-side utilities to help you find what you need without downloading the whole world.

Sorting

• ByName: sortBy=name. Helpful for building an A-Z contact picker UI.
• ByPushName: sortBy=pushname. Useful if your address book is empty and you rely on user-set names.

Filtering (Implicit)

Currently, the API returns valid contacts. It automatically filters out invalid JIDs or malformed entries that might exist in the raw database, ensuring you get a clean list.

🛡️ Best Practices

1. Don't Poll This

• Bad: Calling /v2/contacts/all every 5 minutes "just in case".
• Why: It's an expensive database scan.
• Good: Call it once on startup to hydrate your cache. Then, listen for message.upsert and contact.update events to incrementally update your local state.

2. Matching Names

• Scenario: You have a number +12345.
• Goal: Find the name.
• Method: Do not call /v2/contacts/all and search the array. That's O(N).
• Method: Call /v2/contacts/+12345@c.us directly. That's O(1). Use the list endpoint only for "Directory" views.

3. Privacy Respect

• Data Minimization: If you are building a dashboard for your agents, do not display the raw @lid or internal IDs. Show name || pushname || number.
• Staleness: Be aware that pushname changes. A user might change their name from "John" to "Crypto King" overnight. Your local cache will be outdated until you refresh.

❓ FAQ

Q: Why are some names null? A: name is the Address Book Name. If you haven't saved the number in Google/Apple Contacts (or the bot's virtual address book), name is null. pushname is what the user calls themselves.

Q: Can I add a contact via this API? A: No. This is a read-only view. To "add" a contact, you technically just need to message them. To "save" them with a name, you would need to interact with the host OS's address book, which this API assumes is managed externally or virtually.

Q: I see duplicates! A: You might get the same human returned as both @c.us and @lid. This is rare in the list view (we try to merge them), but if it happens, treat the @c.us as the master record.