> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Usar identificadores de usuario con ámbito empresarial
> Envía mensajes y realiza llamadas de WhatsApp con BSUID, solicita números de teléfono, gestiona entradas de la libreta de contactos de Meta y procesa campos de webhook de BSUID.
## Por qué existen los BSUID
WhatsApp implementará nombres de usuario opcionales en 2026. Cuando un usuario adopta un
nombre de usuario, WhatsApp puede mostrar el nombre de usuario en lugar del número de teléfono del usuario
y puede omitir el número de teléfono en las cargas útiles de webhooks. Cada usuario decide si
adoptar un nombre de usuario, por lo que las empresas no pueden depender de los números de teléfono como la única forma
de identificar a los clientes. Por lo tanto, Meta exige que las empresas y socios de WhatsApp Business Platform,
así como los anunciantes de anuncios de clic a WhatsApp, admitan
BSUID para que puedan seguir procesando mensajes de usuarios que adopten nombres de usuario.
Para respaldar este cambio, Meta comenzó a agregar identificadores de usuario con ámbito empresarial (BSUID) a
las cargas útiles de webhook a principios de abril de 2026. Un BSUID es un identificador de backend para un
usuario de WhatsApp dentro de un portafolio comercial de Meta. Meta lo incluye en los webhooks de
mensajes independientemente de si el usuario ha adoptado un nombre de usuario, y se puede usar para
enviar mensajes al usuario cuando su número de teléfono no está disponible.
Los nombres de usuario y los BSUID tienen ciclos de vida diferentes. Un usuario puede cambiar su nombre de usuario
sin cambiar su número de teléfono o BSUID. Si el usuario cambia su número de
teléfono, Meta genera un nuevo BSUID. Almacena estos identificadores por separado y
actualiza su asociación cuando recibas un evento del sistema de cambio de número de teléfono.
Un número de teléfono aún puede aparecer cuando el número de teléfono comercial ha intercambiado un
mensaje o una llamada con el usuario en los últimos 30 días, o cuando la libreta de contactos de Meta
contiene al usuario. Trata los campos de número de teléfono y nombre de usuario como condicionales,
y actualiza los analizadores y el almacenamiento de identidades para aceptar BSUID junto con cualquier otro
identificador presente.
Esta guía cubre las reglas de identidad de BSUID, las solicitudes de mensajes y llamadas, la libreta
de contactos de Meta y los campos de webhook que tu integración necesita almacenar.
## Comprender los identificadores
| Identificador | Ámbito | Ejemplo | Cuándo usarlo |
| - | - | - | - |
| Número de teléfono | Una cuenta de WhatsApp | `+16315551111` | Úsalo cuando el número de teléfono esté disponible y la operación lo requiera. |
| BSUID | Un portafolio comercial de Meta y un usuario de WhatsApp | `US.13491208655302741918` | Úsalo desde cualquier número de teléfono comercial del mismo portafolio. |
| BSUID principal | Un conjunto de portafolios comerciales de Meta vinculados y un usuario de WhatsApp | `US.ENT.11815799212886844830` | Úsalo solo después de que Meta habilite los BSUID principales para los portafolios vinculados. |
Meta genera automáticamente BSUID regulares. Cada BSUID comienza con el código de país de
dos letras ISO 3166 alfa-2 del usuario, seguido de un punto y hasta 128
caracteres alfanuméricos. Conserva el valor completo. No elimines ni modifiques
el prefijo de país, el punto ni los caracteres del identificador.
Los BSUID tienen estas reglas de ciclo de vida:
* Un BSUID es único para un par de portafolio comercial y usuario.
* El BSUID de un usuario cambia cuando el usuario cambia su número de teléfono.
* Un BSUID principal funciona en todos los portafolios vinculados para los que Meta lo haya habilitado.
* Un número de teléfono comercial no puede usar un BSUID regular asignado a otro
portafolio.
Las plantillas de autenticación de un toque, cero toques y copiar código requieren un número
de teléfono. No envíes estos tipos de plantilla solo con un BSUID.
Para vincular portafolios y usar BSUID principales, solicita a tu contacto de Meta que
verifique tu elegibilidad. Puedes continuar usando BSUID regulares dentro de sus
portafolios originales después de que Meta habilite los BSUID principales.
## Antes de comenzar
* Almacena tu clave de API de YCloud en `YCLOUD_API_KEY`.
* Usa un número de teléfono comercial de WhatsApp propiedad del mismo portafolio que el
BSUID regular.
* Suscribe tu punto de conexión de webhook a los eventos de WhatsApp que utilice tu integración.
* Trata cada nuevo campo de BSUID, BSUID principal, número de teléfono y nombre de usuario como
opcional al deserializar webhooks.
* Almacena el BSUID regular y el BSUID principal de forma independiente cuando ambos estén presentes.
## Enviar un mensaje con un BSUID
Ambos puntos de conexión de mensajes de WhatsApp aceptan `recipient`:
| Punto de conexión | Comportamiento |
| - | - |
| `POST /whatsapp/messages/sendDirectly` | Envía el mensaje de forma sincrónica a la WhatsApp Business API. |
| `POST /whatsapp/messages` | Encola el mensaje para su envío asincrónico. |
Establece `recipient` en un BSUID regular o en un BSUID principal. Omite `to` cuando
quieras que YCloud se dirija al usuario mediante BSUID.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
--header "X-API-Key: $YCLOUD_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"from": "+16315551111",
"recipient": "US.13491208655302741918",
"type": "text",
"text": {
"body": "Hello from YCloud!"
}
}'
```
Usa el mismo cuerpo de solicitud con `POST /whatsapp/messages` para encolar el mensaje.
| Entrada | Resultado |
| - | - |
| Solo `to` | YCloud envía al número de teléfono. |
| Solo `recipient` | YCloud envía al BSUID o BSUID principal. |
| Tanto `to` como `recipient` | YCloud usa `to` e ignora `recipient`. |
| Ningún campo | YCloud rechaza la solicitud. |
## Solicitar el número de teléfono de un usuario
Utilice un mensaje de solicitud de información de contacto (request-contact-info) cuando su flujo de trabajo necesite un número de teléfono que no se incluyó en un webhook. El usuario decide si compartirlo.
### Usar un botón de plantilla
Agrega un botón `REQUEST_CONTACT_INFO` a una plantilla de utilidad o marketing. El texto del botón es fijo como `Share Contact Info`, y el botón no admite parámetros al momento del envío.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "buttons",
"buttons": [
{
"type": "REQUEST_CONTACT_INFO",
"text": "Share Contact Info"
}
]
}
```
Crea y aprueba la plantilla antes de enviarla. Consulta
[Solicitar plantilla de número de teléfono](/es/api-reference/guides/examples/api-examples/whatsapp-template-creation-examples#request-phone-number-template)
para ver una solicitud de plantilla completa.
### Usar un mensaje interactivo
Envía un mensaje interactivo de `request_contact_info` cuando no necesites una plantilla:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
https://api.ycloud.com/v2/whatsapp/messages/sendDirectly \
--header "X-API-Key: $YCLOUD_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"from": "+16315551111",
"recipient": "US.13491208655302741918",
"type": "interactive",
"interactive": {
"type": "request_contact_info",
"body": {
"text": "Please share your phone number."
},
"action": {
"name": "request_contact_info"
}
}
}'
```
### Gestionar la respuesta del contacto
Cuando el usuario comparte información de contacto, YCloud envía un evento `whatsapp.inbound_message.received` cuyo `type` de mensaje es `contacts`.
Para una respuesta a tu solicitud, `contacts[].origin` es `contact_request`.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "whatsapp.inbound_message.received",
"whatsappInboundMessage": {
"fromUserId": "US.13491208655302741918",
"type": "contacts",
"contacts": [
{
"origin": "contact_request",
"phones": [
{
"phone": "+16315551111",
"wa_id": "16315551111"
}
]
}
]
}
}
```
Valida la firma del evento, confírmalo con una respuesta `2xx` y procesa el número de teléfono de forma asíncrona. Un contacto compartido directamente desde WhatsApp también puede incluir una vCard.
## Entender la libreta de contactos de Meta
La libreta de contactos de Meta almacena la asociación entre el número de teléfono de un usuario y el BSUID. Con la función habilitada, enviar o recibir un mensaje o una llamada usando el número de teléfono del usuario registra ambos identificadores. Meta puede luego incluir esa asociación en los webhooks incluso después de que el usuario adopte un nombre de usuario.
Las libretas de contactos pertenecen a portafolios comerciales individuales. Los portafolios vinculados no comparten ni sincronizan sus entradas: registra la asociación de forma independiente en cada portafolio.
Meta conserva las entradas hasta que desactives la función o desactives tu cuenta.
Puedes desactivarla en **Meta Business Suite > Configuración del negocio > Información del
negocio**. Desactivar la función elimina las entradas almacenadas y deja de registrar
nuevas. Volver a activarla comienza a recopilar nuevas entradas; no restaura
los datos eliminados.
### Solicitudes de contacto y almacenamiento local
Cuando un usuario comparte su número de teléfono a través de un botón de solicitud de información de contacto (request-contact-info), Meta agrega el número de teléfono a la libreta de contactos si la función está habilitada. Para las empresas que utilizan Local Storage, Meta extrae el número de teléfono de la vCard compartida y lo almacena en la libreta de contactos en los centros de datos de Meta. El resto de los datos de la vCard no se conservan más allá del período de retención estándar.
Meta eliminó el requisito anterior de enviar un mensaje por separado para capturar esta asociación. Consulta la [documentación oficial de BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#contact-book) para conocer el comportamiento actual de Local Storage.
### Eliminar una entrada de la libreta de contactos de Meta
Elimine una entrada de la libreta de contactos de Meta para un BSUID regular a través de un número de teléfono comercial de WhatsApp con:
`DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}`
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request DELETE \
"https://api.ycloud.com/v2/whatsapp/phoneNumbers/WABA_ID/%2B16315551111/contactBook/US.13491208655302741918" \
--header "X-API-Key: $YCLOUD_API_KEY" \
--header "Accept: application/json"
```
Utilice un BSUID estándar para esta operación. No se admiten BSUID principales que contengan `.ENT.`. Codifique en formato URL el signo `+` inicial en el número de teléfono como `%2B` cuando construya la ruta manualmente.
Una respuesta HTTP `200` siempre contiene `success: true`. Un valor de `deleted` de
`true` significa que Meta eliminó una entrada coincidente. Un valor de `false` significa que Meta
procesó la solicitud pero no encontró ninguna entrada coincidente.
Eliminar la entrada no borra los contactos de YCloud, los mensajes ni los registros comerciales de BSUID. Después de la eliminación, los eventos de webhook para los números de teléfono comerciales en la misma cartera comercial de Meta ya no incluirán el número de teléfono del usuario y el BSUID juntos. La memoria caché de 30 días de Meta aún puede suministrar ambos identificadores, y una interacción posterior puede volver a crear la entrada de la libreta de contactos.
## Iniciar una llamada con un BSUID
`POST /whatsapp/calls/connect` también acepta `recipient`. Se aplican las mismas reglas de destino: proporcione `to` o `recipient`, y `to` tiene prioridad cuando ambos están presentes.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
https://api.ycloud.com/v2/whatsapp/calls/connect \
--header "X-API-Key: $YCLOUD_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"from": "+16315551111",
"recipient": "US.13491208655302741918",
"sdpType": "offer",
"sdp": "SDP_OFFER"
}'
```
Para conocer el ciclo de vida completo de las llamadas, consulta
[Administrar llamadas de WhatsApp](/es/api-reference/guides/whatsapp-platform/manage-whatsapp-calls).
## Procesar los campos de webhook de BSUID
Los siguientes campos son adiciones a las cargas útiles de eventos existentes. Mantén el objeto de nivel superior del evento al definir tu modelo de datos.
| Evento | Campos opcionales para almacenar |
| - | - |
| `whatsapp.message.updated` | `whatsappMessage.recipientUserId`, `whatsappMessage.parentRecipientUserId`, `whatsappMessage.customerProfile.name`, `whatsappMessage.customerProfile.username` |
| `whatsapp.inbound_message.received` | `whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username` |
| `whatsapp.user.preferences` | `whatsappUserPreference.userId`, `whatsappUserPreference.parentUserId` |
| `whatsapp.call.connect` | `callingConnect.toUserId`, `callingConnect.toParentUserId`, `callingConnect.fromUserId`, `callingConnect.fromParentUserId` |
| `whatsapp.call.terminate` | `callingTerminate.toUserId`, `callingTerminate.toParentUserId`, `callingTerminate.fromUserId`, `callingTerminate.fromParentUserId` |
| `whatsapp.call.status.updated` | `callingStatusUpdated.recipientUserId`, `callingStatusUpdated.parentRecipientUserId` |
| `whatsapp.group.participants_update` | `whatsappGroup.recipientUserId`, `whatsappGroup.parentRecipientUserId`, `whatsappGroup.customerProfile.username`, y los campos `recipientUserId` y `parentRecipientUserId` en `whatsappGroup.addedParticipants[]`, `whatsappGroup.removedParticipants[]` y `whatsappGroup.failedParticipants[]` |
| `whatsapp.smb.history` | `whatsappInboundMessage.fromUserId`, `whatsappInboundMessage.fromParentUserId`, `whatsappInboundMessage.customerProfile.username`, `whatsappMessage.toUserId`, `whatsappMessage.toParentUserId` |
| `whatsapp.smb.app.state.sync` | `whatsappSmbAppStateSync.stateSync[].contact.userId`, `whatsappSmbAppStateSync.stateSync[].contact.parentUserId`, `whatsappSmbAppStateSync.stateSync[].contact.username` |
| `whatsapp.smb.message.echoes` | `whatsappMessage.toUserId`, `whatsappMessage.toParentUserId`, `whatsappMessage.customerProfile.username` |
Aplica estas reglas de omisión:
* El campo de BSUID principal no aparece cuando los BSUID principales no están habilitados.
* El campo del destino de un mensaje o llamada enviados puede estar ausente si te dirigiste al usuario
por número de teléfono.
* `customerProfile` aparece en las actualizaciones de mensajes `sent`, `delivered` y `read`,
pero no en las actualizaciones de `failed`.
* `customerProfile.username` no está presente si el usuario no ha habilitado los nombres de usuario.
También está ausente de las actualizaciones de estado `sent`.
* Un número de teléfono puede estar ausente incluso cuando el BSUID correspondiente está presente.
### Gestionar el cambio de número de teléfono de un usuario
Cuando un mensaje entrante tenga `type: system` y `system.type: user_changed_number`, reemplace el mapeo de identidad anterior con los nuevos valores. Los nombres de campo BSUID del objeto `system` se mantienen en el formato snake\_case de Meta.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "system",
"system": {
"type": "user_changed_number",
"wa_id": "16315552222",
"user_id": "US.13491208655302741919",
"parent_user_id": "US.ENT.11815799212886844831"
}
}
```
Trate `parent_user_id` como opcional. Conserve los valores antiguos y nuevos el tiempo suficiente para conciliar las conversaciones existentes y actualizar de forma idempotente su almacén de identidades.
## Nombres de usuario de la empresa
Un nombre de usuario de la empresa ayuda a los clientes a encontrar su negocio en WhatsApp. No oculta el número de teléfono de su empresa. Cada número de teléfono puede tener un nombre de usuario, y un nombre de usuario no se puede compartir entre dos números de teléfono de WhatsApp.
El nombre de usuario de un consumidor puede cambiar sin que cambie el BSUID del usuario. Mantenga el nombre de usuario como información de perfil en lugar de usarlo como su clave de identidad.
Consulte [Reclamar un nombre de usuario de la empresa](/es/documentation/channels/whatsapp-accounts-management/phone-number-management/claim-a-business-username) para ver las reglas de formato de 3 a 35 caracteres y el proceso de reclamación y revisión.
### Nombres de usuario reservados
Puede reclamar un nombre de usuario apto reservado por Meta o elegir otro nombre de usuario para su marca. Utilice WhatsApp Manager, Meta Business Suite o la API de nombres de usuario. La aprobación no significa por sí sola que un nombre de usuario esté activo para los clientes.
Si el nombre de usuario reservado pertenece a su página de Facebook o cuenta de Instagram, vincule el número de teléfono de su empresa a esa página o cuenta antes de reclamarlo. Puede vincularlo al reclamar el nombre de usuario en Meta Business Suite o WhatsApp Manager, o [agregar el número de teléfono a la página o cuenta](https://www.facebook.com/business/help/4631406400243963). Necesita control total o acceso parcial básico con permiso `manage_phone`.
### Prioridad de visualización en la ventana de chat
WhatsApp muestra la identidad comercial en este orden:
1. El nombre guardado en los contactos del cliente.
2. El nombre comercial verificado o el nombre de la cuenta oficial de empresa.
3. El nombre de usuario de la empresa.
4. El número de teléfono.
El número de teléfono de su empresa permanece visible en el perfil de empresa.
## Lista de verificación de migración
1. Agregue cada campo de Webhook relacionado con BSUID a su modelo de deserialización como un
campo opcional.
2. Almacene los BSUID normales y principales por separado de los números de teléfono y los nombres de usuario.
3. Indexe la identidad del cliente por portafolio y BSUID. No trate un BSUID como un
identificador portátil globalmente.
4. Enrute las solicitudes de mensajes y llamadas a través de `to` o `recipient`, y pruebe
la regla de precedencia `to`.
5. Pruebe usuarios solo con nombre de usuario, números de teléfono faltantes, cambios de número de teléfono, BSUID principales
faltantes, webhooks duplicados y recreación de la libreta de contactos.
Inspeccione las cargas útiles de mensajes enviados, entregados, leídos y fallidos.
Inspeccione contactos, actualizaciones del sistema y otras cargas útiles entrantes.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.