Log masukMulakan percubaan percuma
Meta Tech Provider

Nama pengguna WhatsApp dan ID pengguna skop perniagaan (BSUID): apa yang berubah dalam webhook Cloud API

Nama pengguna WhatsApp membolehkan pengguna memaparkan nama dan bukannya nombor telefon mereka. Oleh itu, sejak awal April 2026, webhook mesej Cloud API turut membawa ID pengguna skop perniagaan (BSUID), contohnya US.13491208655302741918, dalam user_id dan from_user_id. Bagi pengguna yang mempunyai nama pengguna, yang tiada mesej atau panggilan dengan nombor itu dalam tempoh 30 hari dan tidak berada dalam buku kenalan, wa_id dan from ditinggalkan.

easyCoexistence menyambungkan nombor aplikasi WhatsApp Business ke Cloud API melalui Coexistence dan menghala webhook messages dan smb_message_echoes ke endpoint anda seperti yang Meta hantar, termasuk medan BSUID, manakala get_api_credentials memberi kod anda apa yang diperlukan untuk membalas dengan recipient.

April 2026

Bila BSUID mula muncul dalam webhook Cloud API, lebih awal daripada nama pengguna sampai kepada pengguna WhatsApp.

July 2026

Bila API mula menerima mesej yang dihantar kepada BSUID, ditetapkan dalam recipient dan bukannya to.

30 days

Tempoh semakan, bagi setiap nombor telefon perniagaan, dalam mana-mana mesej atau panggilan dengan pengguna mengekalkan nombor mereka dalam webhook.

128

Kebanyakan aksara alfanumerik selepas kod negara dua huruf BSUID dan titik.

131062

Ralat Messages API: Business-scoped User ID (BSUID) recipients are not supported for this message.

user_changed_user_id

Jenis mesej sistem untuk perubahan BSUID yang dilaporkan tanpa nombor telefon, dengan BSUID lama dalam previous_user_id.

Apakah nama pengguna WhatsApp dan BSUID?

Nama pengguna ialah nama unik pilihan yang boleh ditetapkan oleh pengguna WhatsApp, dipaparkan dalam aplikasi dan bukannya nombor telefon mereka; Meta sedang melancarkan nama pengguna secara berperingkat pada 2026. BSUID ialah pengecam bahagian belakang yang ditambah oleh Meta supaya perniagaan masih dapat membezakan pengguna: dijana secara automatik, unik bagi setiap pasangan portfolio perniagaan dan pengguna, dan ditulis sebagai kod negara ISO 3166 dua huruf, titik dan sehingga 128 aksara alfanumerik. Meta mewajibkan rakan kongsi dan perniagaan yang disepadukan secara langsung menyokongnya, kerana tiada perniagaan mengawal sama ada penggunanya menggunakan nama pengguna.

Medan manakah yang membawa pengecam baharu?

Sifat baharu di sebelah medan yang dahulunya memegang nombor telefon, merentasi webhook messages, status, system dan user_preferences. Medan induk hanya muncul bagi portfolio perniagaan yang Meta daftarkan dalam BSUID induk, yang berfungsi merentasi portfolio yang didaftarkan:

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

Bila nombor telefon ditinggalkan?

Apabila pengguna mempunyai nama pengguna dan tiada satu pun daripada tiga syarat Meta dipenuhi. Nombor kekal dalam webhook jika nombor telefon perniagaan menghantar mesej atau membuat panggilan kepada nombor pengguna dalam 30 hari lepas, menerima mesej atau panggilan daripadanya dalam tempoh itu, atau pengguna berada dalam buku kenalan portfolio. Tempoh 30 hari dikira bagi setiap nombor telefon perniagaan, jadi nombor kedua dalam portfolio yang sama mungkin hanya menerima BSUID bagi pengguna yang sama. Pengguna tanpa nama pengguna terus tiba dengan kedua-dua nombor telefon dan BSUID mereka.

Bagaimana rupa mesej masuk sekarang?

Seperti sebelum ini, dengan BSUID di sebelah nombor telefon atau menggantikannya. Dalam contoh Meta bagi pengguna yang mempunyai nama pengguna dan nombornya tidak boleh dikongsi, contacts membawa profile.name, profile.username dan user_id, dan mesej membawa from_user_id di tempat from dahulu:

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?" }
        }]
      }
    }]
  }]
}

Bagaimana webhook status berubah?

