Business-scoped user IDs (BSUID)

WhatsApp comenzará a adoptar usernames gradualmente en 2026. Para soportarlos, Meta introdujo un identificador de usuario de backend llamado Business-scoped user ID (BSUID), que identifica de forma única a un usuario de WhatsApp y está ligado a un negocio específico. Este documento describe cómo estos cambios afectan las requests, responses y webhooks de la API.

El canal ISV soporta los identificadores y capacidades introducidas por WhatsApp Business Platform para 2026: BSUID, Parent BSUID, usernames, Contact Book, solicitudes de contacto y nuevos campos de webhooks, sin romper la compatibilidad con integraciones que siguen usando número telefónico.

Referencia oficial de Meta: Business-scoped user IDs.

Resumen rápido

Área	Cambio
Identificadores	Se soportan `user_id` como BSUID, `parent_user_id` como Parent BSUID y `username`.
Envío de mensajes	`/messages` y `/marketing_messages` aceptan `recipient` para BSUID o Parent BSUID.
Compatibilidad	El campo `to` se mantiene. Si se envían `to` y `recipient`, el número telefónico en `to` tiene prioridad.
Plantillas e interactivos	Se soportan mensajes interactivos y plantillas con `REQUEST_CONTACT_INFO`.
Llamadas	Se preservan campos como `to_user_id`, `to_parent_user_id`, `from_user_id` y `from_parent_user_id`.
Webhooks	Se exponen los nuevos campos recibidos desde Meta, incluso cuando no viene número telefónico.
Business Username	Se agregan endpoints para consultar, adoptar/cambiar y eliminar el username de empresa.
Contact Book	Se agrega endpoint para eliminar contactos por BSUID.

Identificadores soportados

Campo	Descripción
`to`	Número telefónico del usuario. Se mantiene por compatibilidad.
`recipient`	BSUID o Parent BSUID usado como destinatario en mensajes salientes.
`user_id`	Business Scoped User ID (BSUID) del usuario.
`parent_user_id`	Parent BSUID del usuario cuando el cliente está enrolado.
`username`	Username del usuario o de la empresa, según el contexto del payload.
`from_user_id`	BSUID del emisor en mensajes/webhooks entrantes.
`from_parent_user_id`	Parent BSUID del emisor en mensajes/webhooks entrantes.
`recipient_user_id`	BSUID del destinatario en webhooks de estado.
`recipient_parent_user_id`	Parent BSUID del destinatario en webhooks de estado.

Formato del BSUID

Los BSUIDs se generan automáticamente, están prefijados con el código de país ISO 3166 alpha-2 del usuario y un punto, seguidos de hasta 128 caracteres alfanuméricos. Por ejemplo: US.13491208655302741918.

Los Parent BSUIDs siguen el mismo formato pero incluyen ENT entre el código de país y el identificador. Por ejemplo: US.ENT.11815799212886844830.

Envío de mensajes con `recipient`

Los endpoints existentes de mensajes preservan el contrato anterior y agregan soporte para BSUID/Parent BSUID mediante recipient.

Endpoint	Cambio
`POST /{v}/{did}/messages`	Permite enviar mensajes usando `to`, `recipient` o ambos.
`POST /{v}/{did}/marketing_messages`	Permite enviar mensajes de marketing usando `recipient`.

Mensaje usando BSUID

Request

POST /{v}/{did}/messages

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/v21.0/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "recipient": "CL.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hola, este mensaje se envía usando BSUID."
    }
  }'

Mensaje usando número telefónico y BSUID

Cuando se informan ambos campos, to mantiene prioridad para preservar el comportamiento histórico.

Request

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/v21.0/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+56912345678",
    "recipient": "CL.13491208655302741918",
    "type": "text",
    "text": {
      "body": "Hola, este mensaje mantiene compatibilidad con to."
    }
  }'

Mensaje interactivo para solicitar información de contacto

Request

POST /{v}/{did}/messages

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/v21.0/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "recipient": "US.13491208655302741918",
    "type": "interactive",
    "interactive": {
      "type": "request_contact_info",
      "body": {
        "text": "Comparte tu número para continuar."
      },
      "action": {
        "name": "request_contact_info"
      }
    }
  }'

Plantillas con `REQUEST_CONTACT_INFO`

El endpoint de plantillas permite crear plantillas que solicitan información de contacto al usuario mediante un botón REQUEST_CONTACT_INFO (disponible en categorías utility y marketing).

