Zaloguj sięRozpocznij bezpłatny okres próbny
Meta Tech Provider

Nazwy użytkowników WhatsApp i identyfikatory BSUID: co się zmienia w webhookach Cloud API

Nazwy użytkowników WhatsApp pozwalają pokazać nazwę zamiast numeru telefonu, dlatego od początku kwietnia 2026 roku webhooki wiadomości Cloud API zawierają także identyfikator użytkownika w zakresie firmy (BSUID), na przykład US.13491208655302741918, w polach user_id i from_user_id. Dla użytkownika z nazwą użytkownika, który przez 30 dni nie wysłał ani nie odebrał wiadomości lub połączenia z tym numerem i nie znajduje się w książce kontaktów, pola wa_id i from są pomijane.

easyCoexistence łączy numer aplikacji WhatsApp Business z Cloud API przez Coexistence i kieruje jego webhooki messages oraz smb_message_echoes na Twój endpoint tak, jak wysyła je Meta, wraz z polami BSUID, a get_api_credentials daje Twojemu kodowi to, czego potrzebuje, aby odpowiedzieć z recipient.

April 2026

Kiedy BSUID zaczęły pojawiać się w webhookach Cloud API, wcześniej niż nazwy użytkowników dotarły do użytkowników WhatsApp.

July 2026

Kiedy API zaczęły przyjmować wiadomości wysyłane na BSUID, podawany w polu recipient zamiast to.

30 days

Okres wsteczny, liczony osobno dla każdego numeru telefonu firmy, w którym każda wiadomość lub połączenie z użytkownikiem zachowuje jego numer w webhookach.

128

Większość znaków alfanumerycznych po dwuliterowym kodzie kraju i kropce w BSUID.

131062

Błąd Messages API: „Business-scoped User ID (BSUID) recipients are not supported for this message.”

user_changed_user_id

Typ wiadomości systemowej dla zmiany BSUID zgłaszanej bez numeru telefonu, ze starym BSUID w polu previous_user_id.

Czym są nazwy użytkowników WhatsApp i BSUID?

Nazwa użytkownika to opcjonalna, unikalna nazwa, którą użytkownik WhatsApp może ustawić; aplikacja pokazuje ją zamiast numeru telefonu, a Meta wprowadza nazwy użytkowników stopniowo w 2026 roku. BSUID to identyfikator zaplecza, który Meta dodała, aby firmy mogły nadal rozróżniać użytkowników: jest generowany automatycznie, jest unikalny dla każdej pary Business Portfolio i użytkownika oraz zapisywany jako dwuliterowy kod kraju ISO 3166, kropka i do 128 znaków alfanumerycznych. Meta wymaga, aby partnerzy i firmy zintegrowane bezpośrednio go obsługiwały, ponieważ żadna firma nie kontroluje tego, czy jej użytkownicy przyjmują nazwy użytkowników.

Które pola przenoszą nowe identyfikatory?

Nowe właściwości występują obok tych, które dotąd zawierały numer telefonu, w webhookach messages, status, system i user_preferences. Pola nadrzędne pojawiają się tylko w Business Portfolio, które Meta zapisała do nadrzędnych BSUID; działają one we wszystkich zapisanych portfolio:

contacts[].user_idThe user's BSUID, in incoming messages and in sent, delivered and read statuses
messages[].from_user_idThe sender's BSUID, beside from
contacts[].profile.usernameThe username, when the user has one; never on sent statuses
statuses[].recipient_user_idThe recipient's BSUID, unless a send to a phone number failed
parent_user_idA parent BSUID shared by enrolled portfolios, such as US.ENT.11815799212886844830
wa_id, from, recipient_idNow left out when the phone number cannot be shared

Kiedy numer telefonu jest pomijany?

Gdy użytkownik ma nazwę użytkownika i żaden z trzech warunków Meta nie jest spełniony. Numer pozostaje w webhookach, jeśli numer telefonu firmy wysłał wiadomość lub zadzwonił do numeru tego użytkownika w ciągu ostatnich 30 dni, otrzymał od niego wiadomość lub połączenie w tym czasie albo użytkownik znajduje się w książce kontaktów portfolio. Okres 30 dni liczony jest osobno dla każdego numeru telefonu firmy, więc drugi numer w tym samym portfolio może otrzymać wyłącznie BSUID tego użytkownika. Użytkownicy bez nazwy użytkownika nadal przychodzą z numerem telefonu i BSUID jednocześnie.

Jak wygląda teraz przychodząca wiadomość?

Jak wcześniej, z BSUID obok numeru telefonu lub zamiast niego. W przykładzie Meta dla użytkownika z nazwą użytkownika, którego numeru nie można udostępnić, contacts zawiera profile.name, profile.username i user_id, a wiadomość zawiera from_user_id w miejscu dawnego from:

