@lid on WhatsApp – What it is, how it works, and how to handle it in SprintHub

The @lid (Linked ID) is a unique, private identifier created by WhatsApp to represent users without exposing the phone number. This change is part of Meta's privacy updates and is being applied in a gradual, which means that:

• Not all users use @lid yet.

• The behavior may vary between chats, groups, and devices.

• Even if the user has not hidden the number, WhatsApp may send only the @lid.

Therefore, it is essential to adapt integrations — including SprintHub's — to handle this transition.

---

Difference between @lid and phone

WhatsApp can now return the contact identifier in different ways:

📌 phone

May contain:

• The contact's actual number → "554499999999"

• Or the @lid itself → "999999999999999@lid"

In other words: phone is no longer a guarantee of a phone number.

---

📌 chatLid

It is the contact's most stable unique identifier. However, it can come as:

• A valid @lid

• Or null

When the chatLid comes as null, the field phone can return only the @lid.

➡️ The behavior is defined exclusively by WhatsApp — and may change at any time.

---

Webhook examples

Depending on the account, privacy, and context, WhatsApp may send different identifiers.

Example 1 — Full return with number and @lid

{
  "chatLid": "999999999999999@lid",
  "phone": "554499999999"
}

Example 2 — Return with only @lid

{
  "chatLid": null,
  "phone": "65998849469@lid"
}

This behavior occurs when WhatsApp hides the number and provides only the @lid identifier.

SprintHub/Z-API only exactly replicates what WhatsApp sends.

---

Sending messages using @lid

{
  "phone": "999999999999999@lid",
  "message": "Hello! This message was sent using the @lid identifier."
}

Even without the real number, WhatsApp delivers the message normally.

---

Best implementation practices

To avoid inconsistencies, we recommend:

1. Prioritize using @lid

It is more stable and tends to be the definitive identifier chosen by WhatsApp.

2. Don't rely only on phone

This field may contain:

• Real number

• @lid

• Mixed formats

3. Always store the @lid in your database

Treat the @lid as a permanent identifier.

4. Keep an internal mapping between:

• chatLid

• phone (when real number)

• @lid

This keeps your support, automation, and CRM logic consistent.

---

Conversion between number and @lid

❌ Convert @lid → number

It's not possible. No API, not even WhatsApp's internal one, provides this information.

This exists for privacy reasons.

---

✔️ Convert number → @lid

This is possible using the Z-API endpoint “Number with WhatsApp?”, which checks:

• Whether the number exists on WhatsApp

• And returns the corresponding @lid, when available

This is the official way to obtain the identifier.

---

Important points

• The @lid is a native WhatsApp, not SprintHub's or Z-API's.

• The behavior may change at any time, without prior notice.

• The attribute chatLid is already implemented in webhooks and can be used for sending.

• The change is being applied gradually, so results may be inconsistent across users, groups, and environments.