Iniciar sesiónEmpezar prueba gratis
Meta Tech Provider

Nombres de usuario de WhatsApp e ID de usuario con alcance de negocio (BSUID): qué cambia en los webhooks de Cloud API

Los nombres de usuario de WhatsApp permiten mostrar un nombre en lugar del número de teléfono, por lo que, desde principios de abril de 2026, los webhooks de mensajes de Cloud API también incluyen un ID de usuario con alcance de negocio (BSUID), como US.13491208655302741918, en user_id y from_user_id. Si un usuario tiene nombre de usuario, no ha intercambiado mensajes ni llamadas con el número en los últimos 30 días y no está en la libreta de contactos, wa_id y from se omiten.

easyCoexistence conecta un número de la app de WhatsApp Business con la Cloud API mediante Coexistencia y enruta sus webhooks messages y smb_message_echoes a tu endpoint tal como Meta los envía, con los campos BSUID incluidos, mientras get_api_credentials da a tu código lo necesario para responder con recipient.

April 2026

Cuándo empezaron a aparecer los BSUID en los webhooks de Cloud API, antes de que los nombres de usuario llegaran a los usuarios de WhatsApp.

July 2026

Cuándo las API empezaron a aceptar mensajes enviados a un BSUID, indicado en recipient en lugar de to.

30 days

Período retroactivo, contado por número de teléfono de negocio, en el que cualquier mensaje o llamada con el usuario mantiene su número en los webhooks.

128

Número máximo de caracteres alfanuméricos tras el código de país de dos letras y el punto de un BSUID.

131062

Error de la API de Mensajes: Business-scoped User ID (BSUID) recipients are not supported for this message.

user_changed_user_id

Tipo de mensaje de sistema para un cambio de BSUID notificado sin número de teléfono, con el BSUID anterior en previous_user_id.

¿Qué son los nombres de usuario y los BSUID de WhatsApp?

Un nombre de usuario es un nombre opcional y único que un usuario de WhatsApp puede configurar y que la app muestra en lugar de su número de teléfono; Meta los está implementando de forma gradual durante 2026. Un BSUID es el identificador de backend que Meta añadió para que las empresas puedan seguir distinguiendo a los usuarios: se genera automáticamente, es único para cada par de portafolio comercial y usuario, y se escribe con el código de país ISO 3166 de dos letras del usuario, un punto y hasta 128 caracteres alfanuméricos. Meta exige que los socios y las empresas con integración directa lo admitan, ya que ninguna empresa controla si sus usuarios adoptan nombres de usuario.

¿Qué campos contienen los nuevos identificadores?

Propiedades nuevas junto a las que contenían el número de teléfono, en los webhooks messages, status, system y user_preferences. Los campos del BSUID principal (parent) solo aparecen en los portafolios comerciales que Meta ha inscrito en los BSUID principales, que funcionan en todos los portafolios inscritos:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

¿Cuándo se omite el número de teléfono?

Cuando el usuario tiene un nombre de usuario y no se cumple ninguna de las tres condiciones de Meta. El número se mantiene en los webhooks si el número de teléfono de negocio envió un mensaje o llamó al número de ese usuario en los últimos 30 días, si recibió un mensaje o una llamada de él en ese plazo o si el usuario está en la libreta de contactos del portafolio. El período retroactivo de 30 días se cuenta por número de teléfono de negocio, así que un segundo número del mismo portafolio puede recibir solo el BSUID de ese mismo usuario. Los usuarios sin nombre de usuario siguen llegando con su número de teléfono y su BSUID.

¿Cómo es ahora un mensaje entrante?

Igual que antes, con el BSUID junto al número de teléfono o en su lugar. En el ejemplo de Meta de un usuario con nombre de usuario cuyo número no puede compartirse, contacts incluye profile.name, profile.username y user_id, y el mensaje lleva from_user_id donde antes iba from:

