LID en WhatsApp: qué es, cómo funciona y qué cambia en las integraciones con Z-API

Durante mucho tiempo, el número de teléfono fue considerado la principal identidad de un contacto en WhatsApp. Para localizar una conversación, registrar un cliente, crear un ticket o enviar un mensaje, bastaba con almacenar una secuencia numérica como 5511999999999.

Este modelo está cambiando. En determinadas situaciones, WhatsApp puede devolver un identificador con el formato @lid en lugar de exponer directamente el número de teléfono. Para quienes utilizan APIs, webhooks, CRMs o automatizaciones, este cambio exige revisar la forma en que los contactos se almacenan, consultan y utilizan para enviar mensajes.

LID, sigla asociada a Local Identifier, es un identificador privado utilizado para representar a un usuario sin revelar necesariamente su número de teléfono real. Permite que la integración siga reconociendo al contacto y enviando mensajes, al mismo tiempo que reduce la exposición del número en payloads, logs y bases de datos técnicas.

Esto no significa que el número de teléfono haya dejado de existir ni que todos los flujos funcionen ahora exclusivamente con LID. El teléfono todavía puede aparecer en determinados eventos y seguir siendo necesario para procesos específicos. El principal cambio es que ya no debe tratarse como la única clave posible.

En este artículo aprenderás:

• qué es LID y por qué WhatsApp utiliza este identificador;
• la diferencia entre phone, lid, @lid y chatLid;
• cómo interpretar las respuestas de los webhooks;
• cómo enviar mensajes utilizando un LID;
• cuándo utilizar LID y cuándo utilizar el teléfono;
• cómo adaptar el CRM, la base de datos y las automatizaciones;
• por qué chatLid: null puede ser una respuesta normal;
• qué conversiones son posibles o limitadas;
• cómo Z-API ayuda a mantener la integración estable.

¿Qué es LID en WhatsApp?

LID es un identificador asociado al usuario dentro de una determinada interacción de WhatsApp. Funciona como una referencia técnica que permite que los sistemas reconozcan al contacto sin depender de la exposición de su número de teléfono.

Una respuesta puede contener un valor como:

5511999999999

O, en otro escenario:

g1ff3a2d@lid

El segundo valor no debe validarse como si fuera un número de teléfono. Es un identificador que debe almacenarse y utilizarse de acuerdo con las reglas de la integración.

La adopción de este modelo está relacionada con una tendencia más amplia hacia la privacidad. Al reducir la circulación de números de teléfono entre integraciones, la plataforma dificulta la copia indiscriminada de bases de números y reduce la exposición de datos personales en logs, colas y sistemas de terceros.

Para los desarrolladores, la consecuencia es directa: los parsers, las bases de datos y las reglas de envío deben aceptar más de un formato de identificación.

Un LID no es un teléfono enmascarado que pueda convertirse libremente. Es un identificador operativo que puede mantener la continuidad de una conversación sin exponer el número.

¿LID sustituye al número de teléfono?

No en todos los contextos. LID sustituye la dependencia exclusiva del teléfono en determinados eventos, pero el número puede seguir estando disponible en otros flujos.

En una integración puedes encontrar situaciones como:

• phone con un número tradicional;
• phone con un valor terminado en @lid;
• un campo lid completado por separado;
• chatLid disponible para identificar una conversación;
• chatLid con valor null;
• teléfono y LID disponibles en el mismo evento.

Por eso, no es seguro crear una regla que acepte únicamente dígitos. Una validación como esta puede fallar cuando WhatsApp devuelve un LID:

if (!/^\d+$/.test(phone)) {
  throw new Error('Número de teléfono no válido');
}

La aplicación debe reconocer ambos escenarios y dirigir cada valor al campo correspondiente.

Una validación más adecuada sería separar el identificador del tipo de contacto:

function identify(value) {
  if (!value) return { type: 'unknown', value: null };
  if (value.endsWith('@lid')) return { type: 'lid', value };
  if (/^\d+$/.test(value)) return { type: 'phone', value };
  return { type: 'other', value };
}

Este ejemplo es conceptual. Los campos exactos dependen del payload recibido y del endpoint utilizado, pero el principio es el mismo: no confundas un número de teléfono con un identificador privado.

Consulta también WhatsApp Coexistence: aprende cómo utilizar la app y la API con el mismo número.

Diferencia entre phone, lid y chatLid

