@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
Example 2 — Return with only @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
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.
