How to resolve @lid (Linked ID) to actual phone number?

[malikyousef]

I'm receiving messages where the sender ID comes in @lid format (e.g., 31142858252478@lid) instead of the standard @c.us phone number format.

Environment:

WAHA version: [your version]
WhatsApp account type: Business / Personal
Issue: When certain contacts send messages, the from field returns an internal Linked ID like 31142858252478@lid rather than their actual phone number (31xxxxxxxxx@c.us).

Questions:

Is there an API endpoint to resolve @lid identifiers to actual phone numbers?
Does GET /api/contacts?contactId=31142858252478@lid work for resolving these IDs?
Is this behavior related to WhatsApp's privacy settings or specific contact types?
Are there any webhook events or settings that would return the resolved phone number instead?
What I've tried:

Using /api/contacts endpoint with the @lid identifier
Checking the message payload for alternative phone fields
Any guidance on handling @lid identifiers would be appreciated!

[DevIgorSantos]

Hi! The @lid in WhatsApp is a unique identifier to replace the unique use of the phone number (JID) in contact identification. I had the same problem, but I managed to solve it with the following endpoint:

curl -X 'GET' \
'{yourBaseUrl}/api/{session}/lids/{lid}' \
-H 'accept: application/json' \
-H 'X-Api-Key: {yourXApiKey}'

[truegreatvoid]

Oi Igor, tu já teve o problema desse endpoint retornar o "np" vazio? Se sim, nesse caso tu deixou como @lid ou encontrou outra forma de tratar isso?

[danewellxp-glitch]

Fala Truegreatvoid. Sim, já tive isso.
Às vezes o /api/contacts devolve o campo do número (aqui a gente usa number; se aí for np, é o mesmo conceito) vazio.
A gente não deixa como @lid na interface. O que fizemos:
Resolução em camadas
Primeiro tentamos o number (ou np) da resposta do /api/contacts. Se vier vazio, usamos o campo id da resposta quando ele já vier no formato @c.us.
Se ainda não tiver nada, fazemos um fallback no banco: buscamos um Customer que tenha aquele waha_chat_id (o @lid) e usamos o phone dele.
Só se tudo isso falhar é que mantemos o @lid (e logamos um warning).
Cache
Quando conseguimos resolver (por qualquer um desses caminhos), guardamos em memória e no Redis (TTL 24h), então não ficamos chamando o endpoint à toa e não dependemos do np/number vindo preenchido toda vez.
Para mostrar o número real na UI
No webhook, antes de salvar conversa/mensagem, chamamos esse resolve_lid(chat_id). O que a gente persiste e exibe é sempre o número resolvido (ou o @lid só quando realmente não deu pra resolver). Ou seja: na listagem de chats e em qualquer lugar que mostre “cliente”, usamos esse valor já resolvido, não o @lid cru.
Se quiser, posso te mandar o trecho do resolve_lid e dos fallbacks (contacts + DB) ou um exemplo de onde a gente chama isso no webhook.

[github-actions[bot]]

English

---

Hi Igor, have you ever had the problem with this endpoint returning the empty "np"? If so, in that case did you leave it as @lid or did you find another way to handle it?

[github-actions[bot]]

English

---

This is Truegreatvoid. Yes, I've had that.
Sometimes /api/contacts returns the number field (here we use number; if it's np, it's the same concept) empty.
We don't leave it as @lid in the interface. What we did:
Layered resolution
First we try the number (or np) of the /api/contacts response. If it comes empty, we use the response id field when it already comes in the @c.us format.
If there is still nothing, we do a fallback in the database: we look for a Customer who has that waha_chat_id (the @lid) and use his phone number.
Only if all else fails do we keep @lid (and log a warning).
Cache
When we manage to resolve it (through any of these paths), we save it in memory and in Redis (TTL 24h), so we don't keep calling the endpoint for nothing and we don't depend on np/number being filled in every time.
To show the actual number in the UI
In webhook, before saving conversation/message, we call this resolve_lid(chat_id). What we persist and display is always the resolved number (or @lid only when it really couldn't be resolved). In other words: in the chat listing and anywhere that shows “customer”, we use this already resolved value, not the raw @lid.
If you want, I can send you the snippet of the resolve_lid and the fallbacks (contacts + DB) or an example of where we call this in the webhook.