# Business-scoped user ID

Un **business-scoped user ID** (BSUID) è l'identificativo di Meta per un utente WhatsApp, circoscritto a un singolo portfolio aziendale. Arriva sui messaggi in entrata indipendentemente dal fatto che il contatto usi uno username WhatsApp, e permette di indirizzare un contatto di cui non hai il numero di telefono.

Bird lo espone come `bsuid` nei campi `from` e `to` di un messaggio, lo accetta come `to` di un invio e filtra l'elenco messaggi in base a esso. Il riferimento [business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) di Meta è la fonte per il rollout stesso e per il comportamento dell'identificativo sulle altre superfici Meta.

## Perché un contatto arriva senza numero di telefono

WhatsApp sta distribuendo gli username. Un utente che ne adotta uno mostra lo username al posto del numero di telefono nell'app, e Meta trattiene il numero dai payload che l'azienda riceve. Il BSUID è l'identità sempre presente, motivo per cui un messaggio in entrata può portarne uno senza alcun `phone_number`.

Meta include comunque il numero di telefono quando hai già una relazione con il contatto: quando quello specifico numero di telefono aziendale ha inviato un messaggio o effettuato una chiamata verso il contatto, oppure ne ha ricevuti, negli ultimi 30 giorni, o quando il contatto è nella tua rubrica Meta. La condizione dei 30 giorni è valutata per singolo numero di telefono aziendale, quindi un contatto che ha scritto a uno dei tuoi numeri può comunque arrivare senza numero di telefono su un altro.

Un messaggio da un utente WhatsApp porta anche il profilo pubblicato dall'utente, in `username` e `display_name` su `from`. Entrambi sono assenti quando il contatto non ha adottato uno username o il messaggio non contiene un profilo, e nessuno dei due può essere usato per indirizzare un messaggio.

## Aspetto di un BSUID

```json
{
  "from": {
    "bsuid": "US.13491208655302741918",
    "username": "alexr",
    "display_name": "Alex Rivera"
  }
}
```

Un codice paese ISO 3166 alpha-2, un punto, poi fino a 128 caratteri alfanumerici. Un **parent BSUID**, per il quale un'azienda gestita può essere iscritta in modo che un unico identificativo funzioni su un insieme di portfolio, inserisce `ENT` dopo il paese: `US.ENT.11815799212886844830`. Bird accetta entrambe le forme come destinatario.

Tre proprietà determinano come memorizzarlo e usarlo:

- **Passa l'intero valore, senza modifiche.** Meta rifiuta un BSUID modificato, quindi nessuna parte è facoltativa: il codice paese, il punto e ogni carattere dell'identificativo viaggiano insieme. Bird valida la forma prima di accettare un invio, e il codice paese deve essere maiuscolo e un codice ISO 3166 alpha-2 reale; un prefisso minuscolo o sconosciuto viene rifiutato, non corretto. Il limite di 128 caratteri si applica all'identificativo dopo il codice paese, e dopo il segmento `ENT.` in un parent BSUID.
- **È circoscritto a un portfolio aziendale.** Qualsiasi numero di telefono aziendale nello stesso portfolio può inviare messaggi a quel BSUID; un numero in un portfolio diverso no, e l'invio fallisce.
- **Non è permanente.** Meta documenta che il BSUID di un contatto viene rigenerato quando cambia numero di telefono, quindi identifica un interlocutore anziché fungere da chiave cliente duratura.

## Come si svolge di solito una conversazione

Un contatto con cui non hai mai parlato ti raggiunge tramite BSUID, e lo scambio che ti porta il suo numero si svolge in tre passaggi:

1. **Il contatto ti scrive.** Il messaggio in entrata porta `from.bsuid`, e `from.phone_number` può essere assente. Quel messaggio apre la [finestra di assistenza clienti](/docs/knowledge-base/whatsapp/customer-service-window), e puoi rispondere liberamente per le 24 ore successive.
2. **Chiedi il numero.** Invia una [richiesta di informazioni di contatto](/docs/guides/whatsapp/message-types/interactive/contact-info-requests), un singolo pulsante che consente al contatto di condividere un numero di telefono. La stessa richiesta può viaggiare su un template tramite il suo pulsante `request_contact_info`, che raggiunge un contatto la cui finestra si è chiusa.
3. **Il contatto tocca il pulsante.** Il numero condiviso arriva come [scheda contatto](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) in entrata con `origin` impostato su `contact_request` e il numero in `phone_numbers`. Una scheda contatto condivisa può descrivere un'altra persona o un altro numero. Conserva quei dati condivisi separatamente dall'identità WhatsApp del mittente; usa le identità effettivamente fornite nei messaggi successivi invece di sovrascrivere il record cliente basandoti solo sulla scheda.

