Conectați-văÎncepeți perioada de probă gratuită
Meta Tech Provider

Nume de utilizator WhatsApp și ID-uri de utilizator restrânse la afacere (BSUID): ce se schimbă în webhook-urile Cloud API

Numele de utilizator WhatsApp permit afișarea unui nume în locul numărului de telefon, așa că din începutul lunii aprilie 2026 webhook-urile mesajelor Cloud API includ și un ID de utilizator restrâns la afacere (BSUID), precum US.13491208655302741918, în user_id și from_user_id. Pentru un utilizator cu nume de utilizator care nu a avut niciun mesaj sau apel cu numărul în ultimele 30 de zile și nu se află în agenda de contacte, wa_id și from sunt omise.

easyCoexistence conectează un număr din aplicația WhatsApp Business la Cloud API prin Coexistence și direcționează webhook-urile messages și smb_message_echoes către endpoint-ul dumneavoastră, așa cum le trimite Meta, cu câmpurile BSUID incluse, în timp ce get_api_credentials oferă codului dumneavoastră ce îi trebuie pentru a răspunde cu recipient.

April 2026

Când au apărut BSUID-urile în webhook-urile Cloud API, înaintea lansării numelor de utilizator pentru utilizatorii WhatsApp.

July 2026

Când API-urile au început să accepte mesaje trimise către un BSUID, setat în recipient în loc de to.

30 days

Perioada de referință, pentru fiecare număr de telefon al afacerii, în care orice mesaj sau apel cu utilizatorul îi păstrează numărul în webhook-uri.

128

Majoritatea caracterelor alfanumerice care urmează după codul de țară din două litere și punctul unui BSUID.

131062

Eroare API Messages: Destinatarii cu ID de utilizator restrâns la afacere (BSUID) nu sunt acceptați pentru acest tip de mesaj.

user_changed_user_id

Tipul de mesaj de sistem pentru o schimbare de BSUID raportată fără numărul de telefon, cu BSUID-ul vechi în previous_user_id.

Ce sunt numele de utilizator WhatsApp și BSUID-urile?

Un nume de utilizator este un nume opțional și unic pe care un utilizator WhatsApp îl poate seta, afișat în aplicație în locul numărului de telefon; Meta lansează treptat numele de utilizator în 2026. BSUID-ul este identificatorul de backend adăugat de Meta pentru ca firmele să poată distinge în continuare utilizatorii: generat automat, unic pentru fiecare pereche formată din Business Portfolio și utilizator, și scris ca codul de țară ISO 3166 din două litere al utilizatorului, un punct și până la 128 de caractere alfanumerice. Meta cere partenerilor și firmelor cu integrare directă să îl accepte, deoarece nicio firmă nu controlează dacă utilizatorii adoptă numele de utilizator.

Ce câmpuri transportă noii identificatori?

Proprietăți noi lângă cele care conțineau numărul de telefon, în webhook-urile messages, status, system și user_preferences. Câmpurile părinte apar doar pentru Business Portfolio-urile pe care Meta le-a înscris în BSUID-uri părinte, care funcționează în toate Business Portfolio-urile înscrise:

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

Când lipsește numărul de telefon?

Când utilizatorul are un nume de utilizator și niciuna dintre cele trei condiții ale Meta nu este îndeplinită. Numărul de telefon rămâne în webhook-uri dacă numărul de telefon al afacerii a trimis un mesaj sau a apelat numărul utilizatorului în ultimele 30 de zile, a primit un mesaj sau un apel de la acesta în acea perioadă sau utilizatorul se află în agenda de contacte a Business Portfolio-ului. Perioada de 30 de zile se numără pentru fiecare număr de telefon al afacerii, astfel încât un al doilea număr din același Business Portfolio poate primi doar BSUID-ul aceluiași utilizator. Utilizatorii fără nume de utilizator continuă să sosească cu atât numărul de telefon, cât și BSUID-ul.

Cum arată acum un mesaj primit?

Ca înainte, cu BSUID-ul lângă numărul de telefon sau în locul lui. În exemplul Meta al unui utilizator cu nume de utilizator al cărui număr nu poate fi partajat, contacts conține profile.name, profile.username și user_id, iar mesajul conține from_user_id în locul vechiului câmp 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?" }
        }]
      }
    }]
  }]
}

Cum se schimbă webhook-urile de status?

Statusurile trimis, livrat și citit primesc un array contacts cu numele utilizatorului, user_id, wa_id atunci când numărul poate fi partajat și username la livrat și citit. În statusuri, recipient_user_id conține BSUID-ul, iar recipient_id este omis când ați trimis către un BSUID și numărul nu poate fi partajat. Un status de eșec nu are array contacts și omite recipient_user_id când mesajul a fost trimis către un număr de telefon, deci legați eșecurile de ID-ul mesajului.

Cum stocați și potriviți utilizatorii?

După BSUID mai întâi, iar numărul de telefon ca a doua cheie ori de câte ori sosește. Stocați întregul BSUID ca șir de caractere, cu codul de țară și punctul, deoarece Meta respinge cererile care modifică orice parte a lui, și stocați și BSUID-ul părinte dacă Business Portfolio-urile dumneavoastră sunt înscrise. Uniți înregistrările existente pe wa_id cât timp acesta mai sosește și păstrați BSUID-ul alături, deoarece un utilizator care adoptă ulterior un nume de utilizator poate reveni fără număr. FAQ-ul Meta cere aceleași uniri în CRM-uri și în instrumentele pe care le alimentează.

Ce se întâmplă când un utilizator își schimbă numărul de telefon?

BSUID-ul său este regenerat, iar schimbarea sosește pe câmpul messages sub formă de mesaj de sistem, deoarece Meta nu are câmp user_id_update la care să vă abonați. system.type este user_changed_number când noul număr poate fi partajat cu dumneavoastră sau user_changed_user_id când poate fi raportată doar schimbarea BSUID-ului; system.user_id conține noul BSUID, iar system.previous_user_id pe cel vechi, ceea ce permite transferul înregistrării. Tratați ambele tipuri.

Cum răspundeți unui utilizator cunoscut doar prin BSUID?

Trimiteți către /<BUSINESS_PHONE_NUMBER_ID>/messages cu recipient setat la BSUID și cu to omis; dacă ambele sunt prezente, to are prioritate și răspunsul merge la numărul de telefon. Intrarea contacts din răspuns conține atunci input și user_id, nu wa_id. Orice tip de mesaj funcționează, cu excepția șabloanelor de autentificare one-tap, zero-tap și copy code, care necesită număr de telefon, iar la BSUID pot ajunge doar numerele din același Business Portfolio. Eroarea 131062 înseamnă că tipul de mesaj nu acceptă destinatari 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." }
}

Cum cereți unui utilizator numărul de telefon?

Cu butonul REQUEST_CONTACT_INFO, adăugat la un șablon utility sau marketing ori trimis ca mesaj interactiv de tip request_contact_info. Un utilizator care apasă pe el își partajează numărul în conversație, iar un webhook contacts sosește cu origin setat la contact_request și numărul în phones[].wa_id; un contact partajat manual sosește cu origin other și un vCard. Meta a pus butonul la dispoziție la începutul lunii iulie 2026, iar eticheta lui nu poate fi personalizată.

Ce este agenda de contacte?

O bază de date găzduită de Meta pentru fiecare Business Portfolio, fără efort de integrare: odată ce numărul de telefon al afacerii trimite un mesaj, apelează sau primește un apel de la numărul de telefon al utilizatorului, numărul și BSUID-ul sunt înregistrate și folosite pentru a completa webhook-urile ulterioare cu numărul de telefon, indiferent dacă utilizatorul are sau nu nume de utilizator. Contează doar interacțiunile de după lansarea sa. Poate fi dezactivată în Meta Business Suite, la Setările afacerii, Informații despre afacere, ceea ce șterge datele stocate, iar GET sau DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book cu un bsuid verifică sau elimină o intrare.

Ce ar trebui să modifice o integrare Coexistence?

Felul în care tratează cele trei webhook-uri pe care le primește doar un număr Coexistence, care se schimbă și ele. În history, fiecare conversație primește un obiect context cu wa_id, user_id și username, iar mesajele sale primesc from_user_id. În smb_message_echoes se adaugă un array contacts, iar message_echoes[].to poate fi omis, în timp ce to_user_id conține BSUID-ul; editările și revocările făcute în aplicația WhatsApp Business sosesc în același mod. În smb_app_state_sync, phone_number al unui contact poate fi omis, iar user_id și username stau alături. Potriviți ecourile și conversațiile importate atât după user_id, cât și după număr.

Cum puteți testa înainte ca utilizatorii să adopte nume de utilizator?

Cu instrumentul de testare al Meta din App Dashboard: la Cazuri de utilizare, Conectați-vă cu clienții prin WhatsApp, Personalizare, Configurare, linkul Test de lângă webhook-ul messages trimite un exemplu către endpoint-ul dumneavoastră. Acesta acoperă mesajele primite și statusurile în patru scenarii:

  • Un utilizator fără nume de utilizator: câmpurile BSUID și numărul de telefon, fără username.
  • Un utilizator cu nume de utilizator al cărui număr nu este disponibil: username și BSUID, fără câmpuri pentru numărul de telefon.
  • Un utilizator cu nume de utilizator al cărui număr este disponibil: username, BSUID și numărul de telefon.
  • Un Business Portfolio înscris în BSUID-uri părinte: un BSUID părinte lângă BSUID-ul propriu al portofoliului.

Cum gestionează easyCoexistence BSUID-urile?

Le transmite așa cum le trimite Meta. Un număr de telefon direcționat către endpoint-ul dumneavoastră cu set_webhook_destination primește webhook-urile messages și smb_message_echoes direct de la Meta, cu user_id, from_user_id, to_user_id și username incluse, iar atunci când automatizările sau redirecționarea sunt activate, easyCoexistence transmite mai departe valoarea trimisă de Meta, neschimbată. Pentru a răspunde unui BSUID, codul dumneavoastră folosește get_api_credentials, care returnează ID-ul numărului de telefon, endpoint-ul de trimitere și, când este disponibil, token-ul propriu; instrumentele send_message și send_template primesc un număr de telefon în cifre internaționale.

Greșeli frecvente

  • Indexarea contactelor doar după wa_id. Un utilizator cu nume de utilizator care nu a avut niciun contact cu numărul de telefon în ultimele 30 de zile sosește cu doar user_id și from_user_id, iar un handler care cere wa_id pierde mesajul.
  • Tăierea prefixului de țară al unui BSUID. Meta cere valoarea întreagă, cu codul de țară și punctul, iar o cerere cu orice parte modificată eșuează.
  • Așteptarea unui câmp user_id_update. Meta nu are unul: schimbările de BSUID sosesc pe messages ca mesaje de sistem de tip user_changed_number sau user_changed_user_id.
  • Potrivirea ecourilor Coexistence doar după to. În smb_message_echoes câmpul to poate fi omis, așa că un răspuns scris în aplicație rămâne nevăzut dacă nu se potrivește și to_user_id.
Faceți acest lucru cu EasyCoexistence

Fiecare conexiune este monitorizată 24/7. De la US$ 9 până la US$ 0,75 pe conexiune pe lună, care scade pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.

Întrebări frecvente

Utilizatorii fără nume de utilizator primesc și ei un BSUID?

Da. Meta setează user_id în webhook-urile messages indiferent dacă utilizatorul are sau nu un nume de utilizator, astfel încât majoritatea utilizatorilor sosesc cu atât numărul de telefon, cât și BSUID-ul lor.

Poate un număr Coexistence să aibă un nume de utilizator de afacere?

Da. Din 29 iunie 2026, o firmă îl poate adopta sau schimba în Meta Business Suite, WhatsApp Manager, aplicația WhatsApp Business sau Username API; nu ascunde numărul firmei, iar business_username_updates raportează fiecare schimbare de status.

Funcționează un BSUID în toate Business Portfolio-urile?

Nu. Un BSUID aparține unui singur Business Portfolio și unui singur utilizator, iar un număr din alt Business Portfolio nu îi poate trimite mesaje. Afacerile gestionate pe care Meta le înscrie primesc BSUID-uri părinte, cu ENT după codul de țară, care funcționează în toate Business Portfolio-urile înscrise.

Cât costă easyCoexistence pentru un număr WhatsApp?

De la US$ 9 până la US$ 0,75 pe conexiune pe lună, în funcție de câte conexiuni aveți, iar primele 3 zile sunt gratuite. Taxele Meta pentru mesaje rămân în metoda de plată a contului dumneavoastră WhatsApp Business.

Continuați să citiți

Gata să începeți?

Configurați WhatsApp Coexistence în câteva minute, nu luni. Aplicația continuă să funcționeze pe telefon.

Începeți perioada de probă gratuită

Verificat la