MasukMulai uji coba gratis
Meta Tech Provider

Username WhatsApp dan ID pengguna terbatas bisnis (BSUID): apa yang berubah pada webhook Cloud API

Username WhatsApp memungkinkan pengguna menampilkan nama alih-alih nomor telepon mereka, sehingga sejak awal April 2026 webhook pesan Cloud API juga membawa ID pengguna terbatas bisnis (BSUID), seperti US.13491208655302741918, di user_id dan from_user_id. Untuk pengguna ber-username yang selama 30 hari tidak bertukar pesan atau panggilan dengan nomor tersebut dan tidak ada di buku kontak, wa_id dan from tidak disertakan.

easyCoexistence menghubungkan nomor aplikasi WhatsApp Business ke Cloud API melalui Coexistence dan merutekan webhook messages dan smb_message_echoes-nya ke endpoint Anda seperti yang dikirim Meta, termasuk field BSUID, sementara get_api_credentials memberi kode Anda apa yang dibutuhkan untuk membalas dengan recipient.

April 2026

Kapan BSUID mulai muncul di webhook Cloud API, sebelum username tersedia bagi pengguna WhatsApp.

July 2026

Kapan API mulai menerima pesan yang dikirim ke BSUID, diatur di recipient alih-alih to.

30 days

Periode lookback per nomor telepon bisnis: selama periode ini, pesan atau panggilan apa pun dengan pengguna membuat nomor mereka tetap ada di webhook.

128

Jumlah maksimum karakter alfanumerik setelah kode negara dua huruf dan titik pada BSUID.

131062

Kesalahan Messages API: penerima Business-scoped User ID (BSUID) tidak didukung untuk pesan ini.

user_changed_user_id

Tipe pesan sistem untuk perubahan BSUID yang dilaporkan tanpa nomor telepon, dengan BSUID lama di previous_user_id.

Apa itu username dan BSUID WhatsApp?

Username adalah nama unik opsional yang dapat diatur pengguna WhatsApp, ditampilkan di aplikasi alih-alih nomor telepon mereka; Meta meluncurkan username secara bertahap sepanjang 2026. BSUID adalah pengidentifikasi backend yang ditambahkan Meta agar bisnis tetap dapat membedakan pengguna: dibuat otomatis, unik untuk setiap pasangan Business Portfolio dan pengguna, dan ditulis sebagai kode negara dua huruf ISO 3166 pengguna, titik, serta hingga 128 karakter alfanumerik. Meta mewajibkan mitra dan bisnis yang terintegrasi langsung untuk mendukungnya, karena tidak ada bisnis yang dapat mengendalikan apakah penggunanya mengadopsi username.

Field mana yang membawa pengenal baru?

Properti baru di samping yang sebelumnya menampung nomor telepon, pada webhook messages, status, system, dan user_preferences. Field induk (parent) hanya muncul untuk Business Portfolio yang telah didaftarkan Meta ke parent BSUID, yang berlaku di seluruh portofolio yang terdaftar:

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

Kapan nomor telepon tidak disertakan?

Ketika pengguna memiliki username dan tidak satu pun dari tiga kondisi Meta terpenuhi. Nomor tetap ada di webhook jika nomor telepon bisnis mengirim pesan atau menelepon nomor pengguna tersebut dalam 30 hari terakhir, menerima pesan atau panggilan darinya dalam kurun waktu itu, atau pengguna ada di buku kontak portofolio. Periode lookback 30 hari dihitung per nomor telepon bisnis, sehingga nomor kedua dalam portofolio yang sama mungkin hanya menerima BSUID untuk pengguna yang sama. Pengguna tanpa username tetap masuk dengan nomor telepon dan BSUID sekaligus.

Seperti apa pesan masuk sekarang?

Seperti sebelumnya, dengan BSUID di samping nomor telepon atau menggantikannya. Dalam contoh Meta untuk pengguna yang memiliki username dan nomornya tidak dapat dibagikan, contacts memuat profile.name, profile.username, dan user_id, dan pesan memuat from_user_id di tempat from dulu berada:

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 sent, delivered, dan read mendapatkan array contacts dengan nama pengguna, user_id, wa_id jika nomor dapat dibagikan, dan username pada status delivered dan read. Pada statuses, recipient_user_id memuat BSUID, dan recipient_id tidak disertakan ketika Anda mengirim ke BSUID dan nomornya tidak dapat dibagikan. Status gagal tidak memiliki array contacts dan tidak menyertakan recipient_user_id ketika pesan dikirim ke nomor telepon, jadi kaitkan kegagalan dengan ID pesan.

