> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/faq/whatsapp-lid-lid.md). # WhatsApp LID (@lid) `@lid` is a unique identifier generated by WhatsApp to represent a contact **without directly exposing the phone number**. This is part of WhatsApp’s gradual move toward stronger privacy and reduced phone number visibility. In practice, WhatsApp may send `@lid` instead of a phone number in chats, messages, or contacts. This behavior is controlled entirely by WhatsApp and applies even if the user did not explicitly enable phone number hiding. Whapi.Cloud works with the identifiers exactly as WhatsApp provides them and automatically resolves `@lid` to a phone number whenever WhatsApp supplies enough data to do so. *** #### What Is a LID (`@lid`) and How It Appears in the API A **LID** is an internal WhatsApp identifier associated with a user or chat. Instead of a numeric phone number, it appears as a string ending with `@lid`, for example: ``` xxxxxxxxxxxxxxxx@lid ``` At the moment, Whapi.Cloud does not expose a separate `lid` or `chat_lid` field. You will see **either** a phone number **or** an `@lid` value in existing fields such as `chat_id`, message sender IDs, or contact identifiers. If `@lid` is present, it means WhatsApp sent the identifier in that format. *** #### WhatsApp Direction: Why LID Matters Long-Term WhatsApp is gradually moving toward a model where **phone numbers are no longer the primary visible identifier**, especially in contexts such as groups, communities, and Ads. This means: * phone numbers may be hidden more often, * `@lid` identifiers will appear more frequently. {% hint style="warning" %} Integrations must stop assuming that a phone number is always available. {% endhint %} Developers should already adapt their systems to work with `@lid` as a first-class identifier rather than treating it as an exception. *** #### How Whapi.Cloud Handles `@lid` When Whapi.Cloud receives an `@lid`, it attempts to resolve it automatically. Internally, the platform analyzes WhatsApp socket data associated with the event. If the phone number is present in the incoming technical payload, Whapi.Cloud replaces `@lid` with the phone number across all available fields. If the phone number is not available at that moment, Whapi.Cloud returns the `@lid` unchanged. We are increasingly encountering the following behavior after connecting a number to our API: * a chat or contact initially appears as `@lid`, * after a new incoming or outgoing message, the phone number becomes available, * Whapi.Cloud then replaces `@lid` with the resolved phone number. This behavior depends entirely on when WhatsApp provides the underlying data.\ \ This behavior is controlled by the channel's `data_mode` setting (`replace` / `original` / `extend`) — the description above is the default `replace` mode. See [WhatsApp Usernames and BSUID](https://support.whapi.cloud/help-desk/faq/whatsapp-usernames-and-bsuid) for the full `data_mode` reference with before/after examples for each mode. *** #### Working with `@lid` as a Full Identifier A LID is a **fully valid WhatsApp identifier**. You can: * send messages to `@lid` the same way as to a phone number, * receive messages from `@lid`, * handle group events, join requests, and membership updates involving `@lid`, * reject calls associated with `@lid`. Messages sent to a LID are delivered normally to the corresponding WhatsApp account. From an integration perspective, `@lid` should be treated exactly like a regular chat identifier. This makes it essential to **store and work with LID values**, not ignore or discard them. *** #### Phone Number ↔ LID Conversion **Converting `@lid` to a Phone Number** WhatsApp does not provide a public or official way to directly convert `@lid` to a phone number. This limitation exists by design and is tied to WhatsApp’s privacy model. Most providers do not offer any solution for this. Whapi.Cloud is actively developing an internal mechanism that can recognize phone numbers associated with LIDs when this information is technically available. {% hint style="success" %} ### Need to get a phone number from a LID? If WhatsApp returns a contact as `@lid`, but your CRM, ERP, or support system still requires a phone number, you can use the **Get ID by LID** method: ``` GET /contacts/ids/{ContactLID} ``` Example response: ```json { "id": "141555503672@s.whatsapp.net" } ``` This helps match LID-based WhatsApp conversations with existing customer records. Read the full guide: [Retrieve a Phone Number from a WhatsApp LID](https://support.whapi.cloud/help-desk/receiving/http-api/retrieve-phone-number-from-whatsapp-lid) {% endhint %} *** **Converting a Phone Number to `@lid`** Whapi.Cloud already provides endpoints that allow retrieving the LID for a given contact. **Get LID for a single contact** ``` GET https://gate.whapi.cloud/contacts/lids/{ContactID} ``` Documentation:\ **Get LIDs for multiple contacts** ``` GET https://gate.whapi.cloud/contacts/lids?ContactIDList=919984351847,61371989950 ``` Documentation:\ These endpoints allow you to build and store a **phone ↔ LID mapping** in your system. *** #### Recommendations for Integrations To ensure long-term stability: * treat all identifiers, * do not assume a phone number will always be present, * store both phone numbers and LIDs when available, * use LID as a stable identifier in chats, messages, and groups, * design systems that can work with `@lid` immediately, without waiting for phone number resolution. **WhatsApp is clearly moving toward LID-based identification.** Systems that adapt early will require fewer changes in the future. Whapi.Cloud already supports this via the `data_mode: extend` setting (beta), which returns the phone number and the LID/BSUID together in the same response. See [WhatsApp Usernames and BSUID](https://support.whapi.cloud/help-desk/faq/whatsapp-usernames-and-bsuid) for details.. *** #### Summary `@lid` is a WhatsApp privacy identifier and an intentional part of the platform’s evolution. It is not an error and not a temporary anomaly. Whapi.Cloud automatically resolves `@lid` to a phone number whenever possible, supports full interaction with LIDs, and provides tools to retrieve LIDs from phone numbers. Additional API features for explicit LID handling and conversion are actively being developed. Explicit dual-identifier support (phone + LID together) is already available via `data_mode: extend`.