Tabla de contenido

Acción requerida: nombres de usuario y BSUID de WhatsApp: lo que necesita saber

Raquel Actualizado por Raquel

WhatsApp implementará un cambio importante en 2026: los usuarios finales podrán ocultar su número de teléfono cuando envíen mensajes a empresas, identificándose con un nombre de usuario (por ejemplo, @alice_smith).

Eso significa que el número de teléfono del usuario dejará de ser su identificador principal. Meta está introduciendo un nuevo identificador llamado BSUID (ID de usuario de ámbito empresarial). En los próximos meses, los BSUID comenzarán a aparecer junto con los números de teléfono en la API de WhatsApp Business.

Este artículo le brinda un aviso temprano sobre: qué está cambiando, qué permanece igual y cómo prepararse para este cambio, ya que esto potencialmente requiere que usted realice cambios en sus sistemas.

La implementación de Meta está en curso y algunas piezas todavía se están habilitando en su lado (docs). Mantendremos este artículo actualizado a medida que evolucionen las cosas.

¿Qué es un BSUID?

Un BSUID es un identificador que representa de forma única a un usuario dentro de su cartera de negocios. Tiene este aspecto:

US.13491208655302741918
IN.26329079733414951

El formato es un código de país (ISO 3166 alfa-2) seguido de una cadena alfanumérica.

Algunas propiedades importantes:

  • Ambito de cartera: el mismo usuario final tendrá un BSUID diferente para cada cartera de negocios a la que envíe mensajes.
  • Estable entre cambios de nombre de usuario: incluso si un usuario cambia su @nombredeusuario, su BSUID permanece igual.
  • Regenerado al cambiar de número de teléfono: si un usuario cambia de número de teléfono, su BSUID es reeditado.
  • Siempre presente: los BSUID se incluyen en cada webhook, independientemente de si el usuario ha elegido usar un nombre de usuario o no.

Lo que permanece igual

Nada se interrumpe para tus contactos existentes. Aún tendrás los números de teléfono de las personas que ya te enviaron mensajes. Todos los contactos que tengas hoy seguirán funcionando exactamente como antes.

También recibirás el número de teléfono del usuario en webhooks en muchos escenarios comunes, incluso después de que adopten un nombre de usuario.

Qué está cambiando

  • No tendrás acceso al número de teléfono de los nuevos usuarios que opten por ocultarlo
  • El identificador principal de los usuarios será su BSUID, no su whatsapp_id (su número de teléfono).

En Turn.io, estos cambios se implementarán progresivamente:

  • Los contactos tendrán nuevos campos
  • Envío de mensajes por BSUID
  • Nuevas expresiones de viaje
  • Cambio de comportamiento para @contact.whatsapp_id
  • Importaciones y exportaciones de CSV
  • Plantillas de autenticación
  • Clientes de BigQuery/almacén de datos

Preparándose

A lo largo de los años, todos crearon sus servicios asumiendo que el identificador principal de un usuario sería su número de teléfono. Esto significa que, en todo el sistema, es posible que dependa del número de teléfono. Aquí hay una lista exhaustiva de cosas que debes revisar y cómo hacer la transición para usar BSUID.

1. Cambios en la API

1.1 Puntos finales de contacto: BSUID como identificador

Todos los puntos finales de contacto ahora aceptan un BSUID como parámetro de ruta contact_id, además de los números de teléfono.

Antes: Solo se aceptan números de teléfono.

OBTENER /v1/contacts/918609840467/profile

Después: se acepta número de teléfono o BSUID. El formato se detecta automáticamente.

GET /v1/contacts/918609840467/profile          # por teléfono


GET /v1/contacts/IN.26329079733414951/profile  # por BSUID

Afectado puntos finales:

  • GET /v1/contacts/<contact_id>: obtener o crear un contacto
  • POST /v1/contacts/<contact_id>: crear un contacto por identificador
  • PUT /v1/contacts/<contact_id>: actualizar un contacto
  • GET /v1/contacts/<contact_id>/profile — obtener perfil de contacto
  • PUT /v1/contacts/<contact_id>/profile — reemplazar perfil de contacto
  • PATCH /v1/contacts/<contact_id>/profile: actualización parcial del perfil de contacto
  • DELETE /v1/contacts/<contact_id>/profile: eliminación del perfil de contacto
  • GET /v1/contacts/<contact_id>/messages: lista de mensajes para un contacto
  • GET/POST/PUT/DELETE /v1/contacts/<contact_id>/claim: administrar la asignación de chat

1.2 Respuesta del contacto: nuevos campos

GET /v1/contacts/<contact_id> ahora incluye el BSUID y el nombre de usuario del contacto cuando se conoce:

{

  "id": "uuid",

  "tipo": "DEFAULT",

  "is_fallback_active": falso,

  "failure_count": 0,

  "bsuid": "IN.26329079733414951",

  "nombre de usuario": "alice_smith"

}

Campo

Tipo

Descripción

bsuid

cadena, omitida cuando no set

Cadena de ID de usuario de ámbito empresarial del usuario

