Nomi utente WhatsApp e BSUID: cosa cambia per OTP, CRM e webhook

Un ID utente con ambito aziendale (BSUID) è l'identificatore che Meta inserisce ora in ogni webhook WhatsApp, in modo che un'azienda possa inviare un messaggio a un utente senza conoscerne il numero di telefono. Esiste perché WhatsApp sta introducendo i nomi utente: una volta che un utente ne attiva uno, un'azienda che non è stata in contatto di recente potrebbe non ricevere più il numero. Questa guida del team di ingegneria di BroadNet spiega il formato, la cronologia, cosa richiede ancora un numero di telefono e come migrare i webhook, i record CRM e i flussi OTP.

Punti chiave

• Gli BSUID sono apparsi nei webhook di WhatsApp da inizio aprile 2026, per ogni utente, indipendentemente dal fatto che utilizzi o meno un nome utente.
• Un BSUID appare come US.13491208655302741918: un codice paese alpha-2 ISO 3166, un punto, e poi fino a 128 caratteri alfanumerici.
• È unico per ogni coppia portfolio aziendale e utente, ed è rigenerato se l'utente cambia il proprio numero di telefono.
• Da luglio 2026 è possibile inviare messaggi a un BSUID, ad eccezione dei modelli di autenticazione one-tap, zero-tap e copy-code, che richiedono ancora il numero di telefono.
• Meta afferma che i partner e le aziende integrate direttamente devono supportare gli BSUID per evitare di perdere la capacità di elaborare i messaggi dagli utenti con nome utente.
• Conservare il numero di telefono E.164 verificato come ancora di identità per OTP, il fallback SMS e i controlli anti-frode. Trattare il BSUID come una chiave a canale WhatsApp.

Cos'è un ID utente con ambito aziendale?

Meta definisce un BSUID come "un identificatore utente unico che può essere utilizzato per inviare un messaggio a un utente WhatsApp quando non si conosce il suo numero di telefono" (Meta, ID utente con ambito aziendale). Il formato è il paese dell'utente come codice alpha-2 ISO 3166, un punto e fino a 128 caratteri alfanumerici, ad esempio US.13491208655302741918.

Tre proprietà sono importanti per la progettazione del sistema:

• Ambito. Un BSUID è unico per un portfolio aziendale e un utente. La stessa persona ha un BSUID diverso per ogni portfolio aziendale con cui comunica, quindi non è possibile utilizzarlo per far corrispondere i clienti tra portfolio non correlati.
• Stabilità. Viene rigenerata quando l'utente cambia il proprio numero di telefono. Quando ciò accade, Meta invia un webhook di messaggio di sistema con tipo user_changed_user_id e un webhook user_id_update separato.
• Parent BSUID. Le aziende gestite con diversi portfolio possono chiedere al proprio punto di contatto Meta di iscriversi ai parent BSUID, che contengono ENT (ad esempio US.ENT.11815799212886844830) e operano su tutti i portfolio iscritti.

Perché WhatsApp sta introducendo i nomi utente?

Per la privacy. Meta ha annunciato il 29 giugno 2026 che le persone possono riservare un nome utente da utilizzare "entro la fine di quest'anno", e che quando un utente ne avrà abilitato uno, una persona o un'azienda a cui invia un messaggio per la prima volta non vedrà più il suo numero di telefono (Informazioni su Meta). La documentazione per gli sviluppatori di Meta afferma che i nomi utente saranno rilasciati gradualmente nel 2026.

Anche le aziende possono avere nomi utente. Dal 29 giugno 2026, un'azienda può rivendicare un nome utente che WhatsApp ha riservato per essa tramite WhatsApp Manager, Meta Business Suite o il Username API, e i nomi utente approvati diventano attivi al lancio della funzione. Un nome utente aziendale non nasconde il numero di telefono dell'azienda.

Qual è la cronologia?

Perderai il numero di telefono del cliente?

A volte. Il BSUID appare in tutti i webhook dei messaggi. Il numero di telefono (wa_id, e from nei messaggi in entrata) è incluso solo quando almeno una di queste condizioni è vera, secondo Meta:

• hai inviato un messaggio o chiamato il numero di telefono dell'utente nei 30 giorni precedenti l'attivazione del webhook;
• hai ricevuto un messaggio o una chiamata dal numero di telefono dell'utente entro quei 30 giorni; o
• l'utente è nella tua rubrica.