Bagaimana menyimpan dan mencocokkan pengguna?

Berdasarkan BSUID terlebih dahulu, dengan nomor telepon sebagai kunci kedua setiap kali tersedia. Simpan seluruh BSUID sebagai string, termasuk kode negara dan titik, karena Meta menolak permintaan yang mengubah bagian mana pun darinya, dan simpan juga parent BSUID jika portofolio Anda terdaftar. Gabungkan record yang sudah ada berdasarkan wa_id selama masih datang, dan simpan BSUID di sampingnya, karena pengguna yang mengadopsi username belakangan mungkin kembali tanpa nomor. FAQ Meta meminta penggabungan yang sama di CRM dan di alat yang menerima datanya.

Apa yang terjadi saat pengguna mengganti nomor telepon?

BSUID mereka dibuat ulang, dan perubahan itu tiba di field messages sebagai pesan sistem, karena Meta tidak memiliki field user_id_update yang dapat Anda langgani. system.type adalah user_changed_number ketika nomor baru dapat dibagikan kepada Anda, atau user_changed_user_id ketika hanya perubahan BSUID yang dapat dilaporkan; system.user_id memuat BSUID baru dan system.previous_user_id BSUID lama, sehingga record dapat dipindahkan ke BSUID baru. Tangani kedua tipe.

Bagaimana membalas pengguna yang hanya dikenal lewat BSUID?

Kirim ke /<BUSINESS_PHONE_NUMBER_ID>/messages dengan recipient diisi BSUID dan to dikosongkan; jika keduanya ada, to yang dipakai dan balasan dikirim ke nomor telepon. Entri contacts pada respons kemudian memuat input dan user_id, bukan wa_id. Tipe pesan apa pun dapat digunakan kecuali template autentikasi one-tap, zero-tap, dan copy code, yang memerlukan nomor telepon, dan hanya nomor dalam Business Portfolio yang sama yang dapat menjangkau BSUID. Kesalahan 131062 berarti tipe pesan 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 nomor telepon pengguna?

Dengan tombol REQUEST_CONTACT_INFO, ditambahkan ke template utility atau marketing, atau dikirim sebagai pesan interaktif bertipe request_contact_info. Pengguna yang mengetuknya membagikan nomor mereka dalam percakapan, dan webhook contacts tiba dengan origin bernilai contact_request serta nomor di phones[].wa_id; kontak yang dibagikan secara manual tiba dengan origin other dan vCard. Meta menyediakan tombol ini sejak awal Juli 2026, dan labelnya tidak dapat disesuaikan.

Apa itu buku kontak?

Penyimpanan yang di-host Meta untuk setiap Business Portfolio, tanpa pekerjaan integrasi: setelah nomor telepon bisnis mengirim pesan, menelepon, atau menerima pesan atau panggilan dari nomor telepon pengguna, nomor itu dan BSUID dicatat dan digunakan untuk mengisi webhook berikutnya dengan nomor telepon, baik pengguna memiliki username maupun tidak. Hanya interaksi setelah peluncurannya yang dihitung. Fitur ini dapat dimatikan di Meta Business Suite, Business settings, Business info, yang akan menghapus data yang disimpannya, dan GET atau DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book dengan bsuid memeriksa atau menghapus satu entri.

Apa yang harus diubah pada integrasi Coexistence?

Penanganan tiga webhook yang hanya diterima nomor Coexistence, yang juga ikut berubah. Pada history, setiap percakapan mendapatkan objek context dengan wa_id, user_id, dan username, dan pesan-pesannya mendapatkan from_user_id. Pada smb_message_echoes, array contacts ditambahkan, dan message_echoes[].to dapat dihilangkan sementara to_user_id memuat BSUID; edit dan revoke yang dibuat di aplikasi WhatsApp Business tiba dengan cara yang sama. Pada smb_app_state_sync, phone_number kontak dapat dihilangkan, dengan user_id dan username di sampingnya. Cocokkan echo dan chat yang diimpor berdasarkan user_id juga, selain nomor.

Bagaimana menguji sebelum pengguna mengadopsi username?

Dengan alat uji Meta di App Dashboard: di bawah Use cases, Connect with customers through WhatsApp, Customize, Configuration, tautan Test di samping webhook messages mengirim contoh ke endpoint Anda. Alat ini mencakup pesan masuk dan status dalam empat skenario:

  • Pengguna tanpa username: field BSUID dan nomor telepon, tanpa username.
  • Pengguna dengan username yang nomornya tidak tersedia: username dan BSUID, tanpa field nomor telepon.
  • Pengguna dengan username yang nomornya tersedia: username, BSUID, dan nomor telepon.
  • Portofolio yang terdaftar di parent BSUID: parent BSUID di samping BSUID milik portofolio.

Bagaimana easyCoexistence menangani BSUID?

Ia meneruskannya persis seperti yang dikirim Meta. Nomor yang diarahkan ke endpoint Anda dengan set_webhook_destination menerima webhook messages dan smb_message_echoes langsung dari Meta, termasuk user_id, from_user_id, to_user_id, dan username, dan dengan automations atau forwarding aktif, easyCoexistence meneruskan nilai yang dikirim Meta tanpa diubah. Untuk membalas BSUID, kode Anda menggunakan get_api_credentials, yang mengembalikan phone number ID nomor tersebut, endpoint kirimnya, dan, jika tersedia, token Anda sendiri; tool send_message dan send_template menerima nomor telepon dalam digit internasional.

Kesalahan umum

  • Menjadikan wa_id satu-satunya kunci kontak. Pengguna dengan username yang tidak berinteraksi dengan nomor itu selama 30 hari hanya datang dengan user_id dan from_user_id, dan handler yang mewajibkan wa_id akan melewatkan pesan tersebut.
  • Memangkas awalan kode negara BSUID. Meta menginginkan seluruh nilai, termasuk kode negara dan titik, dan permintaan dengan bagian apa pun yang diubah akan gagal.
  • Menunggu field user_id_update. Meta tidak memilikinya: perubahan BSUID tiba di messages sebagai pesan sistem bertipe user_changed_number atau user_changed_user_id.
  • Mencocokkan echo Coexistence hanya dengan to. Pada smb_message_echoes field to dapat dihilangkan, sehingga balasan yang diketik di aplikasi tidak terlihat kecuali to_user_id juga dicocokkan.
Melakukan ini dengan EasyCoexistence

Setiap koneksi dipantau 24/7. US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.

Pertanyaan yang sering diajukan

Apakah pengguna tanpa username juga mendapatkan BSUID?

Ya. Meta menetapkan user_id di webhook messages baik pengguna memiliki username maupun tidak, sehingga sebagian besar pengguna datang dengan nomor telepon dan BSUID sekaligus.

Bisakah nomor Coexistence memiliki username bisnis?

Bisa. Sejak 29 Juni 2026 bisnis dapat mengadopsi atau mengubahnya di Meta Business Suite, WhatsApp Manager, aplikasi WhatsApp Business, atau Username API; ini tidak menyembunyikan nomor bisnis, dan business_username_updates melaporkan setiap perubahan status.

Apakah BSUID berlaku lintas Business Portfolio?

Tidak. BSUID milik satu portofolio dan pengguna, dan nomor di portofolio lain tidak dapat mengirim pesan kepadanya. Bisnis terkelola yang didaftarkan Meta mendapatkan parent BSUID, dengan ENT setelah kode negara, yang berlaku lintas portofolio yang terdaftar.

Berapa biaya easyCoexistence untuk satu nomor WhatsApp?

US$ 9 hingga US$ 0.75 per koneksi per bulan, tergantung jumlah koneksi Anda, dan 3 hari pertama gratis. Biaya pesan Meta sendiri tetap ditagihkan ke metode pembayaran WhatsApp Business Account Anda.

Lanjut membaca

Siap memulai?

Konfigurasikan WhatsApp Coexistence dalam hitungan menit, bukan bulan. Aplikasi tetap berfungsi di ponsel.

Mulai uji coba gratis

Diverifikasi pada