# Business-scoped User IDs

Eine **Business-scoped User ID** (BSUID) ist Metas Bezeichner für einen WhatsApp-Nutzer, auf ein Business-Portfolio beschränkt. Sie kommt bei eingehenden Nachrichten an, unabhängig davon, ob der Kontakt einen WhatsApp-Nutzernamen verwendet, und adressiert einen Kontakt, dessen Telefonnummer Sie nicht haben.

Bird stellt sie als `bsuid` auf `from` und `to` einer Nachricht bereit, akzeptiert sie als `to` eines Versands und filtert die Nachrichtenliste danach. Metas Referenz zu [Business-scoped User IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) ist die Quelle für den Rollout selbst und dafür, was andere Meta-Oberflächen mit dem Bezeichner tun.

## Warum ein Kontakt ohne Telefonnummer ankommt

WhatsApp führt Nutzernamen ein. Ein Nutzer, der einen annimmt, zeigt in der App seinen Nutzernamen anstelle seiner Telefonnummer, und Meta hält die Nummer dann aus den Payloads zurück, die ein Unternehmen erhält. Die BSUID ist die Identität, die immer vorhanden ist – deshalb kann eine eingehende Nachricht eine BSUID enthalten, aber keinerlei `phone_number`.

Meta liefert die Telefonnummer weiterhin mit, wenn Sie bereits eine Beziehung zum Kontakt haben: wenn diese bestimmte geschäftliche Telefonnummer den Kontakt in den letzten 30 Tagen angerufen oder ihm geschrieben hat oder einen Anruf oder eine Nachricht von ihm erhalten hat, oder wenn er in Ihrem Meta-Kontaktbuch steht. Die 30-Tage-Bedingung wird pro geschäftlicher Telefonnummer ausgewertet, sodass ein Kontakt, der einer Ihrer Nummern geschrieben hat, bei einer anderen trotzdem ohne Telefonnummer ankommen kann.

Eine Nachricht von einem WhatsApp-Nutzer enthält auch das veröffentlichte Profil, in `username` und `display_name` auf `from`. Beide fehlen, wenn der Kontakt keinen Nutzernamen angenommen hat oder die Nachricht kein Profil enthält, und keines von beiden kann zum Adressieren einer Nachricht verwendet werden.

## Wie eine BSUID aussieht

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

Ein ISO-3166-Alpha-2-Ländercode, ein Punkt, dann bis zu 128 alphanumerische Zeichen. Eine **Parent-BSUID**, für die ein verwaltetes Unternehmen registriert werden kann, damit ein Bezeichner über mehrere Portfolios hinweg funktioniert, fügt `ENT` nach dem Ländercode ein: `US.ENT.11815799212886844830`. Bird akzeptiert beide Formen als Empfänger.

Drei Eigenschaften bestimmen, wie Sie eine BSUID speichern und verwenden:

- **Übergeben Sie den gesamten Wert unverändert.** Meta lehnt eine modifizierte BSUID ab, daher ist kein Teil optional: Ländercode, Punkt und jedes Zeichen des Bezeichners gehören zusammen. Bird validiert die Form vor der Annahme eines Versands, und der Ländercode muss in Großbuchstaben und ein gültiger ISO-3166-Alpha-2-Code sein; ein kleingeschriebenes oder unbekanntes Präfix wird abgelehnt statt korrigiert. Die 128-Zeichen-Grenze gilt für den Bezeichner nach dem Ländercode und nach dem `ENT.`-Segment bei einer Parent-BSUID.
- **Sie ist auf ein Business-Portfolio beschränkt.** Jede geschäftliche Telefonnummer im selben Portfolio kann diese BSUID anschreiben; eine Nummer in einem anderen Portfolio kann das nicht, und der Versand schlägt fehl.
- **Sie ist nicht dauerhaft.** Meta dokumentiert, dass die BSUID eines Kontakts neu generiert wird, wenn er seine Telefonnummer ändert. Sie identifiziert also einen Gesprächspartner, anstatt als dauerhafter Kundenschlüssel Ihrerseits zu dienen.

## Wie eine Konversation üblicherweise abläuft

Ein Kontakt, mit dem Sie noch nicht gesprochen haben, erreicht Sie per BSUID, und der Austausch, der Ihnen seine Nummer liefert, läuft in drei Schritten ab:

1. **Der Kontakt schreibt Ihnen.** Die eingehende Nachricht enthält `from.bsuid`, und `from.phone_number` kann fehlen. Diese Nachricht öffnet das [Kundenservice-Fenster](/docs/knowledge-base/whatsapp/customer-service-window), sodass Sie in den nächsten 24 Stunden frei antworten können.
2. **Sie fragen nach der Nummer.** Senden Sie eine [Kontaktinfo-Anfrage](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) – eine einzelne Schaltfläche, über die der Kontakt eine Telefonnummer teilen kann. Dieselbe Anfrage lässt sich auch über ein Template mit dessen `request_contact_info`-Button stellen, das einen Kontakt erreicht, dessen Fenster bereits geschlossen ist.
3. **Der Kontakt tippt auf die Schaltfläche.** Die freigegebene Nummer kommt als eingehende [Kontaktkarte](/docs/guides/whatsapp/receiving-whatsapp/contact-cards) an, mit `origin` auf `contact_request` und der Nummer in `phone_numbers`. Eine freigegebene Kontaktkarte kann auch eine andere Person oder Nummer beschreiben. Speichern Sie diese Freigabe getrennt von der WhatsApp-Identität des Absenders; verwenden Sie die tatsächlich in nachfolgenden Nachrichten gelieferten Identitäten, statt den Kundendatensatz allein anhand der Karte zu überschreiben.

