AccediInizia la prova gratuita
Meta Tech Provider

Username WhatsApp e BSUID: cosa cambia nei webhook della Cloud API

Gli username di WhatsApp permettono agli utenti di mostrare un nome al posto del numero di telefono. Così, da inizio aprile 2026, anche i webhook messages della Cloud API portano un identificatore User ID con ambito dell'azienda (BSUID), come US.13491208655302741918, in user_id e from_user_id. Per un utente con username che non ha scambiato messaggi o chiamate con il numero da 30 giorni e non è in rubrica, wa_id e from vengono omessi.

easyCoexistence collega un numero dell'app WhatsApp Business alla Cloud API tramite Coexistence e instrada i suoi webhook messages e smb_message_echoes verso il tuo endpoint così come li invia Meta, campi BSUID inclusi, mentre get_api_credentials fornisce al tuo codice ciò che serve per rispondere con recipient.

April 2026

Quando i BSUID hanno iniziato a comparire nei webhook della Cloud API, prima che gli username raggiungessero gli utenti di WhatsApp.

July 2026

Quando le API hanno iniziato ad accettare messaggi inviati a un BSUID, indicato in recipient invece che in to.

30 days

Periodo di 30 giorni, per numero di telefono aziendale, durante il quale qualsiasi messaggio o chiamata con l'utente mantiene il suo numero nei webhook.

128

La maggior parte dei caratteri alfanumerici che seguono il codice paese di due lettere del BSUID e il punto.

131062

Errore dell'API Messages: «Business-scoped User ID (BSUID) recipients are not supported for this message.»

user_changed_user_id

Tipo di messaggio di sistema per un cambio di BSUID segnalato senza numero di telefono, con il BSUID precedente in previous_user_id.

Cosa sono gli username di WhatsApp e i BSUID?

Un username è un nome unico e facoltativo che un utente WhatsApp può impostare, mostrato nell'app al posto del numero di telefono; Meta lo sta distribuendo gradualmente nel 2026. Il BSUID è l'identificatore lato backend che Meta ha aggiunto perché le aziende possano comunque distinguere gli utenti: viene generato automaticamente, è unico per ogni coppia di Business Portfolio e utente, e si presenta come il codice paese ISO 3166 di due lettere dell'utente, un punto e fino a 128 caratteri alfanumerici. Meta richiede che partner e aziende integrate direttamente lo supportino, perché nessuna azienda controlla se i propri utenti adottano gli username.

Quali campi trasportano i nuovi identificatori?

Nuove proprietà affiancate a quelle che contenevano il numero di telefono, nei webhook messages, di stato, system e user_preferences. I campi genitore compaiono solo per i Business Portfolio che Meta ha registrato nei BSUID genitore, che funzionano su tutti i portfolio registrati:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

Quando il numero di telefono viene omesso?

Quando l'utente ha un username e nessuna delle tre condizioni di Meta è soddisfatta. Il numero resta nei webhook se il numero di telefono aziendale ha inviato un messaggio o chiamato il numero dell'utente negli ultimi 30 giorni, ha ricevuto un messaggio o una chiamata da esso in quel periodo, oppure l'utente è in rubrica del portfolio. Il periodo di 30 giorni è calcolato per ogni numero di telefono aziendale, quindi un secondo numero dello stesso portfolio potrebbe ricevere solo il BSUID dello stesso utente. Gli utenti senza username continuano ad arrivare con sia il numero di telefono sia il BSUID.

Come appare ora un messaggio in arrivo?

Come prima, con il BSUID accanto al numero di telefono o al suo posto. Nell'esempio di Meta di un utente con username il cui numero non può essere condiviso, contacts contiene profile.name, profile.username e user_id, e il messaggio porta from_user_id dove prima c'era from:

messages webhook: a text from a user known only by BSUID
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
        "contacts": [{
          "profile": { "name": "Sheena Nelson", "username": "realsheenanelson" },
          "user_id": "US.13491208655302741918"
        }],
        "messages": [{
          "from_user_id": "US.13491208655302741918",
          "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQTRBNjU5OUFFRTAzODEwMTQ0RgA=",
          "timestamp": "1749416383",
          "type": "text",
          "text": { "body": "Does it come in another color?" }
        }]
      }
    }]
  }]
}

Come cambiano i webhook di stato?

Gli stati di invio, consegna e lettura ottengono un array contacts con nome dell'utente, user_id, wa_id quando il numero può essere condiviso, e username su consegnato e letto. Negli stati, recipient_user_id contiene il BSUID, e recipient_id viene omesso quando hai inviato a un BSUID e il numero non può essere condiviso. Uno stato di errore non ha l'array contacts e omette recipient_user_id quando il messaggio era destinato a un numero di telefono, quindi collega i fallimenti all'id del messaggio.

Come memorizzare e abbinare gli utenti?

Prima per BSUID, con il numero di telefono come seconda chiave ogni volta che arriva. Memorizza il BSUID intero come stringa, codice paese e punto compresi, perché Meta rifiuta le richieste che alterano anche una sola parte, e memorizza anche il BSUID genitore se i tuoi portfolio sono registrati. Collega i record esistenti tramite wa_id finché continua ad arrivare e conserva il BSUID accanto, perché un utente che adotta un username in seguito potrebbe tornare senza numero. La FAQ di Meta chiede gli stessi collegamenti nei CRM e negli strumenti che alimentano.

Cosa succede quando un utente cambia numero di telefono?

Il suo BSUID viene rigenerato, e la modifica arriva sul campo messages come messaggio di sistema, poiché Meta non ha un campo user_id_update a cui iscriversi. system.type è user_changed_number quando il nuovo numero può essere condiviso con te, oppure user_changed_user_id quando si può segnalare solo il cambio di BSUID; system.user_id contiene il nuovo BSUID e system.previous_user_id quello vecchio, ed è così che un record viene riportato. Gestisci entrambi i tipi.

Come rispondi a un utente conosciuto solo tramite BSUID?

Invia a /<BUSINESS_PHONE_NUMBER_ID>/messages con recipient impostato sul BSUID e to omesso; con entrambi presenti, vince to e la risposta va al numero di telefono. La voce contacts della risposta contiene allora input e user_id invece di wa_id. Qualsiasi tipo di messaggio funziona, tranne i template di autenticazione one-tap, zero-tap e copy code, che richiedono un numero di telefono, e solo i numeri dello stesso Business Portfolio possono raggiungere un BSUID. L'errore 131062 significa che il tipo di messaggio non accetta destinatari BSUID.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

Come chiedi a un utente il suo numero di telefono?

Con il pulsante REQUEST_CONTACT_INFO, aggiunto a un template di utilità o marketing oppure inviato come messaggio interattivo di tipo request_contact_info. Un utente che lo tocca condivide il suo numero nella conversazione, e arriva un webhook contacts con origin impostato su contact_request e il numero in phones[].wa_id; un contatto condiviso a mano arriva con origin other e una vCard. Meta ha reso disponibile il pulsante all'inizio di luglio 2026, e la sua etichetta non può essere personalizzata.

Cos'è la rubrica?

Un archivio che Meta ospita per ogni Business Portfolio, senza alcun lavoro di integrazione: non appena un numero di telefono aziendale scrive, chiama o riceve una chiamata dal numero di un utente, quel numero e il BSUID vengono registrati e usati per riempire i webhook successivi con il numero di telefono, con o senza username. Contano solo le interazioni successive al suo lancio. Può essere disattivata nelle Impostazioni dell'azienda, in Informazioni sull'azienda, e la disattivazione elimina ciò che contiene; GET o DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book con un bsuid verifica o rimuove una singola voce.

Cosa dovrebbe cambiare un'integrazione Coexistence?

La gestione dei tre webhook che riceve solo un numero Coexistence, che cambiano anch'essi. In history, ogni conversazione ottiene un oggetto context con wa_id, user_id e username, e i suoi messaggi ottengono from_user_id. In smb_message_echoes viene aggiunto un array contacts, e message_echoes[].to può essere omesso mentre to_user_id contiene il BSUID; modifiche e revoche fatte nell'app WhatsApp Business arrivano allo stesso modo. In smb_app_state_sync, il phone_number di un contatto può essere omesso, con user_id e username accanto. Abbina gli echi e le chat importate sia su user_id sia sul numero.

Come testare prima che gli utenti adottino gli username?

Con lo strumento di test di Meta nella App Dashboard: sotto Use cases, Connect with customers through WhatsApp, Customize, Configuration, il link Test accanto al webhook messages invia un campione al tuo endpoint. Copre messaggi in arrivo e stati in quattro scenari:

  • Un utente senza username: campi BSUID e numero di telefono, senza username.
  • Un utente con username il cui numero non è disponibile: username e BSUID, senza campi del numero di telefono.
  • Un utente con username il cui numero è disponibile: username, BSUID e numero di telefono.
  • Un Business Portfolio registrato nei BSUID genitore: un BSUID genitore accanto al BSUID del portfolio.

Come gestisce easyCoexistence i BSUID?

Li inoltra così come Meta li invia. Un numero instradato verso il tuo endpoint con set_webhook_destination riceve i suoi webhook messages e smb_message_echoes direttamente da Meta, user_id, from_user_id, to_user_id e username inclusi, e con automazioni o inoltro attivi easyCoexistence inoltra il valore inviato da Meta senza modifiche. Per rispondere a un BSUID, il tuo codice usa get_api_credentials, che restituisce l'ID del numero di telefono, il suo endpoint di invio e, quando disponibile, il tuo token; gli strumenti send_message e send_template accettano un numero di telefono in cifre internazionali.

Errori comuni

  • Indicizzare i contatti solo su wa_id. Un utente con username che non ha avuto contatti con il numero da 30 giorni arriva con solo user_id e from_user_id, e un gestore che richiede wa_id perde il messaggio.
  • Tagliare il prefisso paese di un BSUID. Meta vuole il valore intero, codice paese e punto compresi, e una richiesta con anche una sola parte modificata fallisce.
  • Aspettarsi un campo user_id_update. Meta non ne ha: le modifiche del BSUID arrivano su messages come messaggi di sistema di tipo user_changed_number o user_changed_user_id.
  • Abbinare gli echi Coexistence solo su to. In smb_message_echoes il campo to può essere omesso, quindi una risposta scritta nell'app non viene vista a meno che anche to_user_id non venga abbinato.
Farlo con EasyCoexistence

Ogni connessione è monitorata 24/7. Da US$ 9 a US$ 0,75 per connessione al mese, con prezzo decrescente all'aumentare delle connessioni, con i primi 3 giorni gratuiti.

Domande frequenti

Anche gli utenti senza username ricevono un BSUID?

Sì. Meta imposta user_id nei webhook messages che l'utente abbia o meno un username, quindi la maggior parte degli utenti arriva con sia il numero di telefono sia il BSUID.

Un numero Coexistence può avere un username aziendale?

Sì. Dal 29 giugno 2026 un'azienda può adottarne o cambiarne uno in Meta Business Suite, WhatsApp Manager, nell'app WhatsApp Business o tramite la Username API; non nasconde il numero aziendale, e business_username_updates segnala ogni cambio di stato.

Un BSUID funziona tra più Business Portfolio?

No. Un BSUID appartiene a un solo portfolio e a un solo utente, e un numero di un altro Business Portfolio non può scrivergli. Le aziende gestite che Meta registra ricevono BSUID genitore, con ENT dopo il codice paese, che funzionano su tutti i portfolio registrati.

Quanto costa easyCoexistence per un numero WhatsApp?

Da US$ 9 a US$ 0,75 per connessione al mese, a seconda di quante connessioni hai, e i primi 3 giorni sono gratuiti. Gli addebiti per i messaggi di Meta restano sul metodo di pagamento del tuo WhatsApp Business Account.

Continua a leggere

Pronto per iniziare?

Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.

Inizia la prova gratuita

Verificato il