messages webhook: a text from a user known only by BSUID
{
  "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?" }
        }]
      }
    }]
  }]
}

Jak zmieniają się webhooki statusów?

Statusy wysłania, dostarczenia i odczytu zyskują tablicę contacts z nazwą profilu użytkownika, user_id, wa_id, gdy numer można udostępnić, oraz username przy dostarczeniu i odczycie. W statusach recipient_user_id zawiera BSUID, a recipient_id jest pomijany, gdy wysłano na BSUID, a numeru nie można udostępnić. Status błędu nie ma tablicy contacts i pomija recipient_user_id, gdy wiadomość poszła na numer telefonu, więc błędy powiąż z identyfikatorem wiadomości.

Jak przechowywać i dopasowywać użytkowników?

Najpierw według BSUID, a numer telefonu jako drugi klucz, gdy tylko się pojawi. Przechowuj cały BSUID jako ciąg znaków, z kodem kraju i kropką, ponieważ Meta odrzuca żądania zmieniające jakąkolwiek jego część, i zapisz też BSUID nadrzędny, jeśli Twoje portfolio jest zapisane. Istniejące rekordy łącz po wa_id, dopóki to pole przychodzi, i zachowuj obok nich BSUID, bo użytkownik, który później przyjmie nazwę użytkownika, może wrócić bez numeru. FAQ Meta prosi o te same połączenia w CRM-ach i narzędziach, które je zasilają.

Co się dzieje, gdy użytkownik zmienia numer telefonu?

Jego BSUID zostaje wygenerowany na nowo, a zmiana przychodzi w polu messages jako wiadomość systemowa, ponieważ Meta nie ma pola user_id_update do subskrybowania. system.type ma wartość user_changed_number, gdy nowy numer można Ci udostępnić, albo user_changed_user_id, gdy można zgłosić tylko zmianę BSUID; system.user_id zawiera nowy BSUID, a system.previous_user_id stary, dzięki czemu rekord się przenosi. Obsłuż oba typy.

Jak odpowiedzieć użytkownikowi znanemu tylko po BSUID?

Wyślij na /<BUSINESS_PHONE_NUMBER_ID>/messages z recipient ustawionym na BSUID i bez to; gdy obydwa są obecne, wygrywa to, a odpowiedź idzie na numer telefonu. Wpis contacts w odpowiedzi zawiera wtedy input i user_id zamiast wa_id. Każdy typ wiadomości działa, z wyjątkiem szablonów uwierzytelniania jednym dotknięciem, zero dotknięć i z kopiowaniem kodu, które wymagają numeru telefonu, a na BSUID mogą odpowiadać tylko numery z tego samego Business Portfolio. Błąd 131062 oznacza, że dany typ wiadomości nie przyjmuje odbiorców BSUID.

POST /<BUSINESS_PHONE_NUMBER_ID>/messages, sent to a BSUID
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "US.13491208655302741918",
  "type": "text",
  "text": { "body": "Yes, it also comes in blue." }
}

Jak poprosić użytkownika o numer telefonu?

Przyciskiem REQUEST_CONTACT_INFO, dodanym do szablonu usługowego lub marketingowego albo wysłanym jako wiadomość interaktywna typu request_contact_info. Użytkownik, który go dotknie, udostępnia numer w wątku, a w webhooku contacts pojawia się origin o wartości contact_request i numer w phones[].wa_id; kontakt udostępniony ręcznie ma origin równy other i vCard. Meta udostępniła przycisk na początku lipca 2026 roku, a jego etykiety nie można zmienić.

Czym jest książka kontaktów?

Magazyn, który Meta prowadzi dla każdego Business Portfolio bez pracy integracyjnej: gdy numer telefonu firmy napisze, zadzwoni lub odbierze połączenie od numeru użytkownika, ten numer i BSUID są zapisywane i służą do uzupełniania późniejszych webhooków numerem telefonu, z nazwą użytkownika lub bez. Liczą się wyłącznie interakcje po jej uruchomieniu. Można ją wyłączyć w Meta Business Suite, w sekcji Ustawienia firmy, Informacje o firmie, co usuwa zgromadzone dane; GET lub DELETE na /<BUSINESS_PHONE_NUMBER_ID>/contact_book z parametrem bsuid sprawdza lub usuwa pojedynczy wpis.

Czego powinna zmienić integracja Coexistence?

