Usar ID de usuario con ámbito de negocio (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 de las cargas útiles de webhook. Cada usuario controla si adopta 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 click-to-WhatsApp, admitan BSUID para que puedan continuar procesando mensajes de usuarios que adopten nombres de usuario. Para respaldar este cambio, Meta comenzó a agregar ID de usuario con ámbito de negocio (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 o no, y se puede utilizar 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 llamada con el usuario en los 30 días anteriores, 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, solicitudes de mensajes y llamadas, la libreta de contactos de Meta y los campos de webhook que tu integración necesita almacenar. Ejemplo de nombre de usuario de WhatsApp

Ejemplo de nombre de usuario de WhatsApp

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 en el 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 alpha-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 las siguientes 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 los portafolios vinculados para los cuales Meta lo habilitó.
Un número de teléfono comercial no puede usar un BSUID regular asignado a otro portafolio.

Las plantillas de autenticación con un solo toque (one-tap), sin toque (zero-tap) y copiar código requieren un número de teléfono. No envíes estos tipos de plantilla únicamente con un BSUID.

Para vincular portafolios y usar BSUID principales, solicita a tu punto de 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. Ejemplo de ID de usuario con ámbito de negocio

Ejemplo de ID de usuario con ámbito de negocio

Antes de comenzar

Almacena tu clave de API de YCloud en YCLOUD_API_KEY.
Usa un número de teléfono comercial de WhatsApp que pertenezca al mismo portafolio que el BSUID regular.
Suscribe tu endpoint 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 endpoints de mensajes de WhatsApp aceptan recipient:

Endpoint	Comportamiento
`POST /whatsapp/messages/sendDirectly`	Envía el mensaje de forma síncrona a la WhatsApp Business API.
`POST /whatsapp/messages`	Encola el mensaje para su envío asíncrono.

Establece recipient en un BSUID regular o en un BSUID principal. Omite to cuando quieras que YCloud se dirija al usuario mediante BSUID.

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`.
Ninguno de los dos campos	YCloud rechaza la solicitud.

Solicitar el número de teléfono de un usuario

Usa un mensaje de solicitud de información de contacto cuando tu flujo de trabajo necesite un número de teléfono que no se incluyó en un webhook. El usuario decide si compartirlo o no.

Usar un botón de plantilla

Añade 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 acepta parámetros al momento del envío.

{
  "type": "buttons",
  "buttons": [
    {
      "type": "REQUEST_CONTACT_INFO",
      "text": "Share Contact Info"
    }
  ]
}

Crea y aprueba la plantilla antes de enviarla. Consulta Plantilla para solicitar número de teléfono para ver una solicitud de plantilla completa.

Usar un mensaje interactivo

Envía un mensaje interactivo request_contact_info cuando no necesites una plantilla:

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 de contacto

Cuando el usuario comparte información de contacto, YCloud envía un evento whatsapp.inbound_message.received cuyo mensaje type es contacts. Para una respuesta a tu solicitud, contacts[].origin es contact_request.

{
  "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. Botón para solicitar información de contacto

Botón para solicitar información de contacto

Comprender 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 entonces 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 detiene el registro de nuevas. Volver a habilitarla comienza a recopilar nuevas entradas; no restaura los datos eliminados. Configuración de la libreta de contactos de Meta

Configuración de la libreta de contactos de Meta

Solicitudes de contacto y Local Storage

Cuando un usuario comparte su número de teléfono a través de un botón de solicitud de información de contacto, Meta añade el número de teléfono a la libreta de contactos si la función está habilitada. Para las empresas que usan 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 previo de enviar un mensaje por separado para capturar esta asociación. Consulta la documentación oficial de BSUID para conocer el comportamiento actual de Local Storage.

Eliminar una entrada de la libreta de contactos de Meta

Elimina una entrada de la libreta de contactos de Meta para un BSUID normal a través de un número de teléfono de WhatsApp Business con: DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}

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"

Usa un BSUID estándar para esta operación. No se admiten BSUID principales que contengan .ENT.. Codifica en la URL el signo inicial + en el número de teléfono como %2B cuando construyas la ruta manualmente. Una respuesta HTTP 200 siempre contiene success: true. Un valor de deleted igual a 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, mensajes ni registros comerciales de BSUID en YCloud. Tras la eliminación, los eventos de webhook para los números de teléfono comerciales en el mismo portafolio comercial de Meta ya no incluirán el número de teléfono del usuario y el BSUID juntos. La caché de 30 días de Meta aún puede suministrar ambos identificadores, y una interacción posterior puede volver a crear la entrada en 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: proporciona to o recipient, y to tiene prioridad cuando ambos están presentes.

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 consultar el ciclo de vida completo de las llamadas, consulta Gestionar llamadas de WhatsApp.

Procesar los campos de webhook de BSUID

Las siguientes cargas útiles de webhook de YCloud muestran los campos agregados o modificados para la compatibilidad con BSUID. Actualiza tu analizador sintáctico para aceptar los nuevos identificadores y gestionar los números de teléfono de clientes faltantes.

Marcador	Significado
`<ADDED>`	Un nuevo campo u objeto opcional introducido para la compatibilidad con BSUID.
`<CHANGED>`	Se puede omitir un campo existente de número de teléfono del cliente; su nombre no cambia.
Sin marcador	Campos existentes conservados para mostrar la estructura completa del evento.

Los ejemplos incluyen la envoltura del evento de YCloud y muestran dónde aparece cada campo. Los campos opcionales siguen las reglas de omisión que se indican a continuación. Elimina los comentarios // <ADDED> y // <CHANGED> antes de usar una carga útil como datos de prueba en JSON.

Evento	Campos opcionales que 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:

Un campo BSUID principal está ausente cuando los BSUID principales no están habilitados.
Un campo de destino de llamada o mensaje enviado puede estar ausente cuando 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 failed.
customerProfile.username está ausente cuando 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.

whatsapp.message.updated

El ejemplo muestra un mensaje entregado. <CHANGED> marca to como condicional cuando el número de teléfono no está disponible. El nuevo objeto customerProfile se omite para failed; su username también se omite para sent o cuando el usuario no tiene nombre de usuario.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "delivered",
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "name": "Example customer", // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.inbound_message.received

Almacena los nuevos identificadores de remitente junto con el nombre de perfil existente. El destinatario comercial to no cambia; el número de teléfono del cliente from se puede omitir. Consulta el ejemplo de cambio de número de teléfono a continuación para un mensaje system.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

whatsapp.user.preferences

La preferencia permanece bajo whatsappUserPreference. Utiliza los identificadores de usuario proporcionados incluso cuando contactPhoneNumber esté ausente.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "WABA_ID",
    "businessPhoneNumber": "+16315551111",
    "businessPhoneId": "BUSINESS_PHONE_ID",
    "contactName": "Example customer",
    "contactPhoneNumber": "+16315552222", // <CHANGED>
    "userId": "US.13491208655302741918", // <ADDED>
    "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1791532800000"
  }
}

whatsapp.call.connect

Para llamadas iniciadas por la empresa, los identificadores del cliente son toUserId y toParentUserId. Para llamadas iniciadas por el usuario, son fromUserId y fromParentUserId. Solo el campo de número de teléfono del cliente puede omitirse en estos ejemplos.

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "answer",
    "sdp": "SDP_CONTENT"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingConnect": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "sdpType": "offer",
    "sdp": "SDP_CONTENT"
  }
}

whatsapp.call.terminate

BUSINESS_INITIATED
USER_INITIATED

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "direction": "BUSINESS_INITIATED",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingTerminate": {
    "id": "CALL_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "direction": "USER_INITIATED",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "startTime": 1791532770000,
    "endTime": 1791532800000,
    "duration": 30,
    "status": "COMPLETED"
  }
}

whatsapp.call.status.updated

Los identificadores del destinatario son hermanos de recipientPhone bajo callingStatusUpdated.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "callingStatusUpdated": {
    "wabaId": "WABA_ID",
    "wacid": "wacid.EXAMPLE",
    "phoneId": "BUSINESS_PHONE_ID",
    "status": "RINGING",
    "recipientPhone": "+16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.group.participants_update

Una actualización de un solo participante puede incluir identificadores directamente bajo whatsappGroup. Los resultados por lotes los llevan en cada elemento en addedParticipants, removedParticipants o failedParticipants. Procesa el arreglo para la operación en el evento.

added
removed
failed

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "GROUP_ID@g.us",
    "addedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z",
    "waId": "16315552222", // <CHANGED>
    "recipientUserId": "US.13491208655302741918", // <ADDED>
    "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "status": "removed",
    "groupId": "GROUP_ID@g.us",
    "removedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        }
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "WABA_ID",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "failed",
    "groupId": "GROUP_ID@g.us",
    "failedParticipants": [
      {
        "input": "US.13491208655302741918",
        "waId": "16315552222", // <CHANGED>
        "recipientUserId": "US.13491208655302741918", // <ADDED>
        "parentRecipientUserId": "US.ENT.11815799212886844830", // <ADDED>
        "customerProfile": {
          "name": "Example customer",
          "username": "example_customer" // <ADDED>
        },
        "errors": [
          {
            "code": 131000,
            "title": "Something went wrong",
            "message": "Please retry later."
          }
        ]
      }
    ],
    "webhookTime": "2026-10-09T08:00:00.000Z"
  }
}

whatsapp.smb.history

Conserva el contenedor específico del evento: el historial entrante utiliza whatsappInboundMessage, mientras que el historial saliente utiliza whatsappMessage. Los campos salientes toUserId y toParentUserId son alias de compatibilidad de recipientUserId y parentRecipientUserId. Estos ejemplos muestran eventos que contienen mensajes; un fragmento de historial solo con metadatos puede omitir ambos objetos de mensaje.

Historial entrante
Historial saliente

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    }
  }
}

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830" // <ADDED>
  }
}

whatsapp.smb.app.state.sync

Esta carga útil se conserva de la documentación heredada de migración de BSUID. Este evento no aparece en el catálogo público actual de eventos a los que se puede suscribir; no lo agregues a enabledEvents según este ejemplo. Utiliza la estructura que aparece a continuación al mantener una integración que ya recibe esta carga útil heredada.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.app.state.sync",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappSmbAppStateSync": {
    "wabaId": "WABA_ID",
    "phoneNumber": "+16315551111",
    "stateSync": [
      {
        "contact": {
          "fullName": "Example customer",
          "firstName": "Example",
          "phoneNumber": "+16315552222", // <CHANGED>
          "userId": "US.13491208655302741918", // <ADDED>
          "parentUserId": "US.ENT.11815799212886844830", // <ADDED>
          "username": "example_customer" // <ADDED>
        },
        "action": "add",
        "timestamp": 1791532800000
      }
    ]
  }
}

whatsapp.smb.message.echoes

Estos son mensajes enviados desde la aplicación WhatsApp Business o un dispositivo complementario compatible. Los nombres de campo heredados toUserId y toParentUserId son alias de compatibilidad de recipientUserId y parentRecipientUserId. Conserva el perfil bajo whatsappMessage.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222", // <CHANGED>
    "type": "text",
    "text": {
      "body": "Order update received."
    },
    "sendTime": "2026-10-09T08:00:00.000Z",
    "status": "sent",
    "toUserId": "US.13491208655302741918", // <ADDED>
    "toParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": { // <ADDED>
      "username": "example_customer" // <ADDED>
    }
  }
}

Gestionar el cambio de número de teléfono de un usuario

Cuando whatsappInboundMessage.type es system y system.type es user_changed_number, los campos de remitente externos identifican la identidad del usuario anterior. Los campos anidados system contienen los nuevos BSUID y, cuando esté disponible, el nuevo número de teléfono. Utiliza los nombres de campo user_id y parent_user_id dentro de system.

{
  "id": "evt_EXAMPLE",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315552222", // <CHANGED>
    "to": "+16315551111",
    "type": "system",
    "sendTime": "2026-10-09T08:00:00.000Z",
    "fromUserId": "US.13491208655302741918", // <ADDED>
    "fromParentUserId": "US.ENT.11815799212886844830", // <ADDED>
    "customerProfile": {
      "name": "Example customer",
      "username": "example_customer" // <ADDED>
    },
    "system": {
      "type": "user_changed_number",
      "wa_id": "16315553333", // <CHANGED>
      "user_id": "US.13491208655302741919", // <ADDED>
      "parent_user_id": "US.ENT.11815799212886844831" // <ADDED>
    }
  }
}

Trata parent_user_id como opcional. El nuevo número de teléfono en wa_id también se puede omitir, así que usa user_id y cualquier parent_user_id proporcionado para actualizar la asignación de identidades. Conserva los valores antiguos y nuevos el tiempo suficiente para conciliar las conversaciones existentes y actualizar de manera idempotente tu almacén de identidades.

Nombres de usuario comerciales

Un nombre de usuario comercial ayuda a los clientes a encontrar tu empresa en WhatsApp. No oculta el número de teléfono de tu empresa. Cada número de teléfono puede tener un nombre de usuario, y dos números de teléfono de WhatsApp no pueden compartir un mismo nombre de usuario. El nombre de usuario de un consumidor puede cambiar sin cambiar el BSUID del usuario. Conserva el nombre de usuario como información del perfil en lugar de usarlo como tu clave de identidad. Consulta Reclamar un nombre de usuario comercial para conocer las reglas de formato de 3 a 35 caracteres y el proceso de reclamación y revisión. Ejemplo de nombre de usuario comercial

Nombres de usuario reservados

Puedes reclamar un nombre de usuario elegible reservado por Meta o elegir otro nombre de usuario para tu marca. Utiliza el Administrador de WhatsApp, Meta Business Suite o la API de nombres de usuario. La aprobación en sí misma no significa que un nombre de usuario esté activo para los clientes. Si el nombre de usuario reservado pertenece a tu página de Facebook o cuenta de Instagram, vincula tu número de teléfono comercial a esa página o cuenta antes de reclamarlo. Puedes vincularlo mientras reclamas 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. Necesitas control total o acceso parcial básico con el permiso manage_phone.

Prioridad de visualización en la ventana de chat

WhatsApp muestra la identidad comercial en este orden:

El nombre guardado en los contactos del cliente.
El nombre comercial verificado o el nombre de la cuenta comercial oficial.
El nombre de usuario comercial.
El número de teléfono.

Tu número de teléfono comercial permanece visible en el perfil de empresa.

Lista de verificación para la migración

Agrega cada campo de webhook relacionado con BSUID a tu modelo de deserialización como un campo opcional.
Almacena los BSUID regulares y principales por separado de los números de teléfono y nombres de usuario.
Indexa la identidad del cliente por portafolio y BSUID. No trates un BSUID como un identificador portable globalmente.
Enruta las solicitudes de mensajes y llamadas mediante to o recipient, y prueba la regla de precedencia de to.
Prueba usuarios que solo tienen nombre de usuario, números de teléfono ausentes, cambios de número de teléfono, BSUID principales ausentes, webhooks duplicados y la recreación de la libreta de contactos.

Ejemplos de estado de mensajes

Inspecciona los payloads de mensajes enviados, entregados, leídos y fallidos.

Ejemplos de mensajes entrantes

Inspecciona contactos, actualizaciones del sistema y otros payloads entrantes.

Primeros pasos

Guías

Endpoints

Webhooks

Usar ID de usuario con ámbito de negocio (BSUID)

Por qué existen los BSUID

Comprender los identificadores

Antes de comenzar

Enviar un mensaje con un BSUID

Solicitar el número de teléfono de un usuario

Usar un botón de plantilla

Usar un mensaje interactivo

Gestionar la respuesta de contacto

Comprender la libreta de contactos de Meta

Solicitudes de contacto y Local Storage

Eliminar una entrada de la libreta de contactos de Meta

Iniciar una llamada con un BSUID

Procesar los campos de webhook de BSUID

Gestionar el cambio de número de teléfono de un usuario

Nombres de usuario comerciales

Nombres de usuario reservados

Prioridad de visualización en la ventana de chat

Lista de verificación para la migración

Ejemplos de estado de mensajes

Ejemplos de mensajes entrantes

​Por qué existen los BSUID

​Comprender los identificadores

​Antes de comenzar

​Enviar un mensaje con un BSUID

​Solicitar el número de teléfono de un usuario

​Usar un botón de plantilla

​Usar un mensaje interactivo

​Gestionar la respuesta de contacto

​Comprender la libreta de contactos de Meta

​Solicitudes de contacto y Local Storage

​Eliminar una entrada de la libreta de contactos de Meta

​Iniciar una llamada con un BSUID

​Procesar los campos de webhook de BSUID

​Gestionar el cambio de número de teléfono de un usuario

​Nombres de usuario comerciales

​Nombres de usuario reservados

​Prioridad de visualización en la ventana de chat

​Lista de verificación para la migración

Ejemplos de estado de mensajes

Ejemplos de mensajes entrantes

Por qué existen los BSUID

Comprender los identificadores

Antes de comenzar

Enviar un mensaje con un BSUID

Solicitar el número de teléfono de un usuario

Usar un botón de plantilla

Usar un mensaje interactivo

Gestionar la respuesta de contacto

Comprender la libreta de contactos de Meta

Solicitudes de contacto y Local Storage

Eliminar una entrada de la libreta de contactos de Meta

Iniciar una llamada con un BSUID

Procesar los campos de webhook de BSUID

Gestionar el cambio de número de teléfono de un usuario

Nombres de usuario comerciales

Nombres de usuario reservados

Prioridad de visualización en la ventana de chat

Lista de verificación para la migración