Endpoint	Cambio
`POST /message_templates/{v}/{did}`	Permite botones de tipo `REQUEST_CONTACT_INFO`.

Request

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/v21.0/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "request_contact_info_template",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Share your phone number to continue."
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "REQUEST_CONTACT_INFO"
          }
        ]
      }
    ]
  }'

Los botones REQUEST_CONTACT_INFO no son personalizables: el label se renderiza automáticamente en el idioma del destinatario, por lo que no es necesario enviar parámetros al enviar la plantilla.

Endpoints de Business Username y Contact Book

Estos endpoints se exponen bajo /business_identifiers/{version}/{did}. Requieren la misma autenticación y validación de canal que los endpoints ISV protegidos.

Operación	Endpoint	Descripción
Obtener username	`GET /business_identifiers/{v}/{did}/username`	Consulta el username asociado al número de negocio.
Adoptar o cambiar username	`POST /business_identifiers/{v}/{did}/username`	Envía el payload requerido por Meta para adoptar o cambiar el username.
Eliminar username	`DELETE /business_identifiers/{v}/{did}/username`	Elimina el username asociado al número de negocio.
Sugerencias de username	`GET /business_identifiers/{v}/{did}/username_suggestions`	Obtiene sugerencias de username disponibles.
Parent BSUID Accounts	`GET /business_identifiers/{v}/{did}/parent-bsuid-accounts?business_id={business_id}`	Consulta las cuentas Parent BSUID asociadas al negocio.
Eliminar Contact Book	`DELETE /business_identifiers/{v}/{did}/contact_book?bsuid={BSUID}`	Elimina un contacto de la libreta usando su BSUID.

Adoptar o cambiar username

Request

POST /business_identifiers/{v}/{did}/username

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/business_identifiers/v21.0/{did}/username' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "mi.negocio"
  }'

Response

Success (200)

{
  "status": "approved"
}

status puede ser approved (aprobado y visible) o reserved (reservado, aún no visible hasta que la feature esté disponible).

Errores de username

Código	Descripción
`147001`	Username no disponible (ya reclamado o no pasa los checks internos).
`147002`	La cuenta no es elegible para solicitar un username (requiere un messaging limit mayor).
`147003`	Cuenta de Facebook no vinculada al número.
`147004`	Cuenta de Instagram no vinculada al número.
`147005`	Se requiere transferencia de username (en uso por otro número del mismo portfolio).

Eliminar contacto por BSUID

Request

DELETE /business_identifiers/{v}/{did}/contact_book?bsuid={BSUID}

curl --request DELETE \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/business_identifiers/v21.0/{did}/contact_book?bsuid=US.13491208655302741918' \
  --header 'Authorization: <JWT>'

Response

Success (200)

{
  "messaging_product": "whatsapp",
  "success": true,
  "deleted": true
}

success — true si el request se procesó correctamente.
deleted — true si la entrada existía y fue eliminada; false si no se encontró ninguna entrada para ese BSUID.

Campos nuevos en webhooks

Los webhooks preservan los campos nuevos que envía Meta. Esto permite recibir eventos aunque el número telefónico no venga informado en el payload.

Webhook	Campos relevantes
`messages`	`user_id`, `parent_user_id`, `username`, `from_user_id`, `from_parent_user_id`.
`statuses`	`recipient_user_id`, `recipient_parent_user_id`, `username`.
`contacts`	`origin`, `vcard`, `from_user_id`, `from_parent_user_id`.
`system`	Cambios de número que pueden implicar cambio de BSUID.
`business_username_updates`	Cambios de estado del username de empresa.
`user_preferences`	Preferencias del usuario, incluyendo identificadores BSUID/Parent BSUID cuando Meta los informa.

Webhook de estado (`statuses`)

Los webhooks de estado de mensaje (sent, delivered, read, failed) incluyen los identificadores del destinatario:

Campo	Descripción
`contacts[].user_id`	BSUID del usuario (siempre presente).
`contacts[].parent_user_id`	Parent BSUID, si está habilitado.
`contacts[].username`	Username, si el usuario lo adoptó (en `delivered`/`read`).
`statuses[].recipient_user_id`	BSUID del destinatario.
`statuses[].recipient_parent_user_id`	Parent BSUID del destinatario, si está habilitado.

El campo recipient_user_id se omite en webhooks failed cuando el mensaje se envió al número telefónico. El bloque contacts se omite completamente en los failed.

Webhook de contactos (`contacts`)

