Dokumentacja
Sign inGet started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

Identyfikatory użytkowników w zakresie firmy

Identyfikator użytkownika w zakresie firmy (BSUID) to identyfikator Meta dla użytkownika WhatsApp, przypisany do jednego portfolio biznesowego. Pojawia się na wiadomościach przychodzących niezależnie od tego, czy kontakt używa nazwy użytkownika WhatsApp, i pozwala zaadresować kontakt, którego numeru telefonu nie masz.
Bird udostępnia go jako bsuid w polach from i to wiadomości, przyjmuje go jako to wysyłki i filtruje po nim listę wiadomości. Dokumentacja Meta business-scoped user IDs jest źródłem informacji o samym wdrożeniu i o tym, jak inne interfejsy Meta obsługują ten identyfikator.

Dlaczego kontakt dociera bez numeru telefonu

WhatsApp wdraża nazwy użytkowników. Użytkownik, który ją przyjmie, wyświetla w aplikacji swoją nazwę zamiast numeru telefonu, a Meta wstrzymuje numer w danych, które otrzymuje firma. BSUID to tożsamość, która jest zawsze obecna, dlatego wiadomość przychodząca może zawierać BSUID i nie zawierać phone_number wcale.
Meta nadal dołącza numer telefonu, jeśli masz już relację z kontaktem: gdy ten konkretny numer biznesowy wysyłał do niego wiadomości lub dzwonił albo odebrał od niego wiadomość lub połączenie w ciągu ostatnich 30 dni, bądź gdy kontakt znajduje się w Twojej książce kontaktów Meta. Warunek 30-dniowy jest oceniany osobno dla każdego numeru biznesowego, więc kontakt, który napisał na jeden z Twoich numerów, może nadal dotrzeć bez numeru telefonu na innym.
Wiadomość od użytkownika WhatsApp zawiera też publikowany przez niego profil, w polach username i display_name obiektu from. Oba są nieobecne, gdy kontakt nie przyjął nazwy użytkownika lub wiadomość nie zawiera profilu, i żadne z nich nie może służyć do zaadresowania wiadomości.

Jak wygląda BSUID

Przykład kodu
{
  "from": {
    "bsuid": "US.13491208655302741918",
    "username": "alexr",
    "display_name": "Alex Rivera"
  }
}
Kod kraju ISO 3166 alpha-2, kropka, a po niej do 128 znaków alfanumerycznych. Nadrzędny BSUID, na który zarządzana firma może zostać zapisana, aby jeden identyfikator działał w zestawie portfolio, wstawia ENT po kodzie kraju: US.ENT.11815799212886844830. Bird akceptuje obie formy jako adresata.
Trzy właściwości decydują o tym, jak przechowujesz i używasz BSUID:
  • Przekazuj całą wartość bez zmian. Meta odrzuca zmodyfikowany BSUID, więc żadna jego część nie jest opcjonalna: kod kraju, kropka i każdy znak identyfikatora są przesyłane razem. Bird waliduje format przed przyjęciem wysyłki, a kod kraju musi być zapisany wielkimi literami i być prawdziwym kodem ISO 3166 alpha-2; prefiks zapisany małymi literami lub nieznany jest odrzucany, nie korygowany. Limit 128 znaków dotyczy identyfikatora po kodzie kraju, a w przypadku nadrzędnego BSUID po segmencie ENT..
  • Jest przypisany do portfolio biznesowego. Każdy numer biznesowy w tym samym portfolio może wysłać wiadomość na ten BSUID; numer w innym portfolio nie może, a wysyłka kończy się błędem.
  • Nie jest trwały. Meta dokumentuje, że BSUID kontaktu jest generowany na nowo, gdy zmieni on numer telefonu, więc identyfikuje partnera rozmowy, a nie służy jako trwały klucz klienta w Twoim systemie.

Jak zwykle przebiega rozmowa

Kontakt, z którym wcześniej nie rozmawiałeś, dociera do Ciebie przez BSUID, a wymiana prowadząca do uzyskania numeru przebiega w trzech krokach:
  1. Kontakt wysyła do Ciebie wiadomość. Wiadomość przychodząca zawiera from.bsuid, a from.phone_number może być nieobecny. Ta wiadomość otwiera okno obsługi klienta, więc przez następne 24 godziny możesz odpowiadać dowolną treścią.
  2. Poproś o numer. Wyślij prośbę o dane kontaktowe, pojedynczy przycisk, który pozwala kontaktowi udostępnić numer telefonu. Tę samą prośbę można wysłać w szablonie za pomocą przycisku request_contact_info, który dociera do kontaktu, którego okno już się zamknęło.
  3. Kontakt naciska przycisk. Udostępniony numer przychodzi jako przychodząca wizytówka kontaktu z origin ustawionym na contact_request i numerem w phone_numbers. Udostępniona wizytówka kontaktu może opisywać inną osobę lub numer. Przechowuj te dane oddzielnie od tożsamości WhatsApp nadawcy; w kolejnych wiadomościach korzystaj z tożsamości faktycznie dostarczonych, zamiast nadpisywać rekord klienta samą wizytówką.
