Mastering Relationships: Contacts Management

In the WhatsApp Protocol, a "Contact" is more than just a phone number. It is a cryptographic identity with privacy settings, profile metadata, and a persistent session state. The Contacts API gives you the tools to manage these relationships programmatically.

🆔 The Anatomy of an Identity

To work with WhatsApp, you must understand the two types of IDs.

1. JID (Jabber ID) - The Standard

This is possibly the most important concept in the entire API.

• Format: [country_code][phone_number]@c.us
• Example: 15551234567@c.us
• Usage: Used for 99% of operations (sending messages, checking presence, blocking).
• Persistence: If a user changes their phone number, their JID changes.

2. LID (Lookup ID) - The Future

Introduced recently by Meta to support username-based privacy.

• Format: [random_integer]@lid
• Example: 123456789012345@lid
• Usage: Currently required only for specific advanced features (like hidden group members).
• Persistence: If a user changes their phone number, their LID stays the same. This allows for long-term tracking of a user identity across phone number swaps.

📖 The "Address Book" Philosophy

WhatsApp interacts with two distinct lists of people:

A. The "Saved" List (True Contacts)

These are people whose numbers you have explicitly saved in your phone's address book (or pushed via API).

• Privilege: They can see your Profile Picture and Status (if your privacy is set to "My Contacts").
• Route: /v2/contacts/all

B. The "Interaction" List

These are people who have messaged you, but you haven't saved them.

• Visual: In the app, they appear as just a phone number (no name).
• Privilege: Restricted. They might not see your bio or photo.

Best Practice: For a business bot, you rarely need to "Save" contacts. You mostly interact with incoming JIDs dynamically. Saving is only necessary if you want to bypass a user's "My Contacts Only" privacy filter to show them your profile photo.

🔍 Discovery & Verification

One of the most powerful features is Existence Checking.

The "Is this a WhatsApp number?" Problem

Marketing databases are full of landlines and dead numbers. Sending messages to them will lower your quality score.

• Solution: Use /v2/contacts/check-exists.
• Logic:
  1. Input: +1 (555) 000-0000
  2. API Action: Pings WhatsApp Directory Server.
  3. Result: true (It's a valid WhatsApp account) or false.
• Cost: This operation is rate-limited. Checking 10,000 numbers in an hour looks like "Scraping" and will trigger a ban.
• Strategy: Check numbers lazily (just before sending the first message), not in bulk.

🛡️ Privacy & Blocking

The Blocklist

Blocking is a functional tool, not just an emotional one.

• Spam Defense: If a user spams your bot with "hi hi hi hi", automatically call /v2/contacts/block.
• Opt-Out Compliance: If a user types "STOP", you must stop messaging them. Blocking them ensures your system physically cannot message them again, providing a fail-safe against logic bugs.

Profile Visibility

When you fetch contact info (/v2/contacts/[id]), you might see profilePic: null or about: null.

• This is not a bug.
• It means the user has set their privacy to "Nobody" or "My Contacts" (and they haven't saved your bot).
• Respect: Do not attempt to bypass this. If the data is hidden, it is private.

🔮 Strategic Workflows

Workflow A: The "CRM Sync"

Keep your Salesforce/HubSpot database up to date.

1. Trigger: User messages your bot.
2. Action: Call /v2/contacts/[id].
3. Data: Extract their pushName (the name they set for themselves) and profilePicUrl.
4. Save: Update your CRM card with their real face and name.
5. Benefit: Your support agents feel like they are talking to a real person, not a number.

Workflow B: The "Number Migration" Handler

1. Event: You know a user by their JID 123@c.us.
2. Action: Store their LID 999@lid alongside it.
3. Future: User changes number to 456@c.us.
4. Recovery: If they message you again, verify the LID. If 999@lid matches, you know it's the same person. Merge the chat history.

⚠️ Limits & Quotas

• 15MB: The maximum size of valid contact photos you can download.
• Sync Frequency: WhatsApp syncs contacts periodically. If you add a contact on your phone, it might take ~30 seconds to show up in the /v2/contacts/all API response.
• Legacy Groups: Some very old groups use LIDs as participant IDs. Modern integration should always prefer JIDs unless explicitly stated otherwise.