messages webhook: a text from a user known only by BSUID
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
        "contacts": [{
          "profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
          "user_id": "US.13491208655302741918"
        }],
        "messages": [{
          "from_user_id": "US.13491208655302741918",
          "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
          "timestamp": "1749416383",
          "type": "text",
          "text": { "body": "Does it come in another color?" }
        }]
      }
    }]
  }]
}

¿Cómo cambian los webhooks de estado?

Los estados enviado, entregado y leído incorporan un array contacts con el nombre del usuario, user_id, wa_id cuando el número puede compartirse, y username en entregado y leído. En statuses, recipient_user_id contiene el BSUID, y recipient_id se omite cuando enviaste el mensaje a un BSUID y el número no puede compartirse. Un estado fallido no tiene array contacts y omite recipient_user_id cuando el mensaje se envió a un número de teléfono, así que vincula los fallos al id del mensaje.

¿Cómo almacenar e identificar a los usuarios?

Primero por BSUID, con el número de teléfono como segunda clave siempre que llegue. Guarda el BSUID completo como cadena, con el código de país y el punto incluidos, ya que Meta rechaza las peticiones que alteren cualquier parte de él, y guarda también el BSUID principal si tus portafolios están inscritos. Vincula los registros existentes por wa_id mientras siga llegando y conserva el BSUID junto a ellos, porque un usuario que adopte un nombre de usuario más adelante puede volver sin número. Las preguntas frecuentes de Meta piden hacer los mismos cruces en los CRM y en las herramientas que estos alimentan.

¿Qué ocurre cuando un usuario cambia de número de teléfono?

Su BSUID se regenera y el cambio llega en el campo messages como mensaje de sistema, ya que Meta no tiene un campo user_id_update al que suscribirse. system.type es user_changed_number cuando el nuevo número puede compartirse contigo, o user_changed_user_id cuando solo puede notificarse el cambio de BSUID; system.user_id contiene el nuevo BSUID y system.previous_user_id el anterior, lo que permite trasladar el registro. Gestiona ambos tipos.

¿Cómo responder a un usuario del que solo conoces el BSUID?

Envía a /<BUSINESS_PHONE_NUMBER_ID>/messages con recipient establecido en el BSUID y sin to; si están ambos, prevalece to y la respuesta va al número de teléfono. La entrada contacts de la respuesta incluye entonces input y user_id en lugar de wa_id. Funciona cualquier tipo de mensaje salvo las plantillas de autenticación de un toque, sin toque y de copiar código, que necesitan un número de teléfono, y solo los números del mismo portafolio comercial pueden enviar mensajes a un BSUID. El error 131062 significa que el tipo de mensaje no admite destinatarios BSUID.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

¿Cómo pedir a un usuario su número de teléfono?

Con el botón REQUEST_CONTACT_INFO, añadido a una plantilla de utilidad o de marketing, o enviado como mensaje interactivo de tipo request_contact_info. Si el usuario lo toca, comparte su número en el chat y llega un webhook contacts con origin establecido en contact_request y el número en phones[].wa_id; un contacto compartido manualmente llega con origin other y una vCard. Meta habilitó el botón a principios de julio de 2026, y su etiqueta no se puede personalizar.

¿Qué es la libreta de contactos?

Un almacén que Meta aloja para cada portafolio comercial, sin trabajo de integración: en cuanto un número de teléfono de negocio envía un mensaje, llama o recibe un mensaje o una llamada del número de teléfono de un usuario, ese número y el BSUID se registran y se usan para completar los webhooks posteriores con el número de teléfono, tenga o no nombre de usuario. Solo cuentan las interacciones posteriores a su lanzamiento. Puede desactivarse en Meta Business Suite, Configuración de la empresa, Información de la empresa, lo que elimina su contenido, y GET o DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book con un bsuid consulta o elimina una entrada.

¿Qué debe cambiar una integración de Coexistencia?

Su gestión de los tres webhooks que solo recibe un número de Coexistencia, que también cambian. En history, cada chat incorpora un objeto context con wa_id, user_id y username, y sus mensajes incorporan from_user_id. En smb_message_echoes se añade un array contacts, y message_echoes[].to puede omitirse mientras to_user_id contiene el BSUID; las ediciones y eliminaciones hechas en la app de WhatsApp Business llegan del mismo modo. En smb_app_state_sync, el phone_number de un contacto puede omitirse, con user_id y username a su lado. Vincula los ecos y los chats importados por user_id además de por el número.

