Nombres de usuario de WhatsApp y BSUID: qué cambia para quien usa la API

Actualizado el 28/10/2026

Los nombres de usuario (usernames) son nombres únicos y opcionales que personas y empresas pueden adoptar en WhatsApp; cuando un cliente activa el suyo, su número de teléfono puede dejar de llegar en los webhooks de la API de WhatsApp. Para que las integraciones sigan sabiendo quién escribió, Meta creó el BSUID (business-scoped user ID), un identificador del usuario válido solo dentro de tu portafolio empresarial. Aparece en los webhooks desde abril de 2026 y, desde julio de 2026, la API acepta enviarle mensajes.

Qué son los nombres de usuario en WhatsApp

Según la documentación de BSUID de Meta, el nombre de usuario es un nombre que la persona puede definir para que aparezca en la app en lugar de su número. Cada persona tiene como máximo uno, puede cambiarlo de vez en cuando y el cambio no altera ni el número ni el BSUID. Adoptarlo es opcional, tanto para personas como para empresas.

Del lado de la empresa existe el nombre de usuario comercial. No oculta el número de la empresa (Meta aclara que no es una función de privacidad) y cada nombre apunta a un único número comercial. Reglas de formato:

• solo letras del alfabeto inglés, dígitos, punto y guion bajo;
• de 3 a 35 caracteres, con al menos una letra;
• no puede empezar ni terminar con punto, ni tener dos puntos seguidos;
• no puede empezar con www. ni terminar con un sufijo de dominio como .com;
• no distingue mayúsculas, pero punto y guion bajo cuentan: mitienda, mi.tienda y mi_tienda son nombres distintos.

Desde el 29 de junio de 2026 las empresas pueden reservar y adoptar su nombre de usuario en Meta Business Suite, el Administrador de WhatsApp, la app WhatsApp Business o la API. En la actualización del 23 de octubre de 2026, Meta agregó un límite: cada número comercial puede cambiar de nombre de usuario hasta 2 veces en 14 días corridos (10 veces para nombres reservados). Si se supera, la API devuelve el error 130429.

Qué es el BSUID

El BSUID identifica a un usuario de WhatsApp para una empresa específica. Según la documentación, es:

• generado automáticamente, tenga o no el usuario un nombre de usuario;
• formado por el código de país ISO 3166 alfa-2, un punto y hasta 128 caracteres alfanuméricos, por ejemplo US.13491208655302741918;
• único por par usuario + portafolio empresarial (el antiguo Business Manager);
• regenerado cuando el usuario cambia de número.

El alcance es lo que más confunde: un BSUID solo funciona con números del mismo portafolio. En un SaaS, el BSUID que llegó al número del cliente A no sirve para enviar desde el número del cliente B.

Las empresas con varios portafolios pueden pedir a Meta el BSUID principal (parent BSUID), válido en todos los portafolios inscritos. Lleva ENT después del código de país (US.ENT.11815799212886844830) y llega en el campo parent_user_id. La inscripción depende de la elegibilidad que evalúa tu contacto en Meta.

Meta afirma que el soporte de BSUID es obligatorio para socios, empresas con integración directa y anunciantes de anuncios que hacen clic a WhatsApp, porque nadie controla cuándo un cliente activará su nombre de usuario.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Campos nuevos en los webhooks

El BSUID aparece en todo webhook que normalmente traería el teléfono. Campos documentados:

Webhook	Campo	Qué trae
Mensaje recibido	contacts[].user_id	BSUID del usuario
Mensaje recibido	contacts[].profile.username	Nombre de usuario, solo si lo tiene
Mensaje recibido	messages[].from	Teléfono (puede omitirse)
Mensaje recibido	messages[].from_user_id	BSUID
Estado	statuses[].recipient_id	Teléfono (puede omitirse)
Estado	statuses[].recipient_user_id	BSUID, siempre incluido (salvo failed enviado por teléfono)
Cualquiera, si está habilitado	parent_user_id, from_parent_user_id, recipient_parent_user_id	BSUID principal

Un webhook de mensaje recibido de alguien que activó su nombre de usuario y con quien no hablaste en los últimos 30 días puede llegar así, sin teléfono:

{
  "contacts": [
    {
      "profile": { "name": "Pablo M.", "username": "pablomorales" },
      "user_id": "MX.13491208655302741918"
    }
  ],
  "messages": [
    {
      "from_user_id": "MX.13491208655302741918",
      "id": "wamid.HBgL...",
      "timestamp": "1761650000",
      "type": "text",
      "text": { "body": "Hola, ¿ya llegó mi pedido?" }
    }
  ]
}

Los webhooks de user_preferences, grupos y llamadas también recibieron estos campos. Y el nuevo business_username_updates avisa cuando cambia el estado del nombre de usuario de la empresa (context: "revoked" cuando Meta lo revoca).

Cuándo el teléfono sigue llegando

Aunque el usuario tenga nombre de usuario, su número sigue en el payload si se cumple al menos una condición:

1. le enviaste un mensaje o lo llamaste en los últimos 30 días;
2. recibiste un mensaje o llamada de ese número en los últimos 30 días;
3. el usuario está en tu contact book.

Las dos primeras se evalúan por número comercial, no por portafolio. Si el cliente habla con tu número de ventas, el webhook de tu número de soporte puede llegar sin teléfono.

Cambio de número y cambio de BSUID

Cuando el usuario cambia de número, el BSUID se regenera y recibes un mensaje de sistema en el campo messages con system.type igual a user_changed_number, con user_id, previous_user_id y wa_id cuando el número puede compartirse. Si no puede, el tipo es user_changed_user_id y solo cambian los identificadores. Basta con suscribirse a messages (user_id_update no es un campo suscribible). Para el formato general de los eventos, consulta estados de mensaje por webhook y el glosario de la API de WhatsApp.

Cómo enviar un mensaje a un BSUID

Desde julio de 2026, POST /<PHONE_NUMBER_ID>/messages acepta el campo recipient con el BSUID en lugar de to:

curl -X POST 'https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>/messages' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "recipient": "MX.13491208655302741918",
    "type": "text",
    "text": { "body": "Tu pedido salió a reparto." }
  }'

Reglas para recordar:

• Usa el valor completo. Código de país, punto y todos los caracteres. Cualquier cambio hace fallar la solicitud.
• to gana sobre recipient. Si envías ambos, Meta usa el teléfono.
• Excepción: autenticación. Las plantillas de autenticación one-tap, zero-tap y copy code exigen el teléfono. Enviarlas a un BSUID devuelve el error 131062.
• Alcance del portafolio. Un BSUID de otro portafolio no funciona.

La Marketing Messages API también acepta envíos por BSUID desde el 5 de mayo de 2026, pero Meta advierte que la optimización de entrega no se aplica a esos envíos y recomienda usar el teléfono cuando lo tengas.

Pedirle el teléfono al cliente

Si un contacto solo tiene BSUID y necesitas el número (para facturación, cobro u OTP), Meta creó el botón REQUEST_CONTACT_INFO. Puede ir en plantillas de utilidad y marketing o enviarse como mensaje interactivo. Cuando el usuario lo toca, el número se comparte en el chat y llega un webhook de contactos con origin: "contact_request". La etiqueta del botón no se puede personalizar.

Contact book: la agenda que Meta guarda por ti

El contact book está alojado por Meta y no requiere integración. Tras el lanzamiento de la función, cada interacción (mensaje o llamada, enviada o recibida) entre un número del portafolio y un usuario guarda su teléfono y su BSUID. A partir de ahí, los webhooks de ese usuario traen el teléfono aunque active su nombre de usuario.

Puntos de atención:

• no es retroactivo: las conversaciones anteriores al lanzamiento no se guardan;
• el alcance es el portafolio empresarial;
• los datos se conservan hasta que desactives la función (Meta Business Suite > Configuración del negocio > Información del negocio) o la cuenta; desactivarla borra todo y reactivarla no lo recupera;
• por API, GET /<PHONE_NUMBER_ID>/contact_book indica si hay un teléfono guardado para un BSUID (campo present) sin devolver nunca el número, y un DELETE elimina la entrada.

Impacto en un CRM que usa el teléfono como clave

La mayoría de las integraciones usa wa_id o from como clave primaria del contacto. Con los nombres de usuario, los mensajes pueden llegar sin teléfono y el BSUID cambia cuando el cliente cambia de número.

Un modelo que resiste:

1. Crea una tabla de identidades, no una columna. Cada contacto puede tener teléfono, un BSUID por portafolio y un BSUID principal.
2. Busca primero por BSUID, después por teléfono. Si ambos coinciden con contactos distintos, fusiónalos.
3. Guarda el par teléfono + BSUID siempre que lleguen juntos. Así reconoces al cliente cuando aparezca solo con BSUID.
4. Procesa user_changed_number y user_changed_user_id actualizando el BSUID a partir de previous_user_id.
5. Responde desde el mismo número comercial cuando sea posible, por la regla de 30 días por número.
6. Prueba antes de producción. El Panel de apps tiene un botón Test en el webhook de mensajes con escenarios de usuarios con y sin nombre de usuario.

async function resolverContacto(value) {
  const c = value.contacts?.[0] ?? {};
  const msg = value.messages?.[0] ?? {};
  const bsuid = c.user_id ?? msg.from_user_id;
  const telefono = msg.from ?? c.wa_id; // puede venir vacío

  let contacto = bsuid ? await db.contactoPorBsuid(bsuid) : null;
  if (!contacto && telefono) contacto = await db.contactoPorTelefono(telefono);
  if (!contacto) contacto = await db.crearContacto();

  await db.vincular(contacto.id, { bsuid, telefono, username: c.profile?.username });
  return contacto;
}

Si tu embudo depende de anuncios, el mismo cuidado aplica a la atribución: consulta cómo rastrear anuncios Click-to-WhatsApp. Cambios paralelos en la cuenta, como la nueva estructura de la WABA, también afectan los IDs que guarda tu CRM.

Cronograma confirmado en la documentación de Meta

Fecha	Qué pasó
Inicio de abril de 2026	Los BSUID empiezan a aparecer en los webhooks
5 de mayo de 2026	/marketing_messages acepta envíos por BSUID
29 de junio de 2026	Las empresas pueden reservar y adoptar nombre de usuario comercial
Julio de 2026	La Cloud API acepta envíos por BSUID; botón REQUEST_CONTACT_INFO disponible
24 de agosto de 2026	Consulta del contact book (GET .../contact_book)
23 de octubre de 2026	Límite de cambio de nombre de usuario (2 cada 14 días) y error 130429
2026	WhatsApp habilita los nombres de usuario de forma gradual

Meta no publicó una fecha única para que todos los usuarios tengan nombre de usuario; la página solo habla de un despliegue gradual en 2026. Seguimos los próximos cambios en novedades de la API de WhatsApp en 2026.

Cómo funciona con Vectalk

Vectalk es un proxy de la WhatsApp Cloud API oficial: los webhooks que registras con POST /api/webhooks reciben el mismo payload que envía Meta, así que user_id, from_user_id, username y los mensajes de sistema llegan sin cambios. Lo que hay que ajustar está en tu código, en el modelo de contacto descrito arriba. La referencia de eventos está en la documentación de webhooks y el registro se hace en apps.vectalk.com.br/register.

Preguntas frecuentes

¿El cliente que active su nombre de usuario desaparecerá de mi CRM?

No, si tu integración ya lee el BSUID. Llega en todo webhook, con o sin nombre de usuario. Lo que puede faltar es el teléfono, cuando no hubo conversación en ese número en los últimos 30 días y el cliente no está en el contact book.

¿Puedo enviar una plantilla de marketing a un BSUID?

Sí. El envío por BSUID acepta cualquier tipo de mensaje, salvo las plantillas de autenticación one-tap, zero-tap y copy code. En la Marketing Messages API, los envíos por BSUID no reciben optimización de entrega.

¿El BSUID cambia?

Cambia cuando el usuario cambia de número de teléfono. Cambiar el nombre de usuario no altera el BSUID. El cambio llega como mensaje de sistema en el webhook messages.

¿Tener nombre de usuario oculta el número de mi empresa?

No. Meta dice que el nombre de usuario comercial no oculta el número de la empresa y no fue pensado como función de privacidad.

¿Un BSUID sirve para todos mis clientes de SaaS?

No. Está limitado al portafolio empresarial donde se generó. Cada cliente tendrá sus propios BSUID para los mismos usuarios.

---

Fuentes oficiales consultadas el 28/10/2026: Business-scoped user IDs (actualizada el 23/10/2026), Registro de cambios de la plataforma de WhatsApp, Enviar mensajes de marketing (Marketing Messages API).