> ## Documentation Index
> Fetch the complete documentation index at: https://help.treble.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nombres de usuario de WhatsApp y BSUID (Business-Scoped User ID)

> Meta está cambiando la forma en que se identifica a los contactos de WhatsApp. Aquí te explicamos qué es un BSUID y un nombre de usuario de WhatsApp, qué cambia en tus mensajes entrantes y salientes, y cómo lo maneja Treble por ti.

Meta está implementando un cambio en la forma en que WhatsApp identifica a las personas con las que hablas. Hasta ahora, cada contacto se identificaba por su **número de teléfono**. Eso está cambiando: los usuarios de WhatsApp ahora pueden adoptar un **nombre de usuario** y, si lo hacen, pueden elegir no compartir su número de teléfono con las empresas.

Para que esto sea posible, Meta ahora envía un nuevo identificador permanente con cada contacto: el **Business-Scoped User ID (BSUID)**. Esta página te explica qué es, qué cambia, y qué (si algo) necesitas hacer.

<Note>
  **No se rompe nada si no haces nada.** Treble resuelve contactos, mantiene las conversaciones conectadas, y envía mensajes correctamente sin importar si un contacto se identifica por número de teléfono, nombre de usuario, o solo por BSUID. Esta página existe para que entiendas *por qué* puedes ver un contacto sin número de teléfono, y qué significa eso.
</Note>

## ¿Qué es un BSUID?

Un **Business-Scoped User ID** es un identificador único, generado por Meta, para un usuario de WhatsApp, específico para tu negocio. Es el único identificador que Meta siempre incluye con cada mensaje entrante o estado de mensaje, tenga el usuario un nombre de usuario configurado o no, y comparta su número o no.

* Se ve como una cadena con prefijo de código de país, por ejemplo `US.13491208655302741918`.
* Está **limitado a nivel de portafolio de negocio** — la misma persona escribiéndole a dos negocios distintos recibe un BSUID diferente para cada uno.
* **No se puede usar para plantillas de autenticación (OTP)** — esas siguen requiriendo un número de teléfono, ya que dependen de verificación basada en número.

## ¿Qué es un nombre de usuario de WhatsApp?

Un nombre de usuario es un identificador opcional y legible (como `@tunombre`) que un usuario de WhatsApp puede reservar para su cuenta, similar a un nombre de usuario en otras apps de mensajería o redes sociales. Un usuario que tiene un nombre de usuario **puede elegir ocultar su número de teléfono a las empresas** — en ese caso, vas a ver su nombre de usuario (si te escribe con uno configurado) y su BSUID, pero no su número.

<Info>
  Un nombre de usuario es opcional y lo controla el usuario. El número de teléfono también puede volver a aparecer más adelante — Meta lo muestra de nuevo si hubo una interacción reciente (dentro de los últimos 30 días) o si el contacto existe en la libreta de contactos de tu negocio.
</Info>

## Por qué está pasando esto

Hasta ahora, el número de teléfono era el ancla de todo: cómo se identificaba, se hacía match, y se le mandaban mensajes a un contacto. Meta está desacoplando eso — el número de teléfono pasa a ser *algo que un contacto puede compartir*, no algo con lo que siempre puedes contar.

<Steps>
  <Step title="Abril 2026">
    Los BSUID empiezan a aparecer en los webhooks entrantes para todos los contactos, tengan o no un nombre de usuario configurado.
  </Step>

  <Step title="29 de junio de 2026">
    Se abre globalmente la reserva de nombres de usuario — tanto para usuarios de WhatsApp como para negocios (mira las preguntas frecuentes más abajo para saber cómo configurar uno para tu propio número). Después, la activación se va habilitando por país en las semanas siguientes.
  </Step>

  <Step title="Julio 2026 en adelante">
    Las APIs de envío empiezan a aceptar un BSUID directamente (vía el parámetro `recipient`) como alternativa a un número de teléfono (`to`).
  </Step>
</Steps>

La adopción es completamente voluntaria del lado del usuario final — la mayoría de tus contactos van a seguir escribiéndote con su número de teléfono visible, exactamente como antes.

## Cómo identifica Treble a un contacto

Treble rastrea **tres** identificadores para cada contacto en vez de solo uno:

| Identificador      | De dónde sale                                      | ¿Siempre presente?                             |
| ------------------ | -------------------------------------------------- | ---------------------------------------------- |
| Número de teléfono | El clásico `wa_id`                                 | No — se omite una vez que el usuario lo oculta |
| Nombre de usuario  | El handle de WhatsApp, si el usuario configuró uno | No — es opcional                               |
| BSUID              | El campo `user_id` de Meta                         | Sí — siempre se envía                          |

