Map a WhatsApp LID to a Phone Number
Before you message anyone, you need to know the number is on WhatsApp and what its identifier is. The official API answers neither question. These endpoints do, and they are the ones to pace most carefully.
Can the official WhatsApp Cloud API do this?
Not applicable. The official API never shows you a LID.
Read the full comparisonHow it works
Resolve the identities you already know, resolve the ones that arrive in events, and design for the case where no phone number comes back.
Look up the LID for a number you know
Given a phone number, fetch the linked identity it maps to. Doing this for your own known contacts up front means later group events resolve from cache instead of needing a lookup each time.
API reference for this stepResolve a LID that arrived in an event
Group and channel events increasingly carry a linked identity instead of a number. Resolve it once, store both, and key your own records on the linked identity because that is the value that will keep arriving.
API reference for this stepHandle the case where it cannot be resolved
Sometimes there is no mapping to be had, and the event arrives with a null phone number. Design for that: a participant you can address and count but cannot match to a CRM row is still a participant.
curl --request GET \
--url 'https://api.wapito.com/v1/contacts/+15551234567/lid' \
--header 'Authorization: Bearer wpt_YOUR_TOKEN'Endpoints
Webhook events
groups.participantsGroup membership or role changedonGroupsParticipants()messagesMessage sent or receivedonMessages()
What you can build with it
- Match group members to CRM records
A membership organisation resolves the linked identity of each group participant once and stores both values, so a message from a member is attributed to the right record even when the event carries no phone number at all.
- Keep attribution working after a migration
A support desk that used to key threads on phone numbers re-keys them on linked identity, resolving the numbers it already knows in a single backfill. Nothing breaks as more of the network starts sending identities instead of numbers.
- Deduplicate a contact list
An agency discovers that the same person appears twice in its database under two numbers by resolving both to the same linked identity, then merges the records rather than messaging the same human twice.
What the official WhatsApp Cloud API does here
Meta's official WhatsApp Cloud API is built for business messaging: templates, customer-service windows and per-conversation pricing. A large part of what WhatsApp itself can do — groups, channels, status, presence, contact lookups — has no endpoint there at all, which is why so many teams end up looking past it. Everything below is checked against Meta's own published reference, with the link and the date we checked it.
Restricted on the Cloud API
Not applicable. The official API never shows you a LID.
Meta's Cloud API hands a business an identifier for the customer in a conversation it already manages, so the mapping problem does not arise there - but neither does the capability. There is no official endpoint that takes a linked identity and returns a phone number, because the official platform never exposes linked identities in the first place.
Paraphrase (not a verbatim quote), checked against the Cloud API messages reference: recipients are addressed by phone number and the platform returns its own identifier for a customer; no linked-identity resolution endpoint appears in the reference.
The official workaround
There is nothing to work around, because the official platform has no groups or channels where a linked identity would appear. The trade is that it also cannot see those conversations at all.
Wapito is an independent product. It is not affiliated with, endorsed by, sponsored by or certified by WhatsApp or Meta Platforms, Inc. WhatsApp is a trademark of Meta Platforms, Inc.
Gotchas
- A linked identity is not a phone number and cannot be messaged as one in every context. Keep the two fields separate in your schema rather than overloading one column.
- Resolution can fail and return nothing, particularly for people the linked number has never interacted with. Treat a null phone number as a normal outcome rather than an error to retry.
Tutorials by language
Frequently asked questions
Why did WhatsApp introduce linked identities?
To stop group and channel participation from exposing everybody's phone number to everybody else. It is a privacy improvement for users, and a real migration cost for anyone whose automation assumed the sender of a group message is always a number they can look up.
Is a LID stable over time?
It is stable for a given account, which is what makes it useful as a key. Treat it the way you would treat any external identifier: store it, index on it, and do not try to parse meaning out of it. If the account itself goes away, so does the identity.
Can I message someone using only their LID?
In contexts where the identity is the participant - inside a group, for instance - yes. Starting a fresh one-to-one conversation from an identity alone is not something to rely on, so resolve to a phone number when you need to open a new thread, and expect that to sometimes be impossible.
What if the mapping simply is not available?
Then the event arrives with the identity and a null phone number, and that is the honest answer rather than a bug. Your system should be able to count, address and reply to that participant inside the conversation without ever knowing their number, because increasingly that is the normal case.
Related
Related features
Glossary
Try it on your own number
Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.