{"id":3104,"date":"2026-11-06T09:13:28","date_gmt":"2026-11-06T09:13:28","guid":{"rendered":"https:\/\/360dialog.com\/blog\/?p=3104"},"modified":"2026-11-06T09:13:28","modified_gmt":"2026-11-06T09:13:28","slug":"integracion-bsuid-whatsapp","status":"publish","type":"post","link":"https:\/\/360dialog.com\/blog\/es\/integracion-bsuid-whatsapp\/","title":{"rendered":"Integraci\u00f3n de BSUID en WhatsApp: webhooks, env\u00edo y la libreta de contactos"},"content":{"rendered":"\n

Una integraci\u00f3n de la WhatsApp Business API identifica a un cliente que usa un nombre de usuario de WhatsApp por un ID de usuario a nivel de empresa (BSUID), un c\u00f3digo \u00fanico para cada par de cliente y portfolio comercial.<\/strong> El webhook sigue incluyendo el n\u00famero de tel\u00e9fono cuando el mismo n\u00famero de la empresa intercambi\u00f3 un mensaje o una llamada con el cliente en los \u00faltimos 30 d\u00edas. El n\u00famero tambi\u00e9n se mantiene en los webhooks para los clientes que est\u00e1n en la libreta de contactos (Contact Book), una lista que Meta guarda con los n\u00fameros de tel\u00e9fono de conversaciones anteriores. Cualquier otro mensaje de un cliente con nombre de usuario llega con un BSUID y sin n\u00famero de tel\u00e9fono. Un controlador de webhooks debe aceptar los mensajes que llegan con un BSUID y sin n\u00famero de tel\u00e9fono. Si los rechaza, esos mensajes se pierden, y Meta no tiene forma de volver a enviarlos.<\/p>\n\n\n\n

<\/p>\n\n\n\n

Puntos clave<\/h2>\n\n\n\n
    \n
  1. Meta exige a los socios, a las empresas con integraci\u00f3n directa y a los anunciantes de clic a WhatsApp en la plataforma de WhatsApp Business que admitan los BSUID.<\/li>\n\n\n\n
  2. El n\u00famero de tel\u00e9fono de un cliente sigue llegando durante 30 d\u00edas despu\u00e9s de un mensaje o una llamada con el mismo n\u00famero de la empresa, y mientras el cliente siga en la libreta de contactos.<\/li>\n\n\n\n
  3. Un mensaje puede ir a un BSUID, a un n\u00famero de tel\u00e9fono o a ambos, y solo las plantillas de autenticaci\u00f3n de un solo toque, sin toque y de copiar c\u00f3digo todav\u00eda necesitan el n\u00famero de tel\u00e9fono.<\/li>\n\n\n\n
  4. Una empresa que necesita un n\u00famero de tel\u00e9fono puede pedirlo en el chat con un bot\u00f3n, y el cliente decide si lo comparte.<\/li>\n\n\n\n
  5. 360Dialog, un Official Meta Solution Partner, les da a las empresas acceso a la WhatsApp Business API, que acepta los BSUID como destinatarios de los mensajes.<\/strong><\/li>\n<\/ol>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfQu\u00e9 es un ID de usuario a nivel de empresa (BSUID)?<\/h2>\n\n\n\n

    Un ID de usuario a nivel de empresa (BSUID) es un identificador que WhatsApp genera para cada par de cliente y portfolio comercial, y llega en los webhooks tenga o no el cliente un nombre de usuario. Guardarlo le da a una integraci\u00f3n una clave de cliente \u00fanica que sigue funcionando cuando un cliente deja de compartir su n\u00famero de tel\u00e9fono.<\/p>\n\n\n\n

    Un nombre de usuario es un nombre \u00fanico y opcional que un usuario de WhatsApp puede mostrar en lugar de su n\u00famero de tel\u00e9fono, y WhatsApp est\u00e1 lanzando los nombres de usuario de forma gradual.[1] Nuestra gu\u00eda sobre nombres de usuario de WhatsApp para empresas<\/a> explica qu\u00e9 cambia para los clientes y para los equipos que les responden.<\/p>\n\n\n\n

    Meta exige a todos los socios y a las empresas con integraci\u00f3n directa en la plataforma de WhatsApp Business que admitan los BSUID, y el requisito se extiende a los anunciantes de clic a WhatsApp.[2] Los BSUID aparecen en los webhooks desde principios de abril de 2026. En la Cloud API<\/a>, el valor est\u00e1 en el campo user_id de cada webhook messages.<\/p>\n\n\n\n

    Guarda y env\u00eda cada BSUID completo, porque una solicitud con una parte faltante o modificada falla. Una columna de base de datos para el BSUID necesita espacio para el c\u00f3digo de pa\u00eds de dos letras, el punto y hasta 128 letras y d\u00edgitos despu\u00e9s. Cada BSUID funciona dentro de un portfolio comercial, antes llamado Business Manager, y solo los n\u00fameros de tel\u00e9fono de empresa de ese portfolio pueden enviarle mensajes. Por eso, el mismo cliente tiene un BSUID distinto en cada portfolio.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfCu\u00e1ndo sigue devolviendo la API el n\u00famero de tel\u00e9fono de un cliente?<\/h2>\n\n\n\n

    Los webhooks siguen trayendo el n\u00famero de tel\u00e9fono de un cliente cuando ese n\u00famero de tel\u00e9fono de empresa intercambi\u00f3 un mensaje o una llamada con el cliente en los \u00faltimos 30 d\u00edas, o cuando el cliente est\u00e1 en la libreta de contactos de la empresa. Saber qu\u00e9 caso aplica le indica a un equipo qu\u00e9 conversaciones necesitan primero el manejo de BSUID.<\/p>\n\n\n\n

    Cinco situaciones deciden qu\u00e9 identificadores trae un webhook, seg\u00fan la documentaci\u00f3n de Meta sobre los BSUID.<\/p>\n\n\n\n

    Situaci\u00f3n<\/th>N\u00famero de tel\u00e9fono<\/th>BSUID<\/th><\/tr><\/thead>
    El cliente no tiene nombre de usuario<\/td>Incluido<\/td>Incluido<\/td><\/tr>
    El cliente tiene nombre de usuario, y este n\u00famero de la empresa intercambi\u00f3 con \u00e9l un mensaje o una llamada en los \u00faltimos 30 d\u00edas<\/td>Incluido<\/td>Incluido<\/td><\/tr>
    El cliente tiene nombre de usuario y est\u00e1 en la libreta de contactos del portfolio<\/td>Incluido<\/td>Incluido<\/td><\/tr>
    El cliente tiene nombre de usuario y comparte su n\u00famero con el bot\u00f3n Solicitar informaci\u00f3n de contacto<\/td>Incluido en un webhook contacts<\/td>Incluido<\/td><\/tr>
    El cliente tiene nombre de usuario y no cumple ninguna de las condiciones anteriores<\/td>Omitido<\/td>Incluido<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    <\/p>\n\n\n\n

    La verificaci\u00f3n de 30 d\u00edas se hace por n\u00famero de tel\u00e9fono de empresa, mientras que la libreta de contactos cubre todo el portfolio. Un cliente que regresa fuera de ambos casos puede aparecer como una conversaci\u00f3n nueva. Las llamadas cuentan igual que los mensajes, incluidas las llamadas hechas con la WhatsApp Calling API<\/a>. Una conversaci\u00f3n que empieza desde anuncios de clic a WhatsApp<\/a> sigue las mismas condiciones.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfC\u00f3mo funciona la libreta de contactos en la API?<\/h2>\n\n\n\n

    La libreta de contactos es una lista que Meta aloja para cada portfolio comercial, y guarda el n\u00famero de tel\u00e9fono de un cliente junto a su BSUID una vez que el cliente y la empresa intercambian un mensaje o una llamada. Mientras un cliente siga en ella, los webhooks siguen trayendo su n\u00famero de tel\u00e9fono despu\u00e9s de que se cierra la ventana de 30 d\u00edas. Dos llamadas a la API le permiten a una integraci\u00f3n verificar y eliminar entradas individuales.<\/p>\n\n\n\n

    La libreta de contactos no necesita configuraci\u00f3n, y las entradas se mantienen hasta que la empresa desactiva la funci\u00f3n en Meta Business Suite, en Configuraci\u00f3n del negocio > Informaci\u00f3n del negocio, o desactiva su cuenta. Al desactivarla se borran todas las entradas para siempre. Solo registra las interacciones ocurridas despu\u00e9s de que Meta la lanz\u00f3, y sus n\u00fameros de tel\u00e9fono aparecen \u00fanicamente en las cargas \u00fatiles de los webhooks.<\/p>\n\n\n\n

    Meta agreg\u00f3 la llamada de verificaci\u00f3n el 24 de agosto de 2026 y cambi\u00f3 la respuesta de la llamada de eliminaci\u00f3n el 25 de agosto de 2026.[3] Ambas llamadas aceptan un BSUID est\u00e1ndar y rechazan los BSUID principales.<\/p>\n\n\n\n

    Llamada<\/th>Solicitud<\/th>Respuesta<\/th><\/tr><\/thead>
    Verificar<\/td>GET \/<BUSINESS_PHONE_NUMBER_ID>\/contact_book?messaging_product=whatsapp&bsuid=<BSUID><\/td>contacts con bsuid y present (true o false), nunca el n\u00famero de tel\u00e9fono<\/td><\/tr>
    Eliminar<\/td>DELETE en la misma ruta<\/td>success y deleted, con deleted en false para cualquier BSUID sin entrada<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    <\/p>\n\n\n\n

    Un valor deleted en false se ve igual para un BSUID desconocido, uno no v\u00e1lido y uno de otro portfolio. Despu\u00e9s de una eliminaci\u00f3n, el n\u00famero de tel\u00e9fono todav\u00eda puede aparecer dentro de la ventana de 30 d\u00edas o despu\u00e9s de una nueva interacci\u00f3n.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfC\u00f3mo pides un n\u00famero de tel\u00e9fono con el bot\u00f3n Solicitar informaci\u00f3n de contacto?<\/h2>\n\n\n\n

    El bot\u00f3n Solicitar informaci\u00f3n de contacto le pide a un cliente que comparta su n\u00famero de tel\u00e9fono en el chat, y el n\u00famero vuelve en un webhook contacts junto al BSUID. Permite que cualquier flujo que necesite un n\u00famero de tel\u00e9fono lo obtenga dentro de la conversaci\u00f3n, con el consentimiento del cliente.<\/p>\n\n\n\n

    El bot\u00f3n est\u00e1 disponible desde principios de julio de 2026 en plantillas de utilidad y de marketing, y en un mensaje interactivo<\/a>. Un n\u00famero compartido de esta forma tambi\u00e9n entra autom\u00e1ticamente en la libreta de contactos cuando la empresa la usa. Las pautas de Meta piden que los bots que necesitan un n\u00famero lo soliciten y que atiendan a los clientes que prefieren no compartirlo.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfC\u00f3mo env\u00edas mensajes a un BSUID?<\/h2>\n\n\n\n

    Una empresa env\u00eda un mensaje a un BSUID con la misma solicitud de env\u00edo que usa para los n\u00fameros de tel\u00e9fono, con el BSUID en un campo propio. Enviar mensajes por BSUID le permite a una empresa seguir hablando con clientes cuyo n\u00famero de tel\u00e9fono nunca recibi\u00f3.<\/p>\n\n\n\n

    Meta fecha el env\u00edo por BSUID a partir de julio de 2026. Una solicitud identifica al cliente por n\u00famero de tel\u00e9fono, por BSUID o por ambos, y el n\u00famero de tel\u00e9fono tiene prioridad cuando est\u00e1n los dos.<\/p>\n\n\n\n

    Todos los tipos de mensaje funcionan con un BSUID, excepto las plantillas de autenticaci\u00f3n de un solo toque, sin toque y de copiar c\u00f3digo, que todav\u00eda necesitan un n\u00famero de tel\u00e9fono. La Marketing Messages API<\/a> tambi\u00e9n acepta los BSUID, y Meta recomienda usar n\u00fameros de tel\u00e9fono ah\u00ed porque as\u00ed los webhooks siguen devolviendo el n\u00famero.<\/p>\n\n\n\n

    Nuestra documentaci\u00f3n sobre nombres de usuario y BSUID<\/a> muestra la solicitud de env\u00edo completa, la respuesta y los c\u00f3digos de error en la API de 360Dialog.[4]<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfQu\u00e9 cambia en los webhooks?<\/h2>\n\n\n\n

    Los webhooks ahora traen el BSUID del cliente en cada mensaje entrante y en los estados enviado, entregado y le\u00eddo, y el n\u00famero de tel\u00e9fono aparece solo cuando se cumple una de las condiciones de n\u00famero de tel\u00e9fono de Meta. Un analizador que trata el BSUID como el identificador obligatorio sigue procesando todos los mensajes.<\/p>\n\n\n\n

    El BSUID est\u00e1 junto al n\u00famero de tel\u00e9fono en las mismas cargas \u00fatiles, en campos propios. Los campos de n\u00famero de tel\u00e9fono aparecen cuando el cliente no tiene nombre de usuario, cuando se cumple una condici\u00f3n de n\u00famero de tel\u00e9fono o cuando el mensaje se envi\u00f3 a un n\u00famero de tel\u00e9fono, y el nombre de usuario del cliente llega como dato de perfil cuando tiene uno. Los campos que no aplican se omiten de la carga \u00fatil.<\/p>\n\n\n\n

    Un cambio de n\u00famero de tel\u00e9fono le da al cliente un BSUID nuevo, que se informa en el webhook messages como un mensaje del sistema de tipo user_changed_number o user_changed_user_id. Ambos incluyen previous_user_id, el BSUID anterior. Una integraci\u00f3n lo usa para encontrar el registro de cliente que ya tiene guardado. Meta no documenta ning\u00fan campo de webhook user_id_update aparte.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfC\u00f3mo administras un nombre de usuario de empresa a trav\u00e9s de la API?<\/h2>\n\n\n\n

    Una empresa configura, consulta y elimina el nombre de usuario de cada n\u00famero de tel\u00e9fono de empresa con la API de nombres de usuario (Username API) de Meta, que tambi\u00e9n informa los cambios de estado por webhook. Integrar estas llamadas en una plataforma le permite a un equipo controlar los nombres de usuario de muchos n\u00fameros en un solo lugar.<\/p>\n\n\n\n

    Una empresa puede configurar o cambiar un nombre de usuario para cada n\u00famero de tel\u00e9fono de empresa, consultar su estado, aprobado o reservado, y eliminarlo, y una llamada de sugerencias devuelve nombres reservados con m\u00e1s probabilidades de aprobaci\u00f3n. Un nombre de usuario aprobado se activa cuando los nombres de usuario est\u00e1n disponibles en el pa\u00eds de la empresa. Los clientes de 360Dialog lo hacen con los puntos de conexi\u00f3n de nombre de usuario de empresa de nuestra referencia de la API.[5]<\/p>\n\n\n\n

    Cada n\u00famero de tel\u00e9fono de empresa puede configurar 2 nombres de usuario nuevos en cualquier per\u00edodo de 14 d\u00edas consecutivos, o 10 cuando el resultado tiene estado reservado, y una solicitud que supera el l\u00edmite falla. El conteo se lleva por n\u00famero, y eliminar un nombre de usuario no lo modifica.<\/p>\n\n\n\n

    El webhook business_username_updates, al que se suscribe cada app, informa los estados aprobado, eliminado y reservado. Cuando Meta revoca un nombre de usuario, el webhook lo indica, y el nombre de usuario se elimina o se reemplaza por uno generado.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfC\u00f3mo funcionan los BSUID principales en varios portfolios?<\/h2>\n\n\n\n

    Un BSUID principal es un identificador por cliente que puede usar cada portfolio comercial inscrito en la misma cuenta de BSUID principal. Permite que una empresa administrada con varios portfolios reconozca al mismo cliente en todos ellos.<\/p>\n\n\n\n

    Meta ofrece los BSUID principales a empresas administradas, y el contacto de Meta de la empresa verifica la elegibilidad. Despu\u00e9s, los webhooks traen el BSUID principal junto al BSUID normal, en parent_user_id, from_parent_user_id y recipient_parent_user_id. Un BSUID principal agrega ENT despu\u00e9s del c\u00f3digo de pa\u00eds, y cualquier n\u00famero de tel\u00e9fono de empresa de un portfolio inscrito puede enviarle mensajes.<\/p>\n\n\n\n

    La inscripci\u00f3n no cambia los controles de acceso, la facturaci\u00f3n ni la administraci\u00f3n de cada portfolio. Las libretas de contactos siguen separadas por portfolio. Para listar los portfolios inscritos, una empresa llama a GET https:\/\/api.facebook.com\/<BUSINESS_ID>\/parent-bsuid-accounts, que devuelve parent_bsuid_account_id y enrolled_business_portfolios.<\/p>\n\n\n\n

    Las plataformas que operan una integraci\u00f3n de WhatsApp multicliente<\/a> mantienen los BSUID de cada cliente dentro del portfolio de ese cliente.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    \u00bfQu\u00e9 deber\u00eda manejar tu integraci\u00f3n ahora?<\/h2>\n\n\n\n

    Una integraci\u00f3n lista para los BSUID guarda el BSUID como identificador central del cliente, trata el n\u00famero de tel\u00e9fono como opcional y pide un n\u00famero solo donde un flujo lo necesita. Estos cambios mantienen cada conversaci\u00f3n vinculada al registro de cliente correcto.<\/p>\n\n\n\n

    En la pr\u00e1ctica, los analizadores de webhooks y las columnas de base de datos aceptan mensajes que traen solo un BSUID, y cada registro de cliente guarda el BSUID junto al n\u00famero de tel\u00e9fono. As\u00ed, los sistemas de CRM, campa\u00f1as, medici\u00f3n y facturaci\u00f3n tambi\u00e9n identifican a los clientes por BSUID. Los flujos que necesitan un n\u00famero lo piden con el bot\u00f3n Solicitar informaci\u00f3n de contacto y mantienen una alternativa para los clientes que prefieren no compartirlo, y la herramienta de prueba de webhooks de Meta verifica el analizador en cada caso. Los equipos que planean respuestas asistidas por IA pueden leer c\u00f3mo funciona el agente de IA con la API en nuestra gu\u00eda completa de Meta Business Agent<\/a>. Cuando cada sistema identifica a los clientes por BSUID, cada conversaci\u00f3n llega al registro de cliente al que pertenece, y el agente que la responde ve el historial completo.<\/p>\n\n\n\n

    360Dialog es un Official Meta Solution Partner para la WhatsApp Business API, y nuestra documentaci\u00f3n sobre nombres de usuario y BSUID<\/a> ofrece la lista de verificaci\u00f3n de integraci\u00f3n paso a paso, con las solicitudes de env\u00edo y las cargas \u00fatiles de webhooks en la API de 360Dialog. Obtener acceso a la API<\/a> te permite crear y probar el manejo de BSUID en tu propio n\u00famero de la WhatsApp Business API.<\/strong> Habla con nosotros<\/a> para preparar tu integraci\u00f3n de la WhatsApp Business API para los BSUID.<\/strong><\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Preguntas frecuentes<\/h2>\n\n\n\n

    \u00bfUna empresa puede enviar mensajes a un cliente por su nombre de usuario?<\/h3>\n\n\n\n

    Una empresa no puede usar un nombre de usuario como direcci\u00f3n de mensaje en la WhatsApp Business API. Las solicitudes de env\u00edo aceptan un n\u00famero de tel\u00e9fono en el campo to o un BSUID en el campo recipient. El nombre de usuario llega en los webhooks como dato de perfil, y el cliente puede cambiarlo cuando quiera. El BSUID se mantiene y es el identificador que conviene guardar.<\/p>\n\n\n\n

    \u00bfLos mensajes de autenticaci\u00f3n todav\u00eda se env\u00edan a n\u00fameros de tel\u00e9fono?<\/h3>\n\n\n\n

    Las plantillas de autenticaci\u00f3n de un solo toque, sin toque y de copiar c\u00f3digo todav\u00eda van al n\u00famero de tel\u00e9fono del cliente, y enviar una a un BSUID falla con el error 131062. Una empresa que solo tiene un BSUID puede pedir primero el n\u00famero con el bot\u00f3n Solicitar informaci\u00f3n de contacto. Cuando el cliente lo comparte, la empresa env\u00eda la plantilla de autenticaci\u00f3n a ese n\u00famero.<\/p>\n\n\n\n

    \u00bfC\u00f3mo pruebas un controlador de webhooks para BSUID?<\/h3>\n\n\n\n

    La herramienta de prueba de webhooks de Meta env\u00eda al controlador cargas \u00fatiles de ejemplo con BSUID desde el Panel de apps. Abre Casos de uso, luego Conectarse con los clientes a trav\u00e9s de WhatsApp, Personalizar y Configuraci\u00f3n, y selecciona Probar junto al campo messages. Cubre cuatro casos: sin nombre de usuario, nombre de usuario sin n\u00famero de tel\u00e9fono, nombre de usuario con n\u00famero y carga \u00fatil con BSUID principal.<\/p>\n\n\n\n

    \u00bfLos socios deben actualizar las integraciones de sus clientes para los BSUID?<\/h3>\n\n\n\n

    Los socios de la plataforma de WhatsApp Business deben admitir los BSUID, igual que las empresas con integraci\u00f3n directa y los anunciantes de clic a WhatsApp. La app de un socio puede enviar mensajes a los BSUID de un cliente desde los n\u00fameros de empresa de ese cliente. Usar el BSUID de un cliente con el n\u00famero del socio falla, porque cada BSUID pertenece a un solo portfolio comercial.<\/p>\n\n\n\n

    <\/p>\n\n\n\n

    Fuentes<\/h2>\n\n\n\n

    [1] WhatsApp Help Center, \u00abAbout usernames,\u00bb https:\/\/faq.whatsapp.com\/658755553162769\/ (accessed October 29, 2026).<\/p>\n\n\n\n

    [2] Meta for Developers, \u00abBusiness-scoped user IDs,\u00bb updated October 23, 2026, https:\/\/developers.facebook.com\/documentation\/business-messaging\/whatsapp\/business-scoped-user-ids\/ (accessed October 29, 2026).<\/p>\n\n\n\n

    [3] Meta for Developers, \u00abChangelog,\u00bb https:\/\/developers.facebook.com\/documentation\/business-messaging\/whatsapp\/changelog\/ (accessed October 29, 2026).<\/p>\n\n\n\n

    [4] 360Dialog documentation, \u00abUsernames & BSUID,\u00bb https:\/\/docs.360dialog.com\/docs\/resources\/phone-numbers\/usernames-and-bsuid (accessed October 29, 2026).<\/p>\n\n\n\n

    [5] 360Dialog documentation, \u00abBusiness Username,\u00bb https:\/\/docs.360dialog.com\/docs\/messaging-api\/api-reference\/business-username (accessed October 29, 2026).<\/p>\n\n\n\n

    <\/p>\n\n\n\n