Cuando Treble necesita encontrar o crear un contacto, revisa en este orden: **primero número de teléfono**, después **BSUID**, y después **nombre de usuario**. Esto mantiene el match de los contactos con teléfono exactamente como funcionaba siempre, y solo recurre a BSUID/nombre de usuario cuando no hay número con qué trabajar.

<div class="hr" />

## Mensajes entrantes

```mermaid theme={null}
flowchart LR
    A[El contacto envía un mensaje de WhatsApp] --> B{¿Incluye número de teléfono?}
    B -- Sí --> C[Match/creación de contacto por teléfono]
    B -- No --> D{¿El BSUID ya es conocido?}
    D -- Sí --> E[Match con el contacto existente por BSUID]
    D -- No --> F[Se crea un nuevo contacto solo con BSUID]
    C --> G[La conversación continúa normalmente]
    E --> G
    F --> G
```

Cuando llega un mensaje entrante sin número de teléfono, Treble:

1. Busca el contacto por BSUID. Si ya conoce ese BSUID (de un mensaje anterior, o porque el número de teléfono se recuperó antes), la conversación continúa exactamente igual que con cualquier otro contacto.
2. Si es la primera vez que ve ese BSUID, Treble crea un nuevo contacto anclado a él. El contacto se comporta con normalidad en tus flujos, reportes e historial de conversación — simplemente no va a tener número de teléfono hasta que haya uno disponible.
3. Si el contacto comparte un número de teléfono más adelante (ver la sección **Recuperar un número de teléfono** más abajo), Treble lo vincula automáticamente al contacto ya existente anclado por BSUID — no se crea ningún duplicado, y el historial de la conversación se mantiene intacto.

## Mensajes salientes

Enviar un mensaje funciona igual sea que apuntes a un contacto por número de teléfono o por BSUID — Treble maneja la diferencia automáticamente por ti. Las campañas, plantillas y automatizaciones no necesitan ningún cambio.

<Warning>
  **Las plantillas de autenticación (OTP) siempre requieren un número de teléfono.** Si un contacto solo tiene BSUID y necesitas mandarle una plantilla de autenticación, primero vas a necesitar su número de teléfono — mira la siguiente sección.
</Warning>

## Recuperar un número de teléfono

Si tienes un contacto sin número de teléfono y realmente lo necesitas (por ejemplo, para mandar una plantilla de autenticación, o para sincronizar con un CRM que solo hace match por teléfono), Treble soporta el botón de WhatsApp **Request Contact Info** (Solicitar información de contacto).

<Steps>
  <Step title="Envía el botón">
    Agrega un mensaje con el botón **Request Contact Info** a tu flujo, dirigido al contacto que solo tiene BSUID.
  </Step>

  <Step title="El contacto lo toca y da su consentimiento">
    Si acepta, WhatsApp te comparte su número de teléfono — esto siempre requiere consentimiento, el contacto tiene que aceptar explícitamente.
  </Step>

  <Step title="Treble lo guarda automáticamente">
    El número de teléfono se vincula al contacto existente de forma automática. Sin trabajo manual, sin contactos duplicados.
  </Step>
</Steps>

<Info>
  Este botón todavía está en beta privada del lado de Meta y se está desplegando de forma gradual. Una vez que esté disponible de forma general, no vas a necesitar hacer ningún cambio de tu lado para empezar a usarlo.
</Info>

<div class="hr" />

## Soporte en HubSpot

La [integración de Treble con HubSpot](/es/docs/integrations/hubspot/welcome) soporta contactos identificados por BSUID y nombre de usuario de fábrica.

* Se crean automáticamente dos properties nuevas de contacto en HubSpot la primera vez que sincroniza tu integración: **WhatsApp Business Scope ID** (`whatsapp_business_scope_id`) y **WhatsApp Username** (`whatsapp_username`).
* Cuando Treble busca un contacto en HubSpot, revisa primero el número de teléfono, y recurre a BSUID o nombre de usuario cuando no hay número con qué buscar.
* Los contactos nuevos creados desde Treble incluyen estos campos automáticamente, igual que pasa con `treble_created` y otras properties que administra Treble.
* Los contactos que ya existían en HubSpot se van completando con estos campos automáticamente a medida que interactúan — no hace falta ningún backfill manual de tu parte.