¿Cómo probar antes de que los usuarios adopten nombres de usuario?

Con la herramienta de pruebas de Meta en el App Dashboard: en Casos de uso, Conectar con clientes a través de WhatsApp, Personalizar, Configuración, el enlace Test junto al webhook messages envía un ejemplo a tu endpoint. Cubre mensajes entrantes y estados en cuatro escenarios:

  • Un usuario sin nombre de usuario: campos de BSUID y de número de teléfono, sin username.
  • Un usuario con nombre de usuario cuyo número no está disponible: username y BSUID, sin campos de número de teléfono.
  • Un usuario con nombre de usuario cuyo número está disponible: username, BSUID y número de teléfono.
  • Un portafolio inscrito en los BSUID principales: un BSUID principal junto al BSUID propio del portafolio.

¿Cómo gestiona easyCoexistence los BSUID?

Los transmite tal como Meta los envía. Un número enrutado a tu endpoint con set_webhook_destination recibe sus webhooks messages y smb_message_echoes directamente de Meta, con user_id, from_user_id, to_user_id y username incluidos, y, con las automatizaciones o el reenvío activados, easyCoexistence reenvía sin cambios el valor que envió Meta. Para responder a un BSUID, tu código usa get_api_credentials, que devuelve el ID del número de teléfono, su endpoint de envío y, cuando está disponible, tu propio token; las herramientas send_message y send_template reciben un número de teléfono en formato internacional.

Errores comunes

  • Identificar contactos solo por wa_id. Un usuario con nombre de usuario que no ha tenido contacto con el número en 30 días llega solo con user_id y from_user_id, y un manejador que exige wa_id pierde el mensaje.
  • Recortar el prefijo de país de un BSUID. Meta exige el valor completo, con el código de país y el punto, y cualquier petición con una parte alterada falla.
  • Esperar un campo user_id_update. Meta no tiene ninguno: los cambios de BSUID llegan en messages como mensajes de sistema de tipo user_changed_number o user_changed_user_id.
  • Vincular los ecos de Coexistencia solo por to. En smb_message_echoes el campo to puede omitirse, así que una respuesta escrita en la app pasa desapercibida si no se compara también to_user_id.
Hacerlo con EasyCoexistence

Cada conexión se supervisa 24/7. De US$ 9 a US$ 0.75 por conexión al mes, con un precio que baja a medida que añades conexiones, y los primeros 3 días son gratis.

Preguntas frecuentes

¿Los usuarios sin nombre de usuario también tienen BSUID?

Sí. Meta incluye user_id en los webhooks messages tenga o no el usuario nombre de usuario, así que la mayoría de los usuarios llega con su número de teléfono y su BSUID.

¿Un número de Coexistencia puede tener nombre de usuario de empresa?

Sí. Desde el 29 de junio de 2026, una empresa puede adoptarlo o cambiarlo en Meta Business Suite, WhatsApp Manager, la app de WhatsApp Business o la Username API; no oculta el número de la empresa, y business_username_updates notifica cada cambio de estado.

¿Un BSUID sirve en varios portafolios comerciales?

No. Un BSUID pertenece a un portafolio y a un usuario, y un número de otro portafolio no puede enviarle mensajes. Las empresas gestionadas que Meta inscribe reciben BSUID principales, con ENT después del código de país, que funcionan en todos sus portafolios inscritos.

¿Cuánto cuesta easyCoexistence por un número de WhatsApp?

De US$ 9 a US$ 0.75 por conexión al mes, según cuántas conexiones tengas, y los primeros 3 días son gratis. Los cargos por mensaje de Meta se siguen cobrando en el método de pago de tu cuenta de WhatsApp Business.

Sigue leyendo

¿Listo para empezar?

Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.

Empezar prueba gratis

Verificado el