Il lookback di 30 giorni viene valutato per ogni numero di telefono aziendale, quindi un cliente noto alla vostra linea di vendita potrebbe non esserlo alla vostra linea di supporto. La rubrica è una funzionalità ospitata da Meta che memorizza i numeri di telefono e i BSUID dopo una prima interazione, in modo che i webhook successivi possano continuare a trasportare il numero anche dopo che l'utente adotta un nome utente. È attiva per impostazione predefinita e può essere disattivata in Meta Business Suite sotto Impostazioni aziendali, Informazioni aziendali. Lasciatela attiva a meno che non abbiate un motivo per non farlo.

Cosa necessita ancora di un numero di telefono?

Meta è esplicito: i BSUID "possono essere utilizzati per inviare qualsiasi tipo di messaggio, ad eccezione dei modelli di autenticazione one-tap, zero-tap e copy code, che richiedono i numeri di telefono degli utenti". Al di fuori di WhatsApp, qualsiasi cosa che giri sulla rete mobile necessita inoltre del numero.

Come appare il webhook prima e dopo?

Prima di BSUID, il blocco contatti in un webhook di messaggi conteneva il numero di telefono in wa_id, e la maggior parte delle integrazioni lo utilizzava come chiave cliente. L'esempio di Meta del nuovo oggetto contatti aggiunge il nome utente, il BSUID e, dove abilitato, il BSUID padre (parent); wa_id è presente solo quando il numero può essere condiviso:

1"contacts": [
2  {
3    "profile": {
4      "name": "<USER_DISPLAY_NAME>",
5      "username": "<USERNAME>"
6    },
7    "wa_id": "<USER_PHONE_NUMBER>",
8    "user_id": "<BSUID>",
9    "parent_user_id": "<PARENT_BSUID>"
10  }
11]

Anche i messaggi in entrata contengono from_user_id (e from_parent_user_id se abilitato), e i webhook di stato contengono recipient_user_id, che Meta afferma essere sempre impostato sul BSUID dell'utente. Per inviare, inserire il BSUID nel nuovo parametro recipient. È possibile impostare il parametro to (numero di telefono), il parametro recipient (BSUID) o entrambi; quando sono presenti entrambi, il numero di telefono ha la precedenza:

1{
2  "messaging_product": "whatsapp",
3  "recipient_type": "individual",
4  "recipient": "<BSUID>",
5  "type": "text",
6  "text": {
7    "body": "<BODY_TEXT>"
8  }
9}

La risposta di invio include quindi user_id nel suo array di contatti, e wa_id diventa opzionale. Se il parser assume che wa_id sia sempre presente, fallirà al primo utente con nome utente. È possibile incollare payload reali nel nostro ispettore del payload webhook per verificare quali campi riceve effettivamente la propria integrazione.

Cosa si interrompe per OTP?

I modelli di autenticazione con pulsanti one-tap, zero-tap o copia-codice non possono essere inviati a un BSUID. Se un utente con nome utente vi raggiunge tramite WhatsApp e non avete un numero di telefono per loro, non potete inviare loro un WhatsApp OTP di quel tipo. Ciò ha due conseguenze per i flussi di verifica:

• Raccogliere e verificare il numero di telefono durante la registrazione, in formato E.164, e memorizzarlo come indirizzo di verifica dell'account. Non fare affidamento sul webhook WhatsApp per riceverlo in seguito. Vedere cos'è E.164.
• Mantenere un canale che funzioni sul numero stesso. SMS OTP, le OTP vocali e i controlli di rete silenziosi girano tutti sul numero di telefono, motivo per cui un design multicanale con fallback automatico sopravvive a questo cambiamento senza modifiche. La nostra guida al OTP multicanale e il prodotto BroadNet OTP coprono questo schema.

Cosa si interrompe per il CRM e la deduplicazione dei clienti?

La maggior parte dei CRM identifica un contatto WhatsApp tramite il numero di telefono perché SMS, la voce e WhatsApp lo condividevano tutti. Dopo l'introduzione dei nomi utente, un nuovo contatto in entrata potrebbe arrivare solo con un BSUID. Se si crea un nuovo record CRM per esso, si duplicheranno gradualmente i clienti. Quattro regole mantengono i dati puliti:

1. 1Modellare il BSUID come un'identità del canale, non come l'ID del cliente. Un cliente può possedere diversi BSUID (uno per ogni portfolio aziendale) e uno nuovo dopo un cambio di numero.
2. 2Mantenere una tabella di mappatura di BSUID, portfolio, numero di telefono quando noto, prima apparizione e ultima apparizione, e aggiornarla ad ogni webhook, incluso user_id_update.
3. 3Unire in base alle prove, non per congetture: un numero di telefono verificato, un login o un riferimento d'ordine fornito dal cliente in chat.
4. 4Non trattare mai l'assenza di wa_id come un nuovo cliente. Significa solo che il numero non può essere condiviso in quell'evento.

Come si migra? Una checklist passo dopo passo

1. 1Aggiornare i parser dei webhook per leggere user_id, from_user_id, recipient_user_id e il nome utente, e per trattare wa_id e from come opzionali.
2. 2Aggiungere una colonna BSUID (e il BSUID padre se si è un'azienda gestita) ovunque si memorizzino i contatti WhatsApp.
3. 3Backfill: per ogni evento in entrata dall'inizio di aprile 2026, collegare il BSUID al numero di telefono già in possesso.
4. 4Gestire il messaggio di servizio user_changed_user_id e il webhook user_id_update ricollegando il nuovo BSUID al cliente.
5. 5Aggiungere il parametro recipient al proprio percorso di invio e utilizzarlo come fallback quando non si dispone di un numero di telefono.
6. 6Instradare OTP verso il numero di telefono, mai verso un BSUID, e mantenere SMS o la voce come canale di fallback.
7. 7Riservare il proprio nome utente aziendale in WhatsApp Manager, Meta Business Suite o tramite Username API.
8. 8Effettuare un test con un account abilitato al nome utente prima che i nomi utente raggiungano i propri clienti.

Se BroadNet è il proprio fornitore WhatsApp, richiedere l'accesso di test e confermare come i campi BSUID appaiano nei webhook per il proprio account prima di modificare il codice di produzione. Il nostro hub per gli sviluppatori e la pagina WhatsApp Business API contengono i dettagli, e l' instradamento omnichannel gestisce il fallback SMS su cui ora dipendono i flussi di autenticazione.

Domande frequenti

Cos'è un WhatsApp BSUID?

Un ID utente con ambito aziendale: un identificatore che Meta assegna a ogni utente WhatsApp per ogni portfolio aziendale, in modo che l'azienda possa inviare messaggi all'utente senza conoscerne il numero di telefono. Appare come user_id nei webhook.

Che aspetto ha un BSUID?

Un codice paese alpha-2 ISO 3166, un punto, quindi fino a 128 caratteri alfanumerici, ad esempio US.13491208655302741918. I BSUID padre (parent) BSUID per le aziende gestite includono ENT, ad esempio US.ENT.11815799212886844830.

Perderò il numero di telefono del cliente quando adotterà un nome utente?

Solo in alcuni webhook. Il numero è ancora incluso se si è scambiato un messaggio o una chiamata con quel numero negli ultimi 30 giorni, o se l'utente è nella propria rubrica. Altrimenti wa_id viene omesso e si riceve solo il BSUID.

Posso inviare messaggi a un BSUID?

Sì, da luglio 2026, utilizzando il parametro recipient del comando di invio API. Ogni tipo di messaggio funziona tranne i modelli di autenticazione one-tap, zero-tap e copy-code, che richiedono il numero di telefono dell'utente.

Posso inviare modelli di autenticazione (OTP) a un BSUID?

No. I modelli di autenticazione one-tap, zero-tap e copy-code richiedono il numero di telefono. Conserva un numero di telefono verificato per ogni account e utilizza SMS o la voce OTP come fallback.

I BSUID funzionano attraverso i portfolio aziendali?

No. Un BSUID è unico per una coppia formata da un singolo portfolio aziendale e un utente. Le aziende gestite possono chiedere a Meta informazioni sui BSUID padre (parent), che funzionano attraverso i portfolio iscritti insieme.

Un BSUID cambia mai?

Sì. Viene rigenerato quando l'utente cambia il proprio numero di telefono, e Meta segnala questo evento con un messaggio di sistema user_changed_user_id e un webhook user_id_update.

Come posso riservare il mio nome utente aziendale?

Dal 29 giugno 2026, tramite WhatsApp Manager, Meta Business Suite o il Username API. Un nome utente approvato diventa attivo al lancio della funzione nome utente, e non nasconde il numero di telefono della tua azienda.

Fonti

• Meta per gli sviluppatori, ID utente con ambito aziendale (formato, cronologia, campi webhook, rubrica, parametro di invio, eccezione modello di autenticazione), consultato il 26 settembre 2026.
• Informazioni su Meta, È ora di riservare il tuo nome utente WhatsApp, 29 giugno 2026, consultato il 26 settembre 2026.