Interpretar correctamente estos campos ayuda a evitar errores de búsqueda, contactos duplicados y mensajes enviados al destinatario equivocado.

Campo	Qué representa	Cómo tratarlo
phone	Número del usuario cuando está disponible; en algunas respuestas puede contener un LID	No asumas que siempre contendrá solo dígitos
lid o @lid	Identificador privado del usuario	Guárdalo en un campo propio y utilízalo como identificador del contacto
chatLid	Identificador relacionado con el chat o la conversación	Trátalo como opcional y acepta null
from	Origen del evento o remitente, según el payload	Analízalo junto con los demás campos de identidad
messageId	Identificador del mensaje	Utilízalo para seguimiento, idempotencia y auditoría

¿Qué es phone?

El campo phone suele representar el número del contacto cuando WhatsApp lo proporciona. Sin embargo, en algunas versiones o eventos puede devolver un identificador con formato @lid.

Por lo tanto, el nombre del campo no es suficiente para determinar el tipo de valor. Es necesario analizar su contenido.

¿Qué es lid?

El campo lid representa al usuario mediante un identificador privado. Puede ser el valor más adecuado para localizar y mantener la relación técnica con un contacto cuando el número no está disponible.

No utilices un LID como si fuera un número de teléfono en informes, integraciones con SMS o validaciones que requieran país y código de área.

¿Qué es chatLid?

chatLid está relacionado con la identificación del chat o de la conversación. No debe confundirse con el identificador individual del usuario.

Puede haber eventos en los que chatLid tenga un valor y otros en los que sea null. Esta respuesta no debería interrumpir automáticamente el flujo. La aplicación debe saber si está procesando un mensaje individual, un grupo, una conversación que todavía no se ha persistido o un evento que no tiene un chat asociado en ese momento.

¿Por qué chatLid puede devolver null?

chatLid: null no significa necesariamente que el webhook no sea válido. El campo puede no estar disponible en todos los tipos de eventos ni en todas las etapas de una conversación.

Trata el valor nulo como una posibilidad válida:

const chatId = payload.chatLid || null;
const contactId = payload.contact?.lid || payload.from || null;

if (!contactId) {
  // Envía el evento a una cola de análisis o registra el fallo.
}

La regla práctica es:

• utiliza el LID del contacto cuando la tarea sea identificar al usuario;
• utiliza chatLid cuando la operación necesite identificar la conversación;
• acepta null cuando la conversación no esté disponible en el evento;
• utiliza messageId para rastrear el mensaje;
• no descartes automáticamente todo el webhook solo porque chatLid esté vacío.

Consulta también: WhatsApp prueba llamadas para usuarios sin cuenta: conoce los posibles impactos.

¿Cómo gestiona Z-API el LID en los webhooks?

Z-API trabaja con respuestas que pueden contener número de teléfono, LID e información relacionada con el chat. En lugar de construir una integración dependiente de un único formato, tu aplicación debe consultar los campos de contacto disponibles en el payload y conservar el identificador recibido.

Ejemplos conceptuales de eventos:

{
  "from": "5511999999999",
  "messageId": "ABCD1234",
  "contact": {
    "phone": "5511999999999",
    "lid": null
  }
}

En otro evento:

{
  "from": "g1ff3a2d@lid",
  "messageId": "EFGH5678",
  "chatLid": null,
  "contact": {
    "phone": "g1ff3a2d@lid",
    "lid": "g1ff3a2d@lid"
  }
}

Los nombres exactos de los campos y la composición del payload pueden variar según el endpoint y el tipo de mensaje. El punto central es que el sistema debe buscar el identificador privado dentro del objeto de contacto y conservar el valor recibido.

Al recibir un webhook, una rutina recomendada es:

1. validar el origen y la estructura del evento;
2. extraer messageId, from, phone, lid y chatLid;
3. identificar si cada valor corresponde a un teléfono, un LID o un valor nulo;
4. localizar al contacto por LID cuando esté disponible;
5. actualizar el teléfono únicamente si está presente;
6. registrar el origen y la fecha de la información;
7. procesar el mensaje una sola vez;
8. responder utilizando el identificador aceptado por el endpoint.

¿Puedo enviar mensajes utilizando un LID?

Sí. Cuando el endpoint utilizado acepte este identificador, puedes utilizar el LID en el campo to en lugar del número de teléfono.

Ejemplo conceptual:

{
  "to": "g1ff3a2d@lid",
  "message": "¡Hola! ¿Cómo podemos ayudarte?"
}