Status dihantar, diterima dan dibaca mendapat tatasusunan contacts dengan nama pengguna, user_id, wa_id apabila nombor boleh dikongsi, dan username pada status delivered dan read. Dalam status, recipient_user_id membawa BSUID, dan recipient_id ditinggalkan apabila anda menghantar kepada BSUID dan nombornya tidak boleh dikongsi. Status gagal tidak mempunyai tatasusunan contacts dan mengabaikan recipient_user_id apabila mesej dihantar kepada nombor telefon, jadi padankan kegagalan dengan id mesej.

Bagaimana menyimpan dan memadankan pengguna?

Mengikut BSUID dahulu, dengan nombor telefon sebagai kunci kedua apabila ia tiba. Simpan BSUID penuh sebagai rentetan, termasuk kod negara dan titik, kerana Meta menolak permintaan yang mengubah mana-mana bahagiannya, dan simpan juga BSUID induk jika portfolio anda didaftarkan. Padankan rekod sedia ada menggunakan wa_id selagi ia masih tiba, dan simpan BSUID bersebelahannya, kerana pengguna yang kemudian menggunakan nama pengguna mungkin kembali tanpa nombor. FAQ Meta meminta gabungan yang sama dalam CRM dan alat yang menerima data daripadanya.

Apa yang berlaku apabila pengguna menukar nombor telefon?

BSUID mereka dijana semula, dan perubahan tiba pada medan messages sebagai mesej sistem, kerana Meta tidak mempunyai medan user_id_update untuk dilanggani. system.type ialah user_changed_number apabila nombor baharu boleh dikongsi dengan anda, atau user_changed_user_id apabila hanya perubahan BSUID boleh dilaporkan; system.user_id memegang BSUID baharu dan system.previous_user_id yang lama, dan inilah cara rekod dibawa ke hadapan. Kendalikan kedua-dua jenis.

Bagaimana membalas pengguna yang hanya dikenali melalui BSUID?

Hantar ke /<BUSINESS_PHONE_NUMBER_ID>/messages dengan recipient ditetapkan kepada BSUID dan to ditinggalkan; jika kedua-duanya ada, to diutamakan dan balasan pergi ke nombor telefon. Respons entri contacts kemudian membawa input dan user_id dan bukannya wa_id. Mana-mana jenis mesej berfungsi kecuali templat pengesahan one-tap, zero-tap dan copy code, yang memerlukan nombor telefon, dan hanya nombor dalam portfolio perniagaan yang sama boleh sampai ke BSUID. Ralat 131062 bermaksud jenis mesej tidak menerima penerima 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." }
}

Bagaimana meminta nombor telefon pengguna?

Dengan butang REQUEST_CONTACT_INFO, ditambah pada templat utiliti atau pemasaran atau dihantar sebagai mesej interaktif jenis request_contact_info. Pengguna yang menekannya berkongsi nombor mereka dalam perbualan, dan webhook contacts tiba dengan origin ditetapkan kepada contact_request dan nombor dalam phones[].wa_id; kenalan yang dikongsi secara manual tiba dengan origin other dan vCard. Meta menyediakan butang ini pada awal Julai 2026, dan labelnya tidak boleh diubah suai.

Apakah buku kenalan?

Stor yang dihoskan Meta bagi setiap portfolio perniagaan, tanpa kerja integrasi: sebaik sahaja nombor telefon perniagaan menghantar mesej, membuat panggilan atau menerima daripada nombor telefon pengguna, nombor itu dan BSUID direkodkan dan digunakan untuk mengisi webhook kemudian dengan nombor telefon, sama ada pengguna ada nama pengguna atau tidak. Hanya interaksi selepas pelancarannya yang dikira. Ia boleh dimatikan dalam Meta Business Suite, Tetapan perniagaan, Maklumat perniagaan, yang memadam apa yang ada di dalamnya, dan GET atau DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book dengan bsuid menyemak atau mengeluarkan satu entri.

Apa yang perlu diubah oleh integrasi Coexistence?

Pengendalian tiga webhook yang hanya diterima oleh nombor Coexistence, yang turut berubah. Dalam history, setiap utas mendapat objek context dengan wa_id, user_id dan username, dan mesejnya mendapat from_user_id. Dalam smb_message_echoes, tatasusunan contacts ditambah, dan message_echoes[].to boleh ditinggalkan manakala to_user_id membawa BSUID; suntingan dan pembatalan yang dibuat dalam aplikasi WhatsApp Business tiba dengan cara yang sama. Dalam smb_app_state_sync, phone_number kenalan boleh ditinggalkan, dengan user_id dan username di sebelahnya. Padankan gema dan sembang yang diimport mengikut user_id serta nombor.