Cuando un usuario comparte su información de contacto (tocando un botón REQUEST_CONTACT_INFO o compartiendo un contacto directo en el chat), se dispara un webhook de contacto con los campos nuevos:

Campo	Descripción
`from_user_id`	BSUID del usuario.
`origin`	Cómo se compartió la información: `contact_request` (botón `REQUEST_CONTACT_INFO`) u `other` (contacto directo).
`vcard`	Tarjeta de contacto virtual en formato vCard. Solo si `origin` es `other`.

Webhook de sistema (`system`)

Los webhooks de sistema notifican cuando un usuario cambia su número de teléfono, lo que regenera su BSUID:

Campo	Descripción
`system.user_id`	Nuevo BSUID del usuario.
`system.parent_user_id`	Nuevo parent BSUID, si está habilitado.
`system.wa_id`	Nuevo número de teléfono, si está disponible.
`system.body`	Descripción del cambio (`User <nombre> changed from <OLD_BSUID> to <NEW_BSUID>`).
`system.type`	`user_changed_user_id` cuando el usuario cambió su número.

El ISV reenvía los eventos system sin mutar registros locales: la actualización de registros BSUID es responsabilidad del consumidor del webhook.

Ejemplo de mensaje recibido con BSUID

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Sheena Nelson",
                  "username": "realsheenanelson"
                },
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.11815799212886844830"
              }
            ],
            "messages": [
              {
                "from_user_id": "US.13491208655302741918",
                "from_parent_user_id": "US.ENT.11815799212886844830",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
                "timestamp": "1749416383",
                "type": "text",
                "text": {
                  "body": "Does it come in another color?"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Ejemplo de actualización de username de empresa

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "business_username_updates",
          "value": {
            "display_phone_number": "15550783881",
            "username": "mybusiness",
            "status": "approved"
          }
        }
      ]
    }
  ]
}

Llamadas

Los endpoints de llamadas preservan los campos de usuario nuevos cuando Meta los requiere o los entrega en el payload. Consulta API Oficial (CALLING) para el detalle.

Endpoint	Campos relevantes
`POST /calls/{v}/{did}/signaling`	`to_user_id`, `to_parent_user_id`, `from_user_id`, `from_parent_user_id`.
`GET /calls/{v}/{did}/call_permissions`	Permite consultar por `user_wa_id` y también preservar `user_id` cuando se envía como query param.

Errores nuevos o relevantes

Código	Mensaje	Cuándo ocurre
`131062`	`BSUID recipients are not supported for this message`	Meta rechaza un mensaje enviado con BSUID para un tipo de mensaje que no lo soporta.
`147001` a `147005`	Errores de Username API	Meta rechaza operaciones de username por formato, disponibilidad, elegibilidad o reglas de negocio.

Groups API y Block Users API

El ISV también da soporte a las APIs de Groups y Block Users de Meta (grupos, solicitudes de unión, participantes y bloqueo/desbloqueo de usuarios). Consulta la documentación de Meta para conocer el comportamiento de estas capacidades.

Compatibilidad

El microservicio mantiene compatibilidad con integraciones existentes porque los payloads se preservan hacia Meta y hacia los webhooks configurados por el ISV. Las integraciones que todavía operan con número telefónico pueden seguir usando to; las integraciones que adopten BSUID o Parent BSUID pueden usar recipient y los nuevos campos de webhooks.

API Oficial (CALLING)

Business-scoped user IDs (BSUID)

Resumen rápido

Identificadores soportados

Formato del BSUID

Envío de mensajes con recipient

Mensaje usando BSUID

Request

Mensaje usando número telefónico y BSUID

Request

Mensaje interactivo para solicitar información de contacto

Request

Plantillas con REQUEST_CONTACT_INFO

Request

Endpoints de Business Username y Contact Book

Adoptar o cambiar username

Request

Response

Success (200)

Errores de username

Eliminar contacto por BSUID

Request

Response

Success (200)

Campos nuevos en webhooks

Webhook de estado (statuses)

Webhook de contactos (contacts)

Webhook de sistema (system)

Ejemplo de mensaje recibido con BSUID

Ejemplo de actualización de username de empresa

Llamadas

Errores nuevos o relevantes

Groups API y Block Users API

Compatibilidad

Envío de mensajes con `recipient`

Plantillas con `REQUEST_CONTACT_INFO`

Webhook de estado (`statuses`)

Webhook de contactos (`contacts`)

Webhook de sistema (`system`)