WhatsApp-Benutzernamen und geschäftsbezogene Nutzer-IDs (BSUID): Was sich bei Cloud-API-Webhooks ändert
WhatsApp-Benutzernamen erlauben es Nutzern, statt ihrer Telefonnummer einen Namen anzuzeigen. Seit Anfang April 2026 enthalten Cloud-API-Webhooks für Nachrichten daher auch eine geschäftsbezogene Nutzer-ID (BSUID), etwa US.13491208655302741918, in user_id und from_user_id. Bei einem Nutzer mit Benutzernamen, der in 30 Tagen keine Nachricht oder keinen Anruf mit der Nummer hatte und nicht im Adressbuch steht, werden wa_id und from weggelassen.
easyCoexistence verbindet eine Nummer der WhatsApp Business App über Coexistence mit der Cloud API und leitet ihre Webhooks messages und smb_message_echoes so an Ihren Endpoint weiter, wie Meta sie sendet, einschließlich der BSUID-Felder.
Wann BSUIDs erstmals in Cloud-API-Webhooks auftauchten, noch bevor Benutzernamen die WhatsApp-Nutzer erreichten.
Wann die APIs begannen, Nachrichten an eine BSUID anzunehmen, angegeben in recipient statt in to.
Rückblickfrist pro Telefonnummer des Unternehmens, innerhalb derer jede Nachricht oder jeder Anruf mit dem Nutzer dessen Nummer in den Webhooks belässt.
Die meisten alphanumerischen Zeichen nach dem zweistelligen Ländercode und dem Punkt einer BSUID.
Messages-API-Fehler: Empfänger mit geschäftsbezogener Nutzer-ID (BSUID) werden für diese Nachricht nicht unterstützt.
Systemnachrichtentyp für eine BSUID-Änderung, die ohne Telefonnummer gemeldet wird, mit der alten BSUID in previous_user_id.
Was sind WhatsApp-Benutzernamen und BSUIDs?
Ein Benutzername ist ein optionaler, eindeutiger Name, den ein WhatsApp-Nutzer festlegen kann und der in der App anstelle seiner Telefonnummer angezeigt wird; Meta führt Benutzernamen im Jahr 2026 schrittweise ein. Eine BSUID ist die Backend-Kennung, die Meta eingeführt hat, damit Unternehmen ihre Nutzer weiterhin unterscheiden können: Sie wird automatisch erzeugt, ist für jede Kombination aus Business Portfolio und Nutzer eindeutig und besteht aus dem zweistelligen Ländercode nach ISO 3166, einem Punkt und bis zu 128 alphanumerischen Zeichen. Meta verlangt von Partnern und direkt angebundenen Unternehmen, sie zu unterstützen, denn kein Unternehmen kann bestimmen, ob seine Nutzer Benutzernamen übernehmen.
Welche Felder tragen die neuen Kennungen?
Neue Eigenschaften neben denjenigen, die die Telefonnummer enthielten, in den Webhooks messages, status, system und user_preferences. Die übergeordneten Felder erscheinen nur bei Business Portfolios, die Meta für übergeordnete BSUIDs freigeschaltet hat; diese funktionieren über alle freigeschalteten Portfolios hinweg:
Wann wird die Telefonnummer weggelassen?
Wenn der Nutzer einen Benutzernamen hat und keine der drei Bedingungen von Meta zutrifft. Die Nummer bleibt in den Webhooks erhalten, wenn die Geschäftsrufnummer dem Nutzer in den letzten 30 Tagen eine Nachricht geschickt oder ihn angerufen hat, in diesem Zeitraum eine Nachricht oder einen Anruf von ihm erhalten hat oder der Nutzer im Adressbuch des Portfolios steht. Die 30-Tage-Frist wird pro Geschäftsrufnummer gezählt, daher kann eine zweite Nummer im selben Portfolio für denselben Nutzer nur die BSUID erhalten. Nutzer ohne Benutzernamen kommen weiterhin mit ihrer Telefonnummer und ihrer BSUID an.
Wie sieht eine eingehende Nachricht jetzt aus?
Wie bisher, mit der BSUID neben der Telefonnummer oder an deren Stelle. In Metas Beispiel für einen Nutzer mit Benutzernamen, dessen Nummer nicht geteilt werden kann, enthält contacts profile.name, profile.username und user_id, und die Nachricht enthält from_user_id an der Stelle, an der früher from stand:
{
"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?" }
}]
}
}]
}]
}Wie ändern sich die Status-Webhooks?
Gesendet-, zugestellt- und gelesen-Status erhalten ein Array contacts mit Name, user_id, wa_id, sofern die Nummer geteilt werden kann, und bei zugestellt und gelesen zusätzlich username. Bei Status enthält recipient_user_id die BSUID, und recipient_id entfällt, wenn Sie an eine BSUID gesendet haben und die Nummer nicht geteilt werden kann. Ein fehlgeschlagener Status hat kein Array contacts und lässt recipient_user_id weg, wenn die Nachricht an eine Telefonnummer ging; ordnen Sie Fehler daher über die Nachrichten-ID zu.
Wie sollten Sie Nutzer speichern und zuordnen?
Zuerst über die BSUID, mit der Telefonnummer als zweitem Schlüssel, sobald sie eintrifft. Speichern Sie die gesamte BSUID als Zeichenkette, einschließlich Ländercode und Punkt, da Meta Anfragen ablehnt, die einen Teil davon verändern, und speichern Sie auch die übergeordnete BSUID, falls Ihre Portfolios freigeschaltet sind. Verknüpfen Sie bestehende Datensätze über wa_id, solange das Feld noch eintrifft, und behalten Sie die BSUID daneben, denn ein Nutzer, der später einen Benutzernamen übernimmt, kann ohne Nummer zurückkehren. Metas FAQ empfiehlt dieselben Verknüpfungen in CRM-Systemen und in den Tools, die sie speisen.
Was passiert, wenn ein Nutzer seine Telefonnummer ändert?
Seine BSUID wird neu erzeugt, und die Änderung kommt im Feld messages als Systemnachricht an, da Meta kein Feld user_id_update zum Abonnieren bietet. system.type ist user_changed_number, wenn die neue Nummer mit Ihnen geteilt werden kann, oder user_changed_user_id, wenn nur die Änderung der BSUID gemeldet werden kann. system.user_id enthält die neue BSUID und system.previous_user_id die alte, sodass ein Datensatz übernommen werden kann. Behandeln Sie beide Typen.
Wie antworten Sie einem Nutzer, der nur über eine BSUID bekannt ist?
Senden Sie an /<BUSINESS_PHONE_NUMBER_ID>/messages mit recipient auf die BSUID gesetzt und ohne to; sind beide vorhanden, hat to Vorrang und die Antwort geht an die Telefonnummer. Der Eintrag contacts in der Antwort enthält dann input und user_id statt wa_id. Jeder Nachrichtentyp funktioniert, außer One-Tap-, Zero-Tap- und Copy-Code-Authentifizierungs-Templates, die eine Telefonnummer benötigen. Außerdem erreichen nur Nummern im selben Business Portfolio eine BSUID. Fehler 131062 bedeutet, dass der Nachrichtentyp keine BSUID-Empfänger akzeptiert.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"recipient": "US.13491208655302741918",
"type": "text",
"text": { "body": "Yes, it also comes in blue." }
}Wie fragen Sie einen Nutzer nach seiner Telefonnummer?
Mit dem Button REQUEST_CONTACT_INFO, der einem Utility- oder Marketing-Template hinzugefügt oder als interaktive Nachricht vom Typ request_contact_info gesendet wird. Tippt ein Nutzer darauf, teilt er seine Nummer im Chat, und ein Webhook contacts trifft mit origin auf contact_request und der Nummer in phones[].wa_id ein. Ein von Hand geteilter Kontakt kommt mit origin other und einer vCard an. Meta hat den Button Anfang Juli 2026 verfügbar gemacht, seine Beschriftung lässt sich nicht anpassen.
Was ist das Adressbuch?
Ein von Meta für jedes Business Portfolio gehosteter Speicher, ohne Integrationsaufwand: Sobald eine Geschäftsrufnummer einem Nutzer schreibt, ihn anruft oder von ihm eine Nachricht oder einen Anruf erhält, werden dessen Telefonnummer und die BSUID gespeichert. Sie dienen dazu, spätere Webhooks mit der Telefonnummer, dem Benutzernamen oder beidem zu ergänzen, unabhängig davon, ob der Nutzer einen Benutzernamen hat. Nur Interaktionen nach dem Start zählen. Das Adressbuch lässt sich in Meta Business Suite unter Geschäftseinstellungen, Unternehmensinformationen ausschalten; dabei werden die gespeicherten Daten gelöscht. GET oder DELETE an /<BUSINESS_PHONE_NUMBER_ID>/contact_book mit einer bsuid prüft oder entfernt einen einzelnen Eintrag.
Was sollte eine Coexistence-Integration ändern?
Ihre Verarbeitung der drei Webhooks, die nur eine Coexistence-Nummer erhält; auch diese ändern sich. Im Verlauf erhält jede Unterhaltung ein Objekt context mit wa_id, user_id und username, und ihre Nachrichten erhalten from_user_id. In smb_message_echoes kommt ein Array contacts hinzu, und message_echoes[].to kann entfallen, während to_user_id die BSUID enthält. Bearbeitungen und Widerrufe, die in der WhatsApp Business App vorgenommen werden, kommen auf dieselbe Weise an. In smb_app_state_sync kann phone_number eines Kontakts entfallen, daneben stehen user_id und username. Gleichen Sie Echos und importierte Chats auch über user_id ab, nicht nur über die Nummer.
Wie können Sie testen, bevor Nutzer Benutzernamen übernehmen?
Mit Metas Testwerkzeug im App Dashboard: Unter Use Cases, Connect with customers through WhatsApp, Customize, Configuration sendet der Link Test neben dem Webhook messages ein Beispiel an Ihren Endpoint. Er deckt eingehende Nachrichten und Status in vier Szenarien ab:
- Ein Nutzer ohne Benutzernamen: Felder für BSUID und Telefonnummer, kein Benutzername.
- Ein Nutzer mit Benutzernamen, dessen Nummer nicht verfügbar ist: Benutzername und BSUID, ohne Felder für die Telefonnummer.
- Ein Nutzer mit Benutzernamen, dessen Nummer verfügbar ist: Benutzername, BSUID und Telefonnummer.
- Ein Portfolio mit übergeordneten BSUIDs: eine übergeordnete BSUID neben der eigenen BSUID des Portfolios.
Wie geht easyCoexistence mit BSUIDs um?
Wir leiten sie so weiter, wie Meta sie sendet. Eine Nummer, die Sie mit set_webhook_destination an Ihren Endpoint leiten, erhält ihre Webhooks messages und smb_message_echoes direkt von Meta, einschließlich user_id, from_user_id, to_user_id und username. Mit aktivierten Automatisierungen oder Weiterleitung gibt easyCoexistence den von Meta gesendeten Wert unverändert weiter. Um einer BSUID zu antworten, nutzt Ihr Code get_api_credentials, das die Phone Number ID der Nummer, ihren Send-Endpoint und, falls verfügbar, Ihr eigenes Token liefert. Die Werkzeuge send_message und send_template erwarten eine Telefonnummer in internationalen Ziffern.
Häufige Fehler
- Kontakte allein anhand von wa_id ablegen. Ein Nutzer mit Benutzernamen, der 30 Tage lang keinen Kontakt zur Nummer hatte, kommt nur mit user_id und from_user_id an, und ein Handler, der wa_id verlangt, verpasst die Nachricht.
- Den Ländercode einer BSUID abschneiden. Meta verlangt den gesamten Wert, einschließlich Ländercode und Punkt, und jede Anfrage mit einem veränderten Teil schlägt fehl.
- Auf ein Feld user_id_update warten. Meta bietet keines: BSUID-Änderungen kommen über messages als Systemnachrichten vom Typ user_changed_number oder user_changed_user_id an.
- Coexistence-Echos nur über to abgleichen. In smb_message_echoes kann das Feld to entfallen, daher bleibt eine in der App getippte Antwort unbemerkt, solange nicht auch to_user_id abgeglichen wird.
get_api_credentials liefert Ihrem Code, was er zum Antworten mit recipient braucht. Jede Verbindung wird rund um die Uhr überwacht. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit den ersten 3 Tagen als kostenloser Testphase.
Häufig gestellte Fragen
Erhalten Nutzer ohne Benutzernamen ebenfalls eine BSUID?
Ja. Meta setzt user_id in den Webhooks messages, unabhängig davon, ob der Nutzer einen Benutzernamen hat. Deshalb kommen die meisten Nutzer sowohl mit ihrer Telefonnummer als auch mit ihrer BSUID an.
Kann eine Coexistence-Nummer einen Benutzernamen des Unternehmens haben?
Ja. Seit dem 29. Juni 2026 kann ein Unternehmen einen Benutzernamen in Meta Business Suite, im WhatsApp Manager, in der WhatsApp Business App oder über die Username API übernehmen oder ändern. Die Geschäftsnummer wird dadurch nicht verborgen, und business_username_updates meldet jede Statusänderung.
Funktioniert eine BSUID über Business Portfolios hinweg?
Nein. Eine BSUID gehört zu einem Portfolio und einem Nutzer, und eine Nummer aus einem anderen Portfolio kann sie nicht erreichen. Verwaltete Unternehmen, die Meta freischaltet, erhalten übergeordnete BSUIDs mit ENT nach dem Ländercode, die über ihre freigeschalteten Portfolios hinweg funktionieren.
Was kostet easyCoexistence für eine WhatsApp-Nummer?
US$ 9 bis US$ 0.75 pro Verbindung und Monat, je nach Anzahl Ihrer Verbindungen, und die ersten 3 Tage sind kostenlos. Metas eigene Nachrichtengebühren bleiben auf der Zahlungsmethode Ihres WhatsApp Business Account.
Weiterlesen
Bereit für den Start?
Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.
Kostenlose Testphase startenVerifiziert am