Jej obsługi trzech webhooków, które dostaje wyłącznie numer Coexistence, a które też się zmieniają. W history każdy wątek zyskuje obiekt context z wa_id, user_id i username, a jego wiadomości zyskują from_user_id. W smb_message_echoes dochodzi tablica contacts, a message_echoes[].to może być pominięte, podczas gdy to_user_id zawiera BSUID; edycje i cofnięcia wykonane w aplikacji WhatsApp Business przychodzą tak samo. W smb_app_state_sync pole phone_number kontaktu może być pominięte, obok user_id i username. Dopasowuj echa i zaimportowane czaty po user_id, a nie tylko po numerze.

Jak przetestować przed przyjęciem nazw użytkowników przez użytkowników?

Narzędziem testowym Meta w App Dashboard: w sekcji Use cases, Connect with customers through WhatsApp, Customize, Configuration przycisk Test obok webhooka messages wysyła próbkę na Twój endpoint. Obejmuje ona przychodzące wiadomości i statusy w czterech scenariuszach:

  • Użytkownik bez nazwy użytkownika: pola BSUID i numeru telefonu, bez pola nazwy użytkownika.
  • Użytkownik z nazwą użytkownika, którego numer jest niedostępny: nazwa użytkownika i BSUID, bez pól numeru telefonu.
  • Użytkownik z nazwą użytkownika, którego numer jest dostępny: nazwa użytkownika, BSUID i numer telefonu.
  • Business Portfolio zapisane do nadrzędnych BSUID: nadrzędny BSUID obok własnego BSUID portfolio.

Jak easyCoexistence obsługuje BSUID?

Przekazuje je dalej tak, jak wysyła je Meta. Numer skierowany na Twój endpoint za pomocą set_webhook_destination dostaje webhooki messages i smb_message_echoes bezpośrednio od Meta, z user_id, from_user_id, to_user_id i username, a przy włączonych automatyzacjach lub przekazywaniu easyCoexistence przesyła dalej wartość wysłaną przez Meta bez zmian. Aby odpowiedzieć na BSUID, Twój kod używa get_api_credentials, które zwraca identyfikator numeru telefonu, jego endpoint wysyłania i, jeśli jest dostępny, Twój własny token; narzędzia send_message i send_template przyjmują numer telefonu w cyfrach międzynarodowych.

Typowe błędy

  • Kluczowanie kontaktów wyłącznie po wa_id. Użytkownik z nazwą użytkownika, który przez 30 dni nie miał kontaktu z numerem, przychodzi tylko z user_id i from_user_id, a handler wymagający wa_id przegapi wiadomość.
  • Obcinanie kodu kraju z BSUID. Meta chce całej wartości, z kodem kraju i kropką, a żądanie z jakąkolwiek zmienioną częścią kończy się błędem.
  • Oczekiwanie na pole user_id_update. Meta go nie ma: zmiany BSUID przychodzą w messages jako wiadomości systemowe typu user_changed_number lub user_changed_user_id.
  • Dopasowywanie ech Coexistence wyłącznie po to. W smb_message_echoes pole to może być pominięte, więc odpowiedź wpisana w aplikacji pozostanie niezauważona, dopóki nie dopasujesz też to_user_id.
Z EasyCoexistence zrobisz to

Każde połączenie jest monitorowane całą dobę. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń; pierwsze 3 dni są bezpłatne.

Najczęściej zadawane pytania

Czy użytkownicy bez nazwy użytkownika też dostają BSUID?

Tak. Meta ustawia user_id w webhookach messages niezależnie od tego, czy użytkownik ma nazwę użytkownika, więc większość użytkowników przychodzi z numerem telefonu i BSUID jednocześnie.

Czy numer Coexistence może mieć nazwę użytkownika firmy?

Tak. Od 29 czerwca 2026 firma może ją przyjąć lub zmienić w Meta Business Suite, WhatsApp Manager, aplikacji WhatsApp Business lub przez Username API; nie ukrywa to numeru firmy, a business_username_updates raportuje każdą zmianę statusu.

Czy BSUID działa w różnych Business Portfolio?

Nie. BSUID należy do jednego Business Portfolio i użytkownika, a numer z innego portfolio nie może do niego napisać. Zarządzane firmy zapisane przez Meta dostają nadrzędne BSUID z ENT po kodzie kraju, które działają we wszystkich zapisanych portfolio.

Ile kosztuje easyCoexistence dla numeru WhatsApp?

Od US$ 9 do US$ 0.75 za połączenie miesięcznie, zależnie od liczby połączeń, a pierwsze 3 dni są bezpłatne. Opłaty Meta za wiadomości pozostają w metodzie płatności Twojego konta WhatsApp Business.

Czytaj dalej

Gotowy, aby zacząć?

Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.

Rozpocznij bezpłatny okres próbny

Zweryfikowano w