El valor debe ser exactamente el identificador recibido y almacenado por la integración. No intentes crear manualmente un LID a partir del teléfono ni modificar sus caracteres para “estandarizarlo” como si fuera un número.

El flujo recomendado es:

Webhook recibido ↓ Guardar contact.lid ↓ Asociarlo al contacto interno ↓ Recuperar el LID al momento del envío ↓ Enviarlo al endpoint de Z-API ↓ Registrar messageId y status

Si se produce un error y el teléfono está disponible, la aplicación puede aplicar una regla de fallback según el endpoint, la causa del fallo y la política operativa de la empresa.

El fallback no debe utilizarse automáticamente ante cualquier error, ya que un fallo de validación, autorización o destinatario no válido no necesariamente se resolverá cambiando el identificador.

¿Cuándo utilizar LID y cuándo utilizar phone?

La decisión depende del objetivo de la operación.

Prefiere LID para identificar al contacto

Utiliza el LID como identificador preferente cuando esté disponible en el webhook y registrado en el sistema. Esto reduce la dependencia del número y mantiene la integración preparada para eventos en los que el teléfono no aparece.

LID es especialmente útil para:

• localizar al contacto en el CRM;
• asociar mensajes con el mismo usuario;
• responder a una conversación iniciada por el cliente;
• evitar que el sistema descarte eventos sin número de teléfono;
• mantener la operación alineada con el modelo de privacidad de WhatsApp.

Utiliza el teléfono cuando la finalidad requiera el número

El teléfono puede seguir siendo necesario para:

• mostrar el contacto en una interfaz administrativa;
• enviar SMS o realizar llamadas fuera de WhatsApp;
• validar un registro externo;
• integrarse con sistemas que todavía no aceptan LID;
• ejecutar una etapa de autenticación que dependa del número.

La recomendación no es eliminar el teléfono. Es separar identidad y finalidad. El número puede seguir siendo un dato complementario, mientras que el LID funciona como clave preferente de la relación dentro de WhatsApp.

¿Cómo modelar la base de datos?

Evita definir phone como la única clave primaria del contacto. Crea un identificador interno propio y almacena los valores de WhatsApp en campos independientes.

Un posible modelo sería:

contacts

• id — identificador interno
• lid — identificador privado de WhatsApp
• phone — número de teléfono, cuando esté disponible
• chat_lid — identificador del chat, cuando esté disponible
• phone_verified_at — fecha de validación del teléfono
• lid_collected_at — fecha de recopilación del LID
• source — origen del identificador
• last_message_id — último mensaje procesado
• created_at
• updated_at

Recomendaciones importantes:

• crea un índice para lid;
• trata el LID como texto;
• no utilices chatLid como identidad del usuario;
• acepta null en teléfono y chatLid;
• registra el origen del dato;
• conserva un historial de los cambios relevantes;
• mantén la unicidad dentro del contexto correcto;
• evita logs con datos personales innecesarios.

¿Cómo realizar la búsqueda?

El orden de búsqueda puede ser:

1. buscar por LID dentro del contexto de la instancia;

2. si no existe, buscar por el teléfono disponible;

3. validar la asociación y el origen;

4. crear el contacto únicamente después de estos intentos.

No dedupliques contactos únicamente por nombre de perfil. El mismo nombre puede pertenecer a varias personas.

Tampoco asocies automáticamente un LID con un número de teléfono solo porque los eventos ocurrieron con poca diferencia de tiempo.

LID y CRM: ¿qué cambia para una empresa de software?

Los sistemas diseñados para trabajar únicamente con números pueden fallar en diferentes puntos:

• validaciones que rechazan caracteres no numéricos;
• máscaras de teléfono aplicadas sobre el LID;
• informes que no consiguen agrupar correctamente los eventos;
• claves foráneas basadas únicamente en phone;
• integraciones de SMS que reciben el identificador incorrecto;
• filtros de país y código de área aplicados al LID;
• deduplicación que crea un nuevo cliente con cada webhook;
• dashboards que dejan de contabilizar contactos sin número.

Haz un inventario de todos los lugares donde se utiliza el teléfono. Después, clasifica cada uso:

Uso del teléfono	¿Puede migrar a LID?	Acción recomendada
Identificar al contacto en WhatsApp	Sí	Preferir LID cuando esté disponible
Enviar mensajes por WhatsApp	En muchos flujos	Utilizar el identificador aceptado por el endpoint
Enviar SMS	No	Mantener un número de teléfono validado
Mostrar en una interfaz administrativa	No necesariamente	Mostrar el teléfono cuando esté disponible y el LID como referencia técnica
Dedupe de contactos	Parcialmente	Utilizar LID, teléfono y reglas de asociación
Informes de conversaciones	Sí	Agrupar por ID interno y registrar los identificadores
Autenticación externa	Depende	Seguir los requisitos del sistema externo

Esta separación evita que un cambio de privacidad en un canal rompa procesos que realmente dependen del número.

¿Puedo convertir un LID en un número de teléfono?

No dependas de una conversión directa de LID a teléfono mediante una API pública. El objetivo de este identificador es precisamente reducir la exposición del número, por lo que la aplicación no debe asumir que tendrá acceso inverso.

En algunos escenarios autorizados puede existir una consulta de teléfono a LID. Esto depende del endpoint, los permisos, la disponibilidad del dato y el modelo de integración.

No construyas tu arquitectura suponiendo que esta conversión siempre estará disponible.

La orientación más segura es:

• almacenar el LID cuando llegue mediante un webhook;
• almacenar el teléfono únicamente cuando se proporcione legítimamente;
• mantener la relación entre ambos cuando la asociación esté confirmada;
• aceptar que algunos registros tendrán únicamente LID;
• no intentar descubrir el teléfono mediante métodos no autorizados;
• no exponer el LID en URLs públicas o logs sin necesidad.

Buenas prácticas de privacidad y seguridad

Aunque un LID no revele directamente el número de teléfono, sigue siendo un identificador relacionado con una persona y debe protegerse.

Reduce los datos en los logs

Registra únicamente lo necesario para depuración. Enmascara valores en logs de producción y restringe el acceso a payloads completos.

Protege los webhooks

Valida el origen, la firma, la autenticación y la estructura del evento. Un webhook expuesto puede permitir la inyección de mensajes o la modificación indebida de contactos.

Separa los identificadores técnicos de los datos que se muestran

Un agente puede necesitar ver el nombre y el teléfono cuando estén disponibles. El sistema no necesita mostrar el LID en todas las pantallas.

Muestra el identificador únicamente donde sea necesario para soporte o auditoría.

Controla el acceso al mapeo

La relación entre LID y teléfono puede ser sensible. Restringe las consultas, registra los accesos y mantén una política de retención compatible con la finalidad del sistema.

¿Qué cambia en la integración con la API de Z-API?

La adaptación es principalmente de modelado y tratamiento de payloads.

No necesitas reescribir toda la aplicación, pero sí debes eliminar la suposición de que todo contacto estará representado por dígitos.

Los cambios más importantes son:

1. añadir un campo específico para LID;
2. aceptar @lid en validaciones y parsers;
3. guardar contact.lid cuando se reciba;
4. tratar chatLid como opcional;
5. actualizar las búsquedas para dar prioridad al LID;
6. mantener el teléfono como información complementaria;
7. registrar messageId para idempotencia;
8. adaptar informes e interfaces administrativas;
9. revisar integraciones que exigen un número de teléfono;
10. probar el envío tanto con número como con LID.

Z-API ofrece una capa de integración para conectar tu sistema con WhatsApp y trabajar con webhooks, mensajes e identificadores devueltos por la operación.

La aplicación cliente sigue siendo responsable de almacenar los datos, validar los flujos y elegir la regla de fallback adecuada.

Antes de llevar el cambio a producción, consulta la documentación del endpoint utilizado y realiza pruebas con payloads reales de tu instancia.

Consulta también: Cómo usar webhooks de WhatsApp para crear automatizaciones en tiempo real con Z-API.

Plan de migración recomendado

Una migración gradual reduce el riesgo de interrumpir la atención.

Etapa 1: inventario

Haz una lista de las tablas, endpoints, workers, dashboards e integraciones que utilizan phone como clave.

Etapa 2: ampliación del modelo

Añade lid, chatLid y metadatos sin eliminar el teléfono existente. Crea índices y actualiza las rutinas de lectura.

Etapa 3: captura

Empieza a almacenar el LID en todos los webhooks que lo incluyan. Registra la fecha, el origen y el mensaje asociado.

Etapa 4: lectura preferente

Actualiza los lookups para buscar primero por LID y utilizar el teléfono como fallback cuando esté disponible y sea apropiado.