nombre de usuario

, omitida cuando no está configurada

El nombre de usuario de WhatsApp del usuario (p. ej. alice_smith)

1.3 Webhooks que recibe de Turn

Si consume los webhooks de Turn, los campos BSUID ahora aparecen en las cargas útiles y los campos basados en teléfono pueden estar ausentes para los usuarios que han ocultado su número de teléfono. Cualquier código que asuma que from, to o wa_id está siempre presente debe controlar que falten.

1.3.1  Mensaje entrante webhooks

Campo

Cambiar

de

Se omite cuando el teléfono del remitente no está disponible (siempre estuvo presente)

from_bsuid

Nuevo: el BSUID del remitente. No presente en los mensajes recibidos antes del soporte BSUID

entrada de contactos[]

Formato de espejos Meta: wa_id (teléfono) cuando esté disponible, user_id (BSUID) cuando esté disponible, o ambos

Fragmento de mensaje de ejemplo para un BSUID únicamente usuario:

{

  "id": "wamid.xxx",

  "tipo": "text",

  "from_bsuid": "IN.26329079733414951",

  "text": { "cuerpo": "Hola" }

}

con la entrada de contacto: { "perfil": { "nombre": "Alice" }, "user_id": "IN.26329079733414951" }

1.3.2  Webhooks de mensajes salientes

Campo

Cambiar

a

nulo cuando el destinatario no tiene número de teléfono (siempre fue el teléfono)

destinatario

Nuevo: el BSUID del destinatario, incluido siempre que la conversación tenga uno (puede aparecer junto a)

1.4 Envío de mensajes: nuevo campo destinatario

POST /v1/messages ahora acepta un campo de destinatario para envíos basados en BSUID, como alternativa al campo para.

Antes:

{

  "a": "918609840467",

  "type": "texto",

  "texto": { "cuerpo": "Hola" }

}

Después: enviar por BSUID:

{

  "destinatario": "IN.26329079733414951",

  "tipo": "texto",

  "texto": { "cuerpo": "Hola" }

}

Después: enviar con ambos (el teléfono tiene prioridad):

{

  "a": "918609840467",

  "destinatario": "IN.26329079733414951",

  "tipo": "texto",

  "texto": { "cuerpo": "Hola" }

}

Reglas:

  • Se debe proporcionar al menos uno de los destinatarios o destinatario
  • Cuando se proporcionan ambos, el teléfono (to) tiene prioridad
  • a acepta solo números de teléfono (sin prefijo +)
  • destinatario acepta BSUID solamente

1.5 Exportación CSV de contacto: nuevas columnas

Las exportaciones CSV ahora incluyen dos columnas adicionales junto con whatsapp_phone_number:

Nueva columna

Descripción

Ejemplo

bsuid

Usuario con ámbito empresarial ID

IN.26329079733414951

nombre de usuario

nombre de usuario de WhatsApp

alice_smith

1.6 Bloquear/Desbloquear — Soporte BSUID

El bloqueo y desbloqueo de contactos ahora funciona con identificadores BSUID. La API detecta automáticamente si el identificador es un número de teléfono o BSUID. Al enviar la solicitud de bloqueo a Meta, el sistema utiliza user_id (BSUID) cuando el teléfono no está disponible.

1.7 Llamadas salientes: nuevo campo recipient

Las llamadas salientes iniciadas por empresas ahora incluyen un campo destinatario para el inicio de llamadas basado en BSUID, junto con el campo to existente.

2. Cambios en el recorrido

2.1 Nuevos campos de contacto

Hay dos nuevas expresiones disponibles en los recorridos:

Expresión

Tipo

Descripción

Ejemplo valor

@contact.bsuid

cadena

El valor del usuario BSUID

IN.26329079733414951

@contacto.nombredeusuario

cadena

WhatsApp del usuario nombre de usuario

@alice_smith

Están disponibles en el generador de viajes en el menú Variables de contacto.

2.2 Nuevo chat Campo

Expresión

Tipo

Descripción

@chat.owner_bsuid

cadena

El BSUID del chat propietario

Disponible en el menú Variables de chat.

2.3 Cambio de comportamiento para @contact.whatsapp_id

@contact.whatsapp_id sigue siendo solo por teléfono. Para los contactos que solo tienen BSUID (usuarios que han ocultado su número de teléfono), esta expresión devuelve cero.

Acción requerida: 

Los viajes que dependen de @contact.whatsapp_id deben actualizarse para usar @contact.bsuid cuando corresponda, o agregar comprobaciones nulas; consulte a continuación cómo.

Aquí hay una expresión de ejemplo para comprobar si el whatsapp_id de alguien es nulo:

is_nil_or_empty(@contact.whatsapp_id)

Aquí hay un ejemplo de su uso en una tarjeta de código:

card CodeBlock_1 do
 user_id = if(is_nil_or_empty(@contact.whatsapp_id), @contact.bsuid, @contact.whatsapp_id)
 text("ID de usuario: @user_id")
end

3. Solicitar el número de teléfono del usuario (próximamente)