Un contatto può rifiutare. Chiudere il foglio di condivisione non produce né un messaggio né un webhook, quindi un flusso che necessita del numero deve andare in timeout autonomamente anziché attendere un rifiuto, e deve continuare a funzionare per un contatto che non condivide mai il numero.

## Invio a un BSUID

`to` accetta un BSUID ovunque accetti un numero di telefono:

```json
{
  "to": "US.13491208655302741918",
  "from": "+13124495648",
  "text": { "body": "Your order shipped." }
}
```

Quattro aspetti differiscono da un invio indirizzato tramite numero di telefono:

- **`from` deve trovarsi nel portfolio a cui il BSUID è circoscritto.** È lo stesso requisito di portfolio che Meta applica, e una mancata corrispondenza fallisce a livello di WhatsApp anziché in fase di accettazione.
- **I template per codici di verifica monouso richiedono un numero di telefono.** Un template gestito da Bird nella categoria `authentication`, o uno che contiene un pulsante per codice di verifica monouso, viene rifiutato in fase di accettazione con un `422` [`E15014`](/docs/api/errors/E15014) `WhatsAppRecipientNotSupportedForTemplate`. Un template creato dal tuo spazio di lavoro non viene verificato in fase di accettazione: Meta richiede un numero di telefono per i template di autenticazione one-tap, zero-tap e copy-code, quindi un invio di questo tipo viene accettato e poi fallisce.
- **Un valore che non è né un numero di telefono né un BSUID ben formato viene rifiutato in fase di accettazione**, con un `422` [`E15001`](/docs/api/errors/E15001) `WhatsAppInvalidRecipient`.
- **Il prezzo si basa sul prefisso paese del BSUID.** Un numero di telefono fornisce il paese su cui viene calcolato il prezzo del messaggio; per un invio tramite BSUID, il prefisso di due lettere lo fornisce al suo posto.

Tutto il resto dell'invio rimane invariato: la [finestra di assistenza clienti](/docs/guides/whatsapp/message-types#the-customer-service-window) continua a regolare i contenuti liberi, e `202` continua a significare accettato, non consegnato.

**Indirizza un contatto sull'identità con cui ti ha scritto.** Bird registra una finestra aperta per ogni identità portata dal messaggio in entrata, e un invio trova la finestra sotto l'identità a cui è indirizzato. Un contatto che ti ha raggiunto solo tramite BSUID non lascia alcuna finestra associata al numero di telefono, quindi un invio libero verso un numero di telefono in tuo possesso da altra fonte può essere rifiutato con un `422` [`E15044`](/docs/api/errors/E15044) `WhatsAppServiceWindowClosed` mentre Meta considera ancora aperta la conversazione. Rispondere al `from` del messaggio evita la mancata corrispondenza.

## Lettura e filtro per BSUID

Ogni lettura porta tutte le identità presenti nel messaggio:

- **Su un messaggio**, `from` e `to` contengono ciascuno un `phone_number`, un `bsuid`, o entrambi. Un messaggio in entrata indica il contatto su `from`; uno in uscita lo indica su `to`.
- **Su un webhook**, gli stessi indirizzi viaggiano sul payload dell'evento. Vedi [eventi WhatsApp](/docs/guides/whatsapp/events#the-event-envelope) per la struttura.
- **Nell'elenco messaggi**, `to` e `from` accettano ciascuno un BSUID oltre che un numero di telefono, e ciascuno corrisponde a un'estremità del messaggio. Il filtro `bsuid` corrisponde al contatto in entrambe le direzioni. Il filtro precedente `phone_number` è deprecato: `to` e `from` lo sostituiscono e corrispondono a entrambi i tipi di identità.

Memorizza entrambe le identità nel tuo record contatto e indicizza il record sul tuo identificativo, non su quelli di Meta. Un contatto può arrivare solo con un BSUID, ottenere un numero di telefono quando lo condivide e ricevere un nuovo BSUID se cambia numero.

## Prossimi passi

- [Ricezione di schede contatto](/docs/guides/whatsapp/receiving-whatsapp/contact-cards): il tipo di contenuto con cui arriva il numero condiviso
- [Richieste di informazioni di contatto WhatsApp](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): il pulsante che lo chiede
- [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): la struttura della richiesta, il modello `202` e come riprovare in sicurezza
- [Riferimento business-scoped user IDs di Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids): il rollout, i parent BSUID e le altre superfici Meta

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)