Kontakt może odmówić. Zamknięcie arkusza udostępniania nie generuje żadnej wiadomości ani webhooka, więc przepływ wymagający numeru musi sam wygasić oczekiwanie zamiast czekać na odmowę, i musi dalej działać dla kontaktu, który nigdy numeru nie udostępni.

Wysyłanie na BSUID

to przyjmuje BSUID wszędzie tam, gdzie przyjmuje numer telefonu:
Przykład kodu
{
  "to": "US.13491208655302741918",
  "from": "+13124495648",
  "text": { "body": "Your order shipped." }
}
Cztery rzeczy różnią się od wysyłki zaadresowanej numerem telefonu:
  • from musi znajdować się w portfolio, do którego przypisany jest BSUID. To ten sam wymóg portfolio, który stosuje Meta, a niezgodność powoduje błąd na etapie WhatsApp, nie na etapie przyjęcia.
  • Szablony z jednorazowym kodem weryfikacyjnym wymagają numeru telefonu. Szablon zarządzany przez Bird w kategorii authentication lub zawierający przycisk jednorazowego kodu weryfikacyjnego jest odrzucany na etapie przyjęcia z błędem 422 E15014 WhatsAppRecipientNotSupportedForTemplate. Szablon utworzony w Twoim obszarze roboczym nie jest sprawdzany na etapie przyjęcia: Meta wymaga numeru telefonu dla szablonów uwierzytelniania one-tap, zero-tap i copy-code, więc taka wysyłka jest przyjmowana, a potem kończy się błędem.
  • Wartość, która nie jest ani numerem telefonu, ani poprawnie sformowanym BSUID, jest odrzucana na etapie przyjęcia z błędem 422 E15001 WhatsAppInvalidRecipient.
  • Cena zależy od prefiksu kraju w BSUID. Numer telefonu dostarcza kraj, według którego wyceniana jest wiadomość, a w przypadku wysyłki na BSUID dostarcza go dwuliterowy prefiks.
Wszystko inne w wysyłce pozostaje bez zmian: okno obsługi klienta nadal ogranicza treść swobodną, a 202 nadal oznacza przyjęcie, nie dostarczenie.
Adresuj kontakt na tożsamości, z której do Ciebie napisał. Bird rejestruje otwarte okno pod każdą tożsamością, którą niosła wiadomość przychodząca, a wysyłka odnajduje okno pod tożsamością, na którą jest zaadresowana. Kontakt, który dotarł do Ciebie wyłącznie przez BSUID, nie pozostawia okna przypisanego do numeru telefonu, więc swobodna wysyłka na numer, który masz z innego źródła, może zostać odrzucona z błędem 422 E15044 WhatsAppServiceWindowClosed, mimo że Meta nadal uważa rozmowę za otwartą. Odpowiedź na from wiadomości kontaktu zapobiega tej niezgodności.

Odczytywanie i filtrowanie po BSUID

Każdy odczyt zawiera tożsamości obecne w wiadomości:
  • W wiadomości from i to zawierają phone_number, bsuid lub oba. Wiadomość przychodząca wskazuje kontakt w from; wychodząca wskazuje go w to.
  • W webhooku te same adresy znajdują się w danych zdarzenia. Opis struktury znajdziesz w zdarzeniach WhatsApp.
  • Na liście wiadomości to i from przyjmują zarówno BSUID, jak i numer telefonu, i każdy dopasowuje jedną stronę wiadomości. Filtr bsuid dopasowuje kontakt w obu kierunkach. Starszy filtr phone_number jest przestarzały: to i from go zastępują i dopasowują oba rodzaje tożsamości.
Przechowuj obie tożsamości przy własnym rekordzie kontaktu i powiąż rekord z własnym identyfikatorem, a nie z żadnym identyfikatorem Meta. Kontakt może dotrzeć wyłącznie z BSUID, uzyskać numer telefonu po jego udostępnieniu i otrzymać nowy BSUID po zmianie numeru.

Następne kroki

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy