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

Codebeispiel

{
  "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:

Der Kontakt schreibt Ihnen. Die eingehende Nachricht enthält from.bsuid, und from.phone_number kann fehlen. Diese Nachricht öffnet das Kundenservice-Fenster, sodass Sie in den nächsten 24 Stunden frei antworten können.
Sie fragen nach der Nummer. Senden Sie eine Kontaktinfo-Anfrage – 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.
Der Kontakt tippt auf die Schaltfläche. Die freigegebene Nummer kommt als eingehende Kontaktkarte 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:

Codebeispiel

{
  "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 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 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 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 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.
In einem Webhook werden dieselben Adressen im Event-Payload mitgeliefert. Die Struktur finden Sie unter WhatsApp-Webhooks.
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: der Kanal, über den die geteilte Nummer ankommt
WhatsApp-Kontaktinfo-Anfragen: der Button, der danach fragt
WhatsApp-Nachrichten senden: die Anfrage-Struktur, das 202-Modell und sicheres erneutes Versuchen
Metas Referenz zu Business-scoped User IDs: der Rollout, Parent-BSUIDs und die übrigen Meta-Oberflächen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Übung ausprobieren und ein Implementierungs-Briefing erhalten