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

The @lid (Linked ID) is a unique and 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 gradually, which means that:

• Not all users use @lid yet.

• 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

Today WhatsApp can return the contact identifier in different ways:

📌 phone

May contain:

• The contact's real number → "554499999999"

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

That is: phone is no longer a guarantee of a phone number.

---

📌 chatLid

Is the contact's most stable unique identifier. However, it may come as:

• A valid @lid

• Or null

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

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

---

Webhook examples

Depending on the account, privacy settings 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 replicates exactly what WhatsApp sends.

---

Sending messages using the @lid

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

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

---

Implementation best practices

To avoid inconsistencies, we recommend:

1. Prioritize the use of @lid

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

2. Do not rely solely 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 internal mapping between:

• chatLid

• phone (when real number)

• @lid

This way your customer service logic, automations and CRM remain consistent.

---

Conversion between number and @lid

❌ Convert @lid → number

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:

• If the number exists on WhatsApp

• And returns the corresponding @lid, when available

This is the official way to obtain the identifier.

---

Important points

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

• Behavior can 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.