Eine Integration der WhatsApp Business API erkennt einen Kunden, der einen WhatsApp-Benutzernamen verwendet, an einer Business-Scoped User ID (BSUID), einem Code, der für jedes Paar aus Kunde und Business-Portfolio eindeutig ist. Der Webhook enthält weiterhin die Telefonnummer, wenn dieselbe geschäftliche Nummer in den letzten 30 Tagen eine Nachricht oder einen Anruf mit dem Kunden ausgetauscht hat. Die Nummer bleibt außerdem in den Webhooks, wenn der Kunde im Kontaktbuch steht, einer Liste, in der Meta Telefonnummern aus früheren Konversationen speichert. Jede andere Nachricht von einem Kunden mit Benutzernamen kommt mit einer BSUID und ohne Telefonnummer an. Ein Webhook-Handler muss Nachrichten annehmen, die mit einer BSUID und ohne Telefonnummer ankommen. Lehnt er sie ab, gehen diese Nachrichten verloren, und Meta kann sie nicht erneut senden.
Das Wichtigste auf einen Blick
- Meta verlangt von Partnern, direkt integrierten Unternehmen und Werbetreibenden mit Click-to-WhatsApp Ads auf der WhatsApp Business Platform, BSUIDs zu unterstützen.
- Die Telefonnummer eines Kunden kommt noch 30 Tage nach einer Nachricht oder einem Anruf über dieselbe geschäftliche Nummer an und außerdem so lange, wie der Kunde im Kontaktbuch steht.
- Eine Nachricht kann an eine BSUID, an eine Telefonnummer oder an beide gehen, und nur Authentifizierungs-Templates vom Typ One-Tap, Zero-Tap und Code kopieren brauchen weiterhin die Telefonnummer.
- Braucht ein Unternehmen eine Telefonnummer, kann es im Chat per Button danach fragen, und der Kunde entscheidet, ob er sie teilt.
- 360Dialog, ein Official Meta Solution Partner, bietet Unternehmen Zugang zur WhatsApp Business API, die BSUIDs als Empfänger von Nachrichten akzeptiert.
Was ist eine Business-Scoped User ID (BSUID)?
Eine Business-Scoped User ID (BSUID) ist eine Kennung, die WhatsApp für jedes Paar aus Kunde und Business-Portfolio erzeugt, und sie kommt in Webhooks an, egal ob der Kunde einen Benutzernamen hat oder nicht. Speichert eine Integration die BSUID, hat sie einen Kundenschlüssel, der weiter funktioniert, wenn ein Kunde seine Telefonnummer nicht mehr teilt.
Ein Benutzername ist ein optionaler, eindeutiger Name, den ein WhatsApp-Nutzer anstelle seiner Telefonnummer anzeigen kann, und WhatsApp führt Benutzernamen schrittweise ein.[1] Unser Leitfaden zu WhatsApp-Benutzernamen für Unternehmen erklärt, was sich für Kunden und für die Teams ändert, die ihnen antworten.
Meta verlangt von jedem Partner und jedem direkt integrierten Unternehmen auf der WhatsApp Business Platform, BSUIDs zu unterstützen, und die Anforderung gilt auch für Werbetreibende mit Click-to-WhatsApp Ads.[2] BSUIDs erscheinen seit Anfang April 2026 in Webhooks. In der Cloud API steht der Wert im Feld user_id jedes messages-Webhooks.
Speichere und sende jede BSUID vollständig, denn eine Anfrage mit einem fehlenden oder veränderten Teil schlägt fehl. Eine Datenbankspalte dafür braucht Platz für den Ländercode aus zwei Buchstaben, den Punkt und bis zu 128 Buchstaben und Ziffern danach. Jede BSUID gilt innerhalb eines Business-Portfolios, früher Business Manager genannt, und nur die geschäftlichen Telefonnummern dieses Portfolios können ihr Nachrichten senden. Derselbe Kunde hat deshalb in jedem Portfolio eine andere BSUID.
Wann liefert die API noch die Telefonnummer eines Kunden?
Webhooks enthalten die Telefonnummer eines Kunden weiterhin, wenn diese geschäftliche Telefonnummer in den letzten 30 Tagen eine Nachricht oder einen Anruf mit dem Kunden ausgetauscht hat oder wenn der Kunde im Kontaktbuch des Unternehmens steht. Weiß ein Team, welcher Fall zutrifft, erkennt es, welche Konversationen zuerst BSUID-Unterstützung brauchen.
Laut Metas BSUID-Dokumentation entscheiden fünf Situationen, welche Kennungen ein Webhook enthält.
| Situation | Telefonnummer | BSUID |
|---|---|---|
| Kunde hat keinen Benutzernamen | Enthalten | Enthalten |
| Kunde hat einen Benutzernamen, und diese geschäftliche Nummer hat in den letzten 30 Tagen eine Nachricht oder einen Anruf mit ihm gesendet oder empfangen | Enthalten | Enthalten |
| Kunde hat einen Benutzernamen und steht im Kontaktbuch des Portfolios | Enthalten | Enthalten |
| Kunde hat einen Benutzernamen und teilt seine Nummer über den Button „Request Contact Info“ | Enthalten in einem contacts-Webhook | Enthalten |
| Kunde hat einen Benutzernamen und erfüllt keine der Bedingungen oben | Nicht enthalten | Enthalten |
Die 30-Tage-Prüfung läuft pro geschäftlicher Telefonnummer, während das Kontaktbuch das gesamte Portfolio abdeckt. Ein wiederkehrender Kunde, der keine der beiden Bedingungen erfüllt, kann wie eine neue Konversation aussehen. Anrufe zählen wie Nachrichten, auch Anrufe über die WhatsApp Calling API. Für eine Konversation, die über Click-to-WhatsApp Ads beginnt, gelten dieselben Bedingungen.
Wie funktioniert das Kontaktbuch in der API?
Das Kontaktbuch ist eine Liste, die Meta für jedes Business-Portfolio führt, und es speichert die Telefonnummer eines Kunden neben seiner BSUID, sobald Kunde und Unternehmen eine Nachricht oder einen Anruf ausgetauscht haben. Solange ein Kunde darin steht, enthalten Webhooks seine Telefonnummer auch nach Ablauf des 30-Tage-Fensters. Mit zwei API-Aufrufen kann eine Integration einzelne Einträge prüfen und entfernen.
Das Kontaktbuch braucht keine Einrichtung, und Einträge bleiben, bis das Unternehmen die Funktion in der Meta Business Suite unter „Unternehmenseinstellungen“ > „Unternehmensinfo“ ausschaltet oder sein Konto deaktiviert. Beim Ausschalten werden alle Einträge endgültig gelöscht. Das Kontaktbuch erfasst nur Interaktionen nach seiner Einführung durch Meta, und seine Telefonnummern erscheinen nur in Webhook-Payloads.
Meta hat den Prüfaufruf am 24. August 2026 hinzugefügt und die Antwort des Löschaufrufs am 25. August 2026 geändert.[3] Beide Aufrufe nehmen eine einzelne Standard-BSUID an und lehnen übergeordnete BSUIDs ab.
| Aufruf | Anfrage | Antwort |
|---|---|---|
| Prüfen | GET /<BUSINESS_PHONE_NUMBER_ID>/contact_book?messaging_product=whatsapp&bsuid=<BSUID> | contacts mit bsuid und present (true oder false), nie die Telefonnummer |
| Löschen | DELETE auf demselben Pfad | success und deleted, wobei deleted für jede BSUID ohne Eintrag false ist |
Der Wert false für deleted sieht bei einer unbekannten BSUID, einer ungültigen BSUID und einer BSUID aus einem anderen Portfolio gleich aus. Nach einer Löschung kann die Telefonnummer innerhalb des 30-Tage-Fensters oder nach einer neuen Interaktion trotzdem wieder erscheinen.
Wie fragst du mit dem Button „Request Contact Info“ nach einer Telefonnummer?
Der Button „Request Contact Info“ bittet einen Kunden, seine Telefonnummer im Chat zu teilen, und die Nummer kommt in einem contacts-Webhook neben der BSUID zurück. So kann jeder Ablauf, der eine Telefonnummer braucht, sie innerhalb der Konversation und mit Zustimmung des Kunden erfassen.
Der Button ist seit Anfang Juli 2026 in Utility- und Marketing-Templates und in einer interaktiven Nachricht verfügbar. Eine so geteilte Nummer landet außerdem automatisch im Kontaktbuch, wenn das Unternehmen es nutzt. Meta empfiehlt Bots, die eine Nummer brauchen, danach zu fragen und mit Kunden umzugehen, die ablehnen.
Wie sendest du Nachrichten an eine BSUID?
Ein Unternehmen sendet eine Nachricht an eine BSUID mit derselben Sendeanfrage, die es für Telefonnummern nutzt, und die BSUID steht dabei in einem eigenen Feld. Mit Nachrichten per BSUID kann ein Unternehmen weiter mit Kunden schreiben, deren Telefonnummer es nie erhalten hat.
Meta datiert den Versand an BSUIDs auf Juli 2026. Eine Anfrage nennt den Kunden per Telefonnummer, per BSUID oder mit beidem, und die Telefonnummer hat Vorrang, wenn beide vorhanden sind.
Jeder Nachrichtentyp funktioniert mit einer BSUID, außer Authentifizierungs-Templates vom Typ One-Tap, Zero-Tap und Code kopieren, die weiterhin eine Telefonnummer brauchen. Die Marketing Messages API akzeptiert ebenfalls BSUIDs, und Meta empfiehlt dort Telefonnummern, weil Webhooks die Nummer dann weiter zurückgeben.
Unsere Dokumentation zu Benutzernamen und BSUID zeigt die vollständige Sendeanfrage, die Antwort und die Fehlercodes der 360Dialog API.[4]
Was ändert sich bei Webhooks?
Webhooks enthalten jetzt die BSUID des Kunden in jeder eingehenden Nachricht und in den Statusmeldungen für gesendete, zugestellte und gelesene Nachrichten, und die Telefonnummer erscheint nur, wenn eine von Metas Bedingungen für die Telefonnummer zutrifft. Ein Parser, der die BSUID als Pflichtkennung behandelt, verarbeitet weiterhin jede Nachricht.
Die BSUID steht in denselben Payloads neben der Telefonnummer, in eigenen Feldern. Die Felder für die Telefonnummer erscheinen, wenn der Kunde keinen Benutzernamen hat, wenn eine Bedingung für die Telefonnummer zutrifft oder wenn die Nachricht an eine Telefonnummer ging, und der Benutzername des Kunden kommt als Profilangabe an, wenn er einen hat. Felder, die nicht zutreffen, fehlen im Payload.
Ändert ein Kunde seine Telefonnummer, erhält er eine neue BSUID, die der messages-Webhook als Systemnachricht vom Typ user_changed_number oder user_changed_user_id meldet. Beide enthalten previous_user_id, die alte BSUID. Eine Integration findet damit den Kundendatensatz, der bereits gespeichert ist. Meta dokumentiert kein separates Webhook-Feld user_id_update.
Wie verwaltest du einen Unternehmens-Benutzernamen über die API?
Ein Unternehmen legt den Benutzernamen jeder geschäftlichen Telefonnummer über Metas Benutzernamen-API fest, liest ihn und löscht ihn, und die API meldet Statusänderungen per Webhook. Baut eine Plattform diese Aufrufe ein, kann ein Team die Benutzernamen vieler Nummern an einem Ort verfolgen.
Ein Unternehmen kann für jede geschäftliche Telefonnummer einen Benutzernamen festlegen oder ändern, seinen Status abrufen (genehmigt oder reserviert) und ihn löschen. Über einen Vorschlagsaufruf erhält es reservierte Namen, die mit höherer Wahrscheinlichkeit genehmigt werden. Ein genehmigter Benutzername wird aktiv, sobald Benutzernamen im Land des Unternehmens verfügbar sind. 360Dialog-Kunden nutzen dafür die Endpunkte für Unternehmens-Benutzernamen in unserer API-Referenz.[5]
Jede geschäftliche Telefonnummer kann in einem rollierenden Zeitraum von 14 Tagen 2 neue Benutzernamen festlegen, oder 10, wenn das Ergebnis den Status reserviert hat, und eine Anfrage über dem Limit schlägt fehl. Gezählt wird pro Nummer, und das Löschen eines Benutzernamens ändert den Zähler nicht.
Der Webhook business_username_updates, den jede App selbst abonniert, meldet die Status genehmigt, gelöscht und reserviert. Widerruft Meta einen Benutzernamen, meldet der Webhook das, und der Benutzername wird entweder gelöscht oder durch einen generierten ersetzt.
Wie funktionieren übergeordnete BSUIDs über mehrere Portfolios hinweg?
Eine übergeordnete BSUID (Parent BSUID) ist eine Kennung pro Kunde, die jedes Business-Portfolio nutzen kann, das im selben Konto für übergeordnete BSUIDs angemeldet ist. Damit erkennt ein von Meta betreutes Unternehmen mit mehreren Portfolios denselben Kunden in allen Portfolios.
Meta bietet übergeordnete BSUIDs für von Meta betreute Unternehmen an, und der Ansprechpartner des Unternehmens bei Meta prüft die Berechtigung. Webhooks enthalten die übergeordnete BSUID dann neben der regulären BSUID, in parent_user_id, from_parent_user_id und recipient_parent_user_id. Eine übergeordnete BSUID enthält nach dem Ländercode den Zusatz ENT, und jede geschäftliche Telefonnummer in einem angemeldeten Portfolio kann ihr Nachrichten senden.
Die Anmeldung lässt Zugriffskontrollen, Abrechnung und Verwaltung jedes Portfolios unverändert. Kontaktbücher bleiben pro Portfolio getrennt. Um die angemeldeten Portfolios aufzulisten, ruft ein Unternehmen GET https://api.facebook.com/<BUSINESS_ID>/parent-bsuid-accounts auf, und die Antwort enthält parent_bsuid_account_id und enrolled_business_portfolios.
Plattformen mit einer WhatsApp-Integration mit Multi-Tenancy halten die BSUIDs jedes Kundenunternehmens in dessen eigenem Portfolio.
Was sollte deine Integration jetzt abdecken?
Eine Integration, die für BSUIDs bereit ist, speichert die BSUID als zentrale Kundenkennung, behandelt die Telefonnummer als optional und fragt nur dort nach einer Nummer, wo ein Ablauf eine braucht. So bleibt jede Konversation mit dem richtigen Kundendatensatz verknüpft.
In der Praxis nehmen Webhook-Parser und Datenbankspalten Nachrichten an, die nur eine BSUID enthalten, und jeder Kundendatensatz speichert die BSUID neben der Telefonnummer. CRM-, Kampagnen-, Mess- und Abrechnungssysteme ordnen Kunden dann ebenfalls per BSUID zu. Abläufe, die eine Nummer brauchen, fragen mit dem Button „Request Contact Info“ danach und haben einen Weg für Kunden, die ablehnen, und Metas Webhook-Testtool prüft den Parser für jeden Fall. Teams, die KI-gestützte Antworten planen, lesen in unserem vollständigen Leitfaden zu Meta Business Agent, wie der KI-Agent mit der API arbeitet. Sobald jedes System Kunden per BSUID zuordnet, landet jede Konversation beim richtigen Kundendatensatz, und wer darauf antwortet, sieht den gesamten Verlauf.
360Dialog ist ein Official Meta Solution Partner für die WhatsApp Business API, und unsere Dokumentation zu Benutzernamen und BSUID enthält die Schritt-für-Schritt-Checkliste für die Integration mit den Sendeanfragen und Webhook-Payloads der 360Dialog API. Mit API starten, um die BSUID-Verarbeitung auf deiner eigenen Nummer für die WhatsApp Business API aufzubauen und zu testen. Sprich mit uns darüber, wie du deine Integration der WhatsApp Business API auf BSUIDs vorbereitest.
Häufig gestellte Fragen
Kann ein Unternehmen einem Kunden über seinen Benutzernamen schreiben?
Ein Unternehmen kann einen Benutzernamen in der WhatsApp Business API nicht als Empfängeradresse verwenden. Sendeanfragen akzeptieren eine Telefonnummer im Feld to oder eine BSUID im Feld recipient. Der Benutzername erreicht das Unternehmen in Webhooks als Profilangabe, und der Kunde kann ihn jederzeit ändern. Die BSUID bleibt bei dieser Änderung gleich und ist die Kennung, die eine Integration speichert.
Gehen Authentifizierungsnachrichten weiterhin an Telefonnummern?
Authentifizierungs-Templates vom Typ One-Tap, Zero-Tap und Code kopieren gehen weiterhin an die Telefonnummer des Kunden, und der Versand an eine BSUID schlägt mit dem Fehler 131062 fehl. Ein Unternehmen, das nur eine BSUID hat, kann zuerst mit dem Button „Request Contact Info“ nach der Nummer fragen. Sobald der Kunde sie teilt, sendet das Unternehmen das Authentifizierungs-Template an diese Nummer.
Wie testest du einen Webhook-Handler für BSUIDs?
Metas Webhook-Testtool sendet BSUID-Beispiel-Payloads aus dem App-Dashboard an einen Webhook-Handler. Öffne „Anwendungsfälle“, dann „Über WhatsApp mit Kunden in Kontakt treten“, „Anpassen“ und „Konfiguration“, und wähle „Testen“ neben dem Feld messages. Das Tool deckt vier Fälle ab: kein Benutzername, ein Benutzername ohne Telefonnummer, ein Benutzername mit Telefonnummer und ein Payload mit übergeordneter BSUID.
Müssen Partner die Integrationen ihrer Kundenunternehmen für BSUIDs anpassen?
Partner auf der WhatsApp Business Platform müssen BSUIDs unterstützen, und Meta stellt dieselbe Anforderung an direkt integrierte Unternehmen und Werbetreibende mit Click-to-WhatsApp Ads. Die App eines Partners kann die BSUIDs eines Kundenunternehmens über dessen eigene geschäftliche Telefonnummern anschreiben. Mit der eigenen Nummer des Partners schlägt die BSUID eines Kundenunternehmens fehl, weil jede BSUID zu genau einem Business-Portfolio gehört.
Quellen
[1] WhatsApp Help Center, „About usernames,“ https://faq.whatsapp.com/658755553162769/ (accessed October 29, 2026).
[2] Meta for Developers, „Business-scoped user IDs,“ updated October 23, 2026, https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/ (accessed October 29, 2026).
[3] Meta for Developers, „Changelog,“ https://developers.facebook.com/documentation/business-messaging/whatsapp/changelog/ (accessed October 29, 2026).
[4] 360Dialog documentation, „Usernames & BSUID,“ https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-bsuid (accessed October 29, 2026).
[5] 360Dialog documentation, „Business Username,“ https://docs.360dialog.com/docs/messaging-api/api-reference/business-username (accessed October 29, 2026).