Bagaimana anda boleh menguji sebelum pengguna menggunakan nama pengguna?

Dengan alat ujian Meta dalam App Dashboard: di bawah Use cases, Connect with customers through WhatsApp, Customize, Configuration, pautan Test di sebelah webhook messages menghantar sampel ke endpoint anda. Ia meliputi mesej masuk dan status dalam empat senario:

  • Pengguna tanpa nama pengguna: medan BSUID dan nombor telefon, dan tiada nama pengguna.
  • Pengguna dengan nama pengguna yang nombornya tidak tersedia: nama pengguna dan BSUID, tanpa medan nombor telefon.
  • Pengguna dengan nama pengguna yang nombornya tersedia: nama pengguna, BSUID dan nombor telefon.
  • Portfolio yang didaftarkan dalam BSUID induk: BSUID induk di sebelah BSUID portfolio itu sendiri.

Bagaimana easyCoexistence mengendalikan BSUID?

Ia menghantarnya seperti yang Meta hantar. Nombor yang dihalakan ke endpoint anda dengan set_webhook_destination menerima webhook messages dan smb_message_echoes terus daripada Meta, termasuk user_id, from_user_id, to_user_id dan username, dan dengan automasi atau pemajuan dihidupkan, easyCoexistence memajukan nilai yang dihantar Meta tanpa diubah. Untuk membalas BSUID, kod anda menggunakan get_api_credentials, yang mengembalikan ID nombor telefon, endpoint hantar dan, jika ada, token anda sendiri; alat send_message dan send_template mengambil nombor telefon dalam digit antarabangsa.

Kesilapan biasa

  • Mengunci kenalan pada wa_id sahaja. Pengguna dengan nama pengguna yang tidak pernah berhubung dengan nombor itu dalam 30 hari tiba hanya dengan user_id dan from_user_id, dan pengendali yang memerlukan wa_id terlepas mesej itu.
  • Memotong awalan negara BSUID. Meta mahukan nilai penuh, termasuk kod negara dan titik, dan permintaan yang mengubah mana-mana bahagian akan gagal.
  • Menunggu medan user_id_update. Meta tidak mempunyai medan itu: perubahan BSUID tiba pada messages sebagai mesej sistem jenis user_changed_number atau user_changed_user_id.
  • Memadankan gema Coexistence pada to sahaja. Dalam smb_message_echoes medan to boleh ditinggalkan, jadi balasan yang ditaip dalam aplikasi tidak dilihat melainkan to_user_id turut dipadankan.
Menggunakan EasyCoexistence untuk ini

Setiap sambungan dipantau 24/7. US$ 9 hingga US$ 0.75 setiap sambungan sebulan, berkurang apabila anda menambah sambungan, dengan 3 hari pertama percuma.

Soalan lazim

Adakah pengguna tanpa nama pengguna turut mendapat BSUID?

Ya. Meta menetapkan user_id dalam webhook messages sama ada pengguna mempunyai nama pengguna atau tidak, jadi kebanyakan pengguna tiba dengan kedua-dua nombor telefon dan BSUID mereka.

Bolehkah nombor Coexistence mempunyai nama pengguna perniagaan?

Boleh. Sejak 29 Jun 2026 sebuah perniagaan boleh menerima pakai atau menukar satu dalam Meta Business Suite, WhatsApp Manager, aplikasi WhatsApp Business atau Username API; ia tidak menyembunyikan nombor perniagaan, dan business_username_updates melaporkan setiap perubahan status.

Adakah BSUID berfungsi merentasi portfolio perniagaan?

Tidak. BSUID tergolong dalam satu portfolio dan pengguna, dan nombor dalam portfolio lain tidak boleh menghantar mesej kepadanya. Perniagaan terurus yang didaftarkan Meta mendapat BSUID induk, dengan ENT selepas kod negara, yang berfungsi merentasi portfolio yang didaftarkan.

Berapakah kos easyCoexistence untuk nombor WhatsApp?

US$ 9 hingga US$ 0.75 setiap sambungan sebulan, bergantung pada bilangan sambungan anda, dan 3 hari pertama percuma. Caj mesej Meta kekal pada kaedah pembayaran Akaun WhatsApp Business anda.

Teruskan membaca

Sedia untuk bermula?

Sediakan WhatsApp Coexistence dalam beberapa minit, bukan berbulan-bulan. Aplikasi terus berfungsi pada telefon.

Mulakan Percubaan Percuma

Disahkan pada