Etapa 5: envío controlado

Prueba mensajes para contactos identificados por número y por LID. Registra estado, error, tiempo y respuesta.

Etapa 6: reconciliación

Crea una rutina para identificar contactos duplicados, asociaciones incompletas y eventos sin una clave utilizable.

Etapa 7: observabilidad

Monitorea fallos de parsing, mensajes sin destinatario, valores nulos de chatLid, errores de envío y aumentos en los registros duplicados.

Etapa 8: rollout

Libera la nueva lógica gradualmente y conserva la posibilidad de volver al comportamiento anterior en aquellos flujos donde el teléfono siga siendo necesario.

Checklist rápido

• Crear un campo lid en la tabla de contactos.
• Crear un campo opcional para chatLid.
• Indexar el LID como texto.
• Aceptar valores con el sufijo @lid.
• Guardar contact.lid recibido en los webhooks.
• Tratar chatLid: null como una respuesta válida.
• No utilizar phone como única clave primaria.
• Actualizar las búsquedas para dar prioridad al LID.
• Mantener el teléfono como dato complementario.
• Implementar idempotencia mediante messageId.
• Probar el envío con número y con LID.
• Crear fallback únicamente cuando tenga sentido.
• Revisar logs, máscaras y permisos.
• Actualizar dashboards e informes.
• Documentar el nuevo flujo para los equipos de soporte y desarrollo.

Conclusión

LID representa un cambio importante en la forma en que los sistemas identifican contactos en WhatsApp. La plataforma puede seguir funcionando incluso cuando el número de teléfono no está disponible, pero solo si la integración está preparada para trabajar con identificadores privados.

El principal error es tratar un LID como si simplemente fuera un teléfono con otro formato. Tiene su propia finalidad, reglas y limitaciones.

Almacénalo en un campo específico, utilízalo para localizar al contacto, trata chatLid como opcional y conserva el teléfono únicamente donde realmente sea necesario.

La migración no tiene por qué ser traumática. Empieza por el modelo de datos, actualiza los webhooks, adapta las validaciones, prueba los envíos y monitorea los casos en los que el número no esté presente.

Con Z-API, tu empresa puede trabajar con webhooks e integraciones que preserven la continuidad del contacto incluso cuando los identificadores varíen entre teléfono, LID e identificador de chat.

La aplicación es responsable de mantener un modelo flexible, seguro y coherente con los datos recibidos.

¿Recibiste un LID en el webhook? No descartes el evento. Guarda el identificador, asócialo al contacto interno y adapta el flujo de envío para utilizar el valor correcto.

Preguntas frecuentes

¿Qué es LID en WhatsApp?

Es un identificador privado utilizado para representar a un usuario sin depender de la exposición directa del número de teléfono en determinados eventos e integraciones.

¿LID es igual al número de teléfono?

No. LID es un identificador técnico y debe almacenarse en un campo propio. No apliques máscaras de teléfono, validaciones de código de área ni reglas de SMS sobre él.

¿Qué debo hacer cuando phone devuelve un valor con @lid?

Identifica el tipo de valor, guárdalo como LID y no intentes tratarlo como un número de teléfono.

Consulta los demás campos del payload para localizar información complementaria del contacto.

¿Por qué chatLid devuelve null?

El campo puede no estar disponible en determinados eventos o tipos de conversación.

Trata null como una respuesta válida y utiliza el LID del contacto u otro identificador disponible para procesar el mensaje.

¿Puedo enviar un mensaje a un LID?

Si el endpoint utilizado acepta este formato, sí.

Utiliza exactamente el LID recibido en el webhook y sigue la documentación de la integración.

¿Puedo convertir un LID en un número de teléfono?

No asumas que esta conversión estará disponible mediante una API pública.

LID existe precisamente para reducir la exposición del número. Almacena el teléfono únicamente cuando sea proporcionado de forma legítima y autorizada.

¿Necesito eliminar los números de teléfono de mi base de datos?

No. Los números todavía pueden ser necesarios para SMS, autenticación, atención al cliente o integraciones externas.

La recomendación es simplemente no utilizar el teléfono como única clave de la relación en WhatsApp.

¿Qué cambia en mi integración con Z-API?

Debes adaptar el tratamiento de los webhooks, almacenar el LID, aceptar @lid, tratar chatLid como opcional, revisar la lógica de búsqueda y probar los envíos para los identificadores disponibles en cada flujo.