Para recopilar números de teléfono de usuarios que solo usan nombre de usuario, Meta proporciona un nuevo tipo de mensaje llamado Solicitar contacto Información.

Puede solicitar el número de teléfono del usuario desde varios lugares del producto:

Ubicación

Como plantilla

Desde la bandeja de entrada

De viajes

El resultado es siempre el mismo: obtienes acceso al número de teléfono del usuario.

4. Plantillas de autenticación (OTP)

Las plantillas de autenticación no pueden utilizar BSUID. Al intentar enviar una plantilla de autenticación a un contacto que solo utiliza BSUID, se devuelve el código de metaerror 131062. Se requiere un número de teléfono.

Esto se aplica a todos los tipos de plantillas de autenticación:

  • Contraseñas de un solo uso (OTP)
  • Autenticación con un toque
  • Autenticación sin toque
  • Autenticación con copia de código

Estos errores aparecerán en los registros de viaje o en la bandeja de entrada al intentar enviar una plantilla de autenticación a un contacto sin un número de teléfono:

Para enviar plantillas de autenticación, primero debe recopilar el número de teléfono del usuario mediante el mensaje Solicitar información de contacto mencionado anteriormente en este artículo.

5. Cambios en BigQuery/Data Warehouse

5.1 Nuevas columnas

Las siguientes columnas nuevas se exportan automáticamente a BigQuery:

Tabla

Nueva Columna

Tipo

Descripción

contactos

bsuid

STRING

Usuario de ámbito empresarial ID

contactos

nombre de usuario

STRING

WhatsApp nombre de usuario

mensajes

from_bsuid

STRING

BSUID del remitente del mensaje: solo mensajes entrantes, NULL en mensajes salientes

urn_bsuid

STRING

BSUID del cliente en cada lado del mensaje (remitente para entrante, destinatario para saliente): la contraparte BSUID del urn_phone_number existente; use esto para consultas de unión

chats

owner_bsuid

STRING

BSUID del propietario de la conversación

5.2 Campos de teléfono que admiten valores NULL

Solo para BSUID contactos (usuarios que han ocultado su número de teléfono), las columnas basadas en teléfono serán NULL:

Columna

Comportamiento para contactos solo BSUID

contacts.urn

NULL (antes +teléfono)

messages.from_addr

NULL (era número de teléfono)

messages.urn_phone_number

NULL para ambas direcciones (entrante: no from_addr del que derivar; saliente: no hay destinatario telefónico del que derivar from)

chats.owner

NULL (era número de teléfono)

5.3 Impacto en las consultas existentes

Las consultas que SE UNEN en campos basados en teléfono no devolverán silenciosamente filas para contactos solo BSUID. También debes actualizar los JOIN para usar los campos BSUID.

(Nota: urn_phone_number y urn_bsuid son columnas desnormalizadas en la tabla de mensajes que normalizan los identificadores del cliente en todas las direcciones. urn_phone_number: from_addr para entrantes, destinatarios[0] para salientes; NULL cuando el teléfono no está disponible. urn_bsuid: BSUID del remitente para entrante, el BSUID de la conversación para la saliente).

Antes (ÚNETE solo por teléfono; se interrumpe para contactos solo BSUID):

-- Recupera todos los mensajes de un contacto (solo cuentas para el número de teléfono)

SELECT m.*, c.details

FROM mensajes m

UNIR contactos c ON m.urn_phone_number = c.urn

Después (teléfono + BSUID JOIN):

-- Recupera todos los mensajes de un contacto (cuentas tanto para el número de teléfono como para el bsuid)

SELECT m.*, COALESCE(cp.details, cb.details) AS detalles

FROM mensajes m

-- Mensajes se puede vincular su contacto por teléfono O bsuid O ambos

UNIRSE A LA IZQUIERDA contactos cp ON m.urn_phone_number = cp.urn

UNIRSE A LA IZQUIERDA contactos cb ON m.urn_bsuid = cb.bsuid

-- Opcional: conservar solo los mensajes que coincidan con un contacto 

WHERE cp.urn IS NOT NULL O cb.bsuid NO ES NULO

Nuevas capacidades de filtrado:

-- Encuentra todos los contactos que solo usan BSUID (sin número de teléfono)

DONDE contacts.bsuid NO ES NULO Y contacts.urn ES NULO

-- Filtra por BSUID específico

WHERE contacts.bsuid = 'US.13491208655302741918'

-- Todos los mensajes intercambiados con un usuario BSUID específico (ambas direcciones) 

WHERE message.urn_bsuid = 'US.13491208655302741918'

-- Filtrar por nombre de usuario

WHERE contact.username = 'alice_smith'

Le sugerimos que comience lo antes posible a hacer que sus sistemas utilicen el nuevo BSUID y sean resistentes a los usuarios que eligen ocultar su número de teléfono.

Si tiene preguntas mientras tanto, comuníquese con nosotros. Estamos aquí para ayudar.

¿Cómo lo hicimos?

15 de julio de 2026: nuevo cuadro de respuesta

Contacto