<Accordion title="¿Qué pasa si ya tengo una property custom con alguno de estos nombres?">
  Es poco probable, pero si la tienes, no es un conflicto de nuestro lado — Treble solo *lee* estos campos para hacer match de contactos, así que si ya estás llenando algo útil ahí, eso juega a tu favor.
</Accordion>

### La única limitación real

Si un contacto **ya existe en tu CRM** porque te escribió antes *con* su número de teléfono, y esa misma persona más adelante te manda un mensaje nuevo **sin** compartir su número (solo con nombre de usuario/BSUID), Treble no va a poder reconocer que es la misma persona — el contacto viejo nunca quedó etiquetado con su nombre de usuario/BSUID, y esa es la única información disponible en ese momento. En ese caso puntual, se crea un **contacto nuevo y separado** en tu CRM en vez de hacer match con el existente.

Esto no es algo que podamos evitar — es una consecuencia directa de que Meta le permita a los usuarios ocultar su número de teléfono después del hecho. También es un caso muy puntual: solo afecta a contactos que primero escribieron con número de teléfono y después lo ocultan, sin que haya habido antes ninguna interacción que le permitiera a Treble etiquetar su registro existente.

Para integraciones de CRM distintas a HubSpot, el match solo por número de teléfono sigue siendo el comportamiento actual — vamos a extender este mismo soporte de BSUID/nombre de usuario a nuestras otras integraciones de CRM próximamente.

<div class="hr" />

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Necesito cambiar algo en mis flujos o plantillas?">
    No. El envío, las conversaciones, los reportes y las plantillas siguen funcionando igual. Esto lo maneja Treble de forma transparente.
  </Accordion>

  <Accordion title="¿Se ven afectados mis reportes y métricas?">
    No, no cambia nada sobre cómo funcionan los reportes para ti.
  </Accordion>

  <Accordion title="¿Todavía puedo contactar a alguien que oculta su número de teléfono?">
    Sí — le mandas mensajes de la misma forma, Treble resuelve el destinatario correcto (teléfono, BSUID, o nombre de usuario) automáticamente.
  </Accordion>

  <Accordion title="¿Qué pasa con las plantillas de autenticación (OTP) para un contacto que solo tiene BSUID?">
    No se pueden enviar hasta que tengas un número de teléfono para ese contacto. Usa el botón de Request Contact Info (sección **Recuperar un número de teléfono** más arriba) para pedirlo, con su consentimiento.
  </Accordion>

  <Accordion title="¿Esto es algo que tengo que activar?">
    No — es una funcionalidad de la Plataforma de WhatsApp Business que está implementando Meta. Treble lo soporta automáticamente; no hay ninguna configuración que prender.
  </Accordion>

  <Accordion title="¿Esto afecta mi Phone Number ID o mis conversaciones existentes?">
    No. Tu Phone Number ID se mantiene igual, y las conversaciones existentes no se ven afectadas.
  </Accordion>

  <Accordion title="¿Puedo configurar un nombre de usuario para mi propio número de negocio?">
    Sí, si tu WABA/número cumple con los requisitos de elegibilidad de Meta (negocio verificado, nombre de visualización aprobado). Esto se configura directamente en el WhatsApp Manager de Meta (**Account tools → Phone numbers → selecciona el número → pestaña Profile → Username**), o vía la Username API de Meta — Treble no tiene una interfaz para reservarlo, ya que es una configuración de cuenta del lado de Meta.
  </Accordion>

  <Accordion title="Estoy en un país donde esto todavía no se implementó — ¿me afecta?">
    No para tu uso diario de Treble. El despliegue de *reserva y activación* de nombres de usuario está pasando gradualmente por país, con el cronograma completamente a cargo de Meta. Sin importar ese cronograma, el manejo que hace Treble de contactos solo-BSUID está activo en todos lados, así que ya estás cubierto para cuando llegue a tu mercado. Confirma directamente en el WhatsApp Manager de Meta el estado actual para un país en particular — no lo podemos garantizar desde nuestro lado.
  </Accordion>
</AccordionGroup>

<div class="hr" />

## Fuentes

Para el detalle técnico completo directamente de Meta:

* [Meta for Developers — Business-Scoped User IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/)

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Integración con HubSpot" icon="hubspot" href="/es/docs/integrations/hubspot/welcome">
    Mira todo lo que Treble sincroniza con HubSpot.
  </Card>

  <Card title="Meta y Treble" icon="facebook" href="/es/docs/meta/overview">
    Entiende el panorama completo de cómo Treble trabaja con Meta.
  </Card>
</CardGroup>