Ein Kontakt kann ablehnen. Das Schließen des Teilen-Dialogs erzeugt keine Nachricht und keinen Webhook. Ein Flow, der eine Nummer benötigt, muss daher selbst ein Timeout setzen, anstatt auf eine Ablehnung zu warten, und er muss auch für einen Kontakt funktionieren, der seine Nummer nie teilt.

## An eine BSUID senden

`to` akzeptiert eine BSUID überall dort, wo es eine Telefonnummer akzeptiert:

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

Vier Dinge unterscheiden sich von einem Versand, der per Telefonnummer adressiert wird:

- **`from` muss im Portfolio liegen, auf das die BSUID beschränkt ist.** Das ist dieselbe Portfolio-Anforderung, die Meta stellt, und eine Nichtübereinstimmung schlägt bei WhatsApp fehl statt bei der Annahme.
- **Einmalpasswort-Templates benötigen eine Telefonnummer.** Ein von Bird verwaltetes Template in der Kategorie `authentication` oder eines mit einem Einmalpasswort-Button wird bei der Annahme mit einem `422`-Fehler [`E15014`](/docs/api/errors/E15014) `WhatsAppRecipientNotSupportedForTemplate` abgelehnt. Ein Template, das Ihr Workspace erstellt hat, wird bei der Annahme nicht geprüft: Meta verlangt eine Telefonnummer für One-Tap-, Zero-Tap- und Copy-Code-Authentifizierungs-Templates, sodass ein solcher Versand angenommen wird und dann fehlschlägt.
- **Ein Wert, der weder eine Telefonnummer noch eine wohlgeformte BSUID ist, wird bei der Annahme abgelehnt**, mit einem `422`-Fehler [`E15001`](/docs/api/errors/E15001) `WhatsAppInvalidRecipient`.
- **Der Preis richtet sich nach dem Länderpräfix der BSUID.** Eine Telefonnummer liefert das Land, nach dem eine Nachricht bepreist wird, und bei einem BSUID-Versand übernimmt das zweistellige Präfix diese Rolle.

Alles Weitere am Versand bleibt unverändert: Das [Kundenservice-Fenster](/docs/guides/whatsapp/message-types#the-customer-service-window) bestimmt weiterhin, ob Freitext-Inhalte erlaubt sind, und `202` bedeutet weiterhin angenommen, nicht zugestellt.

**Adressieren Sie einen Kontakt mit der Identität, mit der er Ihnen geschrieben hat.** Bird verzeichnet ein offenes Fenster unter jeder Identität, die die eingehende Nachricht enthielt, und ein Versand findet das Fenster unter der Identität, an die er adressiert ist. Ein Kontakt, der Sie nur per BSUID erreicht hat, hinterlässt kein telefonnummerbasiertes Fenster. Ein Freitext-Versand an eine Telefonnummer, die Sie anderweitig haben, kann daher mit einem `422`-Fehler [`E15044`](/docs/api/errors/E15044) `WhatsAppServiceWindowClosed` abgelehnt werden, obwohl Meta die Konversation noch als offen betrachtet. Eine Antwort an die `from` der Nachricht vermeidet die Nichtübereinstimmung.

## Lesen und Filtern nach BSUID

Jedes Lesen liefert die Identitäten, die die Nachricht enthält:

- **Auf einer Nachricht** enthalten `from` und `to` jeweils eine `phone_number`, eine `bsuid` oder beides. Eine eingehende Nachricht benennt den Kontakt auf `from`; eine ausgehende benennt ihn auf `to`.
- **Auf einem Webhook** sind dieselben Adressen im Event-Payload enthalten. Siehe [WhatsApp-Events](/docs/guides/whatsapp/events#the-event-envelope) für die Struktur.
- **In der Nachrichtenliste** akzeptieren `to` und `from` jeweils eine BSUID ebenso wie eine Telefonnummer, und jeder Filter trifft ein Ende der Nachricht. Der `bsuid`-Filter trifft den Kontakt in beiden Richtungen. Der ältere `phone_number`-Filter ist veraltet: `to` und `from` ersetzen ihn und treffen beide Arten von Identität.

Speichern Sie beide Identitäten zu Ihrem eigenen Kontaktdatensatz und verwenden Sie Ihren eigenen Bezeichner als Schlüssel, nicht einen von Meta. Ein Kontakt kann Sie zunächst nur mit einer BSUID erreichen. Sobald er seine Telefonnummer teilt, ist Ihnen auch diese bekannt; wenn er die Nummer wechselt, erhält er eine neue BSUID.

## Nächste Schritte

- [Kontaktkarten empfangen](/docs/guides/whatsapp/receiving-whatsapp/contact-cards): der Kanal, über den die geteilte Nummer ankommt
- [WhatsApp-Kontaktinfo-Anfragen](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): der Button, der danach fragt
- [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp): die Anfrage-Struktur, das `202`-Modell und sicheres erneutes Versuchen
- [Metas Referenz zu Business-scoped User IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids): der Rollout, Parent-BSUIDs und die übrigen Meta-Oberflächen

## 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)