Username WhatsApp dan BSUID: Cara Menyiapkan Webhook, CRM, dan Chatbot agar Chat Tanpa Nomor Tidak Hilang

Jawaban langsung: WhatsApp mulai memberi pengguna username pada 2026, dan chat dari pengguna itu bisa tiba tanpa nomor telepon di webhookWebhookPesan otomatis yang sebuah sistem kirim ke sistem lain tepat saat sesuatu terjadi, misalnya pesan WhatsApp masuk.Buka glosarium. Sistem Anda tetap menerima BSUID (business-scoped user ID) pada from_user_id dan user_id. Jadi baca BSUID, simpan BSUID pada kontak, dan balas dengan field recipient.

Kondisi utama: panduan ini berlaku untuk bisnis yang memakai WhatsApp Business Platform, yaitu Cloud APIAPIPintu resmi yang dipakai 2 sistem untuk saling mengirim data, tanpa orang menyalin data secara manual.Buka glosarium langsung, BSP, atau iklan Click to WhatsAppCTWAIklan Click-to-WhatsApp. Iklan ini membawa orang dari Facebook atau Instagram langsung ke percakapan WhatsApp Anda.Cara tracking iklan CTWA. Batas: BSUID tidak menggantikan nomor untuk semua hal. Template otentikasi one-tap, zero-tap, dan copy code tetap butuh nomor, dan invoice atau lead yang memakai nomor juga tetap butuh nomor.

Kami menulis panduan ini pada 2 Oktober 2026. Sumbernya adalah dokumen Meta Business-scoped user IDs (diperbarui 15 September 2026), App Dashboard dan WhatsApp Manager kami, dan perubahan pada asisten WhatsApp kami. Nomor, ID, dan token pada gambar disamarkan, dan semua payload memakai data dummy.

Apa yang rusak saat pengguna memakai username

Integrasi lama memakai nomor telepon sebagai kunci. Parser membaca messages[].from, CRM mencari kontak dengan nomor, dan chatbot membalas ke nomor yang sama. Saat pengguna memakai username, Meta bisa menghapus from dan wa_id dari webhook.

Akibatnya ada 3 kegagalan yang sering muncul:

• Parser membuang pesan karena field from kosong.
• CRM membuat kontak baru tanpa nama, atau gagal menyimpan chat.
• Chatbot tidak bisa membalas karena tidak tahu tujuan kiriman.

Meta menulis bahwa dukungan BSUID wajib bagi partner, bisnis yang terhubung langsung, dan pengiklan CTWA. FAQ Meta juga menulis bahwa bisnis yang belum siap tidak punya jalan perbaikan untuk pesan yang gagal diproses. Bila Anda memakai iklan CTWA, baca juga cara tracking iklan Click to WhatsApp, karena alur atribusiAtribusiCara sebuah sistem menentukan iklan atau channel mana yang mendapat nilai atas 1 penjualan.Klik ramai, sales sepi: masalahnya bisa di tracking itu juga membaca identitas pengirim.

Meta sendiri menampilkan peringatan ini di App Dashboard. Artinya, persiapan BSUID sudah menjadi pekerjaan rutin untuk setiap aplikasi WhatsApp, bukan rencana jangka panjang.

Cara kerja username, BSUID, dan nomor telepon

Username pengguna bersifat opsional

Pengguna boleh memakai username atau tidak. Pengguna dengan username melihat username, bukan nomor, di aplikasi. Bisnis tidak bisa mengatur pilihan ini, jadi integrasi Anda harus siap untuk kedua bentuk (sumber: Meta, User usernames).

BSUID adalah ID pengguna per portofolio bisnis

BSUID dimulai dengan kode negara ISO 3166 alpha-2, lalu titik, lalu sampai 128 huruf atau angka. Contoh dari Meta: US.13491208655302741918. BSUID berlaku untuk 1 portofolio bisnisBusiness ManagerTempat Meta menyimpan aset iklan usaha Anda: akun iklan, Halaman, pixel, dan hak akses orang.Buka glosarium, jadi nomor bisnis dari portofolio lain gagal mengirim ke BSUID itu.

Sejak awal April 2026, BSUID ada di setiap webhook messages, walau pengguna belum memakai username. Pakai BSUID utuh saat mengirim. Request gagal bila kode negara, titik, atau karakter lain diubah.

Kapan nomor tetap ikut di webhook

Meta tetap mengirim nomor bila 1 dari 3 kondisi ini terpenuhi:

• Nomor bisnis Anda mengirim pesan atau menelepon nomor pengguna dalam 30 hari terakhir.
• Nomor bisnis Anda menerima pesan atau telepon dari nomor pengguna dalam 30 hari terakhir.
• Pengguna ada di buku kontak bisnis (contact book) milik Meta.

Aturan 30 hari dihitung per nomor bisnis. Buku kontak berlaku per portofolio, tetapi hanya mencatat interaksi setelah fitur itu aktif. Sumber: Meta, Phone numbers dan Contact book.

Inti diagram di atas: user_id dan from_user_id selalu ada. Jadi jadikan BSUID identitas cadangan yang wajib dibaca, bukan field tambahan.

Parent BSUID untuk bisnis dengan banyak portofolio

Bisnis terkelola dengan banyak portofolio bisa meminta parent BSUID melalui kontak Meta mereka. Bentuknya memakai ENT, misalnya US.ENT.11815799212886844830, dan datang pada field parent_user_id. Parent BSUID bisa dipakai oleh semua nomor bisnis dari portofolio yang terdaftar.

BSUID berubah saat pengguna mengganti nomor

Saat pengguna mengganti nomor, Meta membuat BSUID baru. Perubahan ini datang sebagai webhook messages bertipe system.

Nilai system.type adalah user_changed_number bila nomor baru boleh dibagikan, atau user_changed_user_id bila hanya BSUID yang boleh dilaporkan. Kedua bentuk membawa previous_user_id. Sumber: Meta, System messages webhooks.

Perbandingan nomor, BSUID, parent BSUID, dan username

Identitas	Field webhook	Cakupan	Bisa untuk kirim pesan	Bisa berubah
Nomor telepon	wa_id, from	Global	Ya, field to	Saat pengguna ganti nomor
BSUID	user_id, from_user_id	1 portofolio bisnis	Ya, field recipient, sejak Juli 2026	Saat pengguna ganti nomor
Parent BSUID	parent_user_id	Semua portofolio yang terdaftar	Ya, field recipient	Saat pengguna ganti nomor
Username	profile.username	Tampilan di aplikasi	Tidak	Ya, pengguna boleh menggantinya

Rekomendasi Rama Digital: simpan nomor dan BSUID pada 1 kontak yang sama. Pakai username hanya sebagai label tampilan, karena pengguna bisa mengganti username kapan saja tanpa mengubah BSUID.

Prasyarat

• Akses admin atau developer ke aplikasi Meta yang memegang webhook WhatsApp.
• Akses ke WhatsApp Manager untuk nomor bisnis Anda.
• 1 endpoint webhook staging yang terpisah dari produksi.
• Akses ke kode parser webhook dan skema data CRM atau inbox.
• 1 nomor uji pribadi untuk menguji tombol permintaan nomor.

Langkah 1: Uji 4 skenario webhook dari App Dashboard

Buka App Dashboard > Use cases > Connect with customers through WhatsApp > Customize > Configuration. Aplikasi yang dibuat sebelum Desember 2025 memakai jalur App Dashboard > WhatsApp > Configuration. Cari baris messages pada bagian Webhook fields, lalu pakai tautan Test di baris itu.

Tautan Test mengirim payload uji ke endpoint webhook aplikasi itu. Jadi arahkan Callback URL ke staging dulu, atau pakai aplikasi uji terpisah. Pada uji kami, kami tidak menekan tombol ini karena aplikasi kami terhubung ke chatbot produksi.

Meta menyediakan 4 skenario uji:

1. Pengguna belum memakai username: payload memuat nomor dan BSUID.
2. Pengguna memakai username dan nomor tidak tersedia: payload memuat username dan BSUID saja.
3. Pengguna memakai username dan nomor tersedia: payload memuat semua field.
4. Parent BSUID ada: payload memuat parent BSUID di samping BSUID biasa.

Verifikasi: endpoint staging menerima 4 payload, dan log Anda mencatat 4 pesan tanpa error. Sumber: Meta, Webhook testing.

Langkah 2: Terima from_user_id di parser webhook

Ubah parser agar pesan tetap diproses saat from kosong. Ini contoh payload skenario 2 dengan data dummy:

{
  "contacts": [{
    "profile": { "name": "Sinta", "username": "sinta.contoh" },
    "user_id": "ID.1234567890123456789"
  }],
  "messages": [{
    "from_user_id": "ID.1234567890123456789",
    "id": "wamid.CONTOH001",
    "timestamp": "1790900000",
    "type": "text",
    "text": { "body": "Halo, masih buka?" }
  }]
}

Baca nomor bila ada, lalu baca BSUID sebagai cadangan. Buang event hanya bila kedua identitas kosong.

const msg = value.messages?.[0];
const contact = value.contacts?.[0] ?? {};
const phone = msg?.from ?? contact.wa_id ?? null;
const bsuid = msg?.from_user_id ?? contact.user_id ?? null;
// Buang event hanya bila kedua identitas kosong.
if (!msg || (!phone && !bsuid)) return logAndSkip(value);
const username = contact.profile?.username ?? null;

Verifikasi: 1 test otomatis memakai payload di atas, dan pesan itu masuk ke antrean balasan. Field username juga tersimpan untuk label kontak.

Langkah 3: Simpan chat dengan kunci nomor atau BSUID

Cari kontak dengan nomor ATAU BSUID. Bila Anda hanya mencari dengan nomor, 1 orang bisa menjadi 2 kontak saat nomornya muncul kemudian. Simpan BSUID utuh, termasuk kode negara dan titik.

// Cari kontak dengan nomor ATAU BSUID, jangan hanya nomor.
let person = await findContact({ phone, bsuid });
if (!person) person = await createContact({ phone, bsuid, username });
else await updateContact(person.id, {
  phone: phone ?? person.phone,
  bsuid: bsuid ?? person.bsuid,
  username: username ?? person.username,
});

// BSUID berubah saat pengguna mengganti nomor.
if (msg.type === 'system' && ['user_changed_number', 'user_changed_user_id'].includes(msg.system?.type)) {
  await moveBsuid(msg.system.previous_user_id, msg.system.user_id, msg.system.wa_id ?? null);
}

Verifikasi: kirim payload skenario 2, lalu kirim skenario 3 untuk BSUID yang sama. Hasil yang benar adalah 1 kontak dengan nomor dan BSUID, bukan 2 kontak.

Langkah 4: Kirim balasan dengan field recipient

Sejak Juli 2026, Messages API menerima BSUID. Isi recipient dengan BSUID atau parent BSUID, lalu hapus to. Bila request memuat to dan recipient, Meta memakai to.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "ID.1234567890123456789",
  "type": "text",
  "text": { "body": "Halo Sinta, kami buka sampai 21.00." }
}

Respons yang berhasil memuat contacts[].user_id. Field wa_id tidak ada bila Anda mengirim ke BSUID.

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "ID.1234567890123456789", "user_id": "ID.1234567890123456789" }],
  "messages": [{ "id": "wamid.CONTOH002" }]
}

Aturan jendela 24 jam tidak berubah, jadi pesan bebas tetap hanya bisa dikirim di dalam jendela itu. Biaya pesan dibahas di jawaban tentang balas chat WhatsApp API berbayar.

Error 131062 berarti BSUID tidak didukung untuk jenis pesan itu, misalnya template otentikasi one-tap. Sumber: Meta, Send message requests dan Error codes.

Langkah 5: Minta nomor dengan tombol REQUEST_CONTACT_INFO

Pakai tombol ini saat sebuah alur butuh nomor, misalnya invoice, pengiriman barang, atau OTP. Tombol tersedia sejak awal Juli 2026 pada template utility dan marketing, atau sebagai pesan interaktif request_contact_info. Label tombol tidak bisa diubah.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "recipient": "ID.1234567890123456789",
  "type": "interactive",
  "interactive": {
    "type": "request_contact_info",
    "body": { "text": "Bagikan nomor Anda agar kami bisa mengirim invoice." },
    "action": { "name": "request_contact_info" }
  }
}

Saat pengguna menekan tombol, nomor tampil di chat dan Meta mengirim webhook contacts. Webhook itu memuat origin: contact_request, from_user_id, dan nomor pada phones[].wa_id. Simpan nomor itu pada kontak yang sudah punya BSUID tersebut (sumber: Meta, Requesting phone numbers from users).

Verifikasi: tekan tombol dari nomor uji pribadi Anda. Kontak di CRM sekarang punya nomor dan BSUID, dan riwayat chat tetap 1.

Langkah 6 (opsional): Klaim username bisnis di WhatsApp Manager

Buka WhatsApp Manager > Phone numbers, pilih ikon pengaturan pada nomor bisnis, lalu buka tab Profile. Bagian Username menampilkan username saat ini dan statusnya. Meta juga menerima klaim dari Meta Business Suite, aplikasi WhatsApp Business, atau Username API sejak 29 Juni 2026.

Pada uji kami, 2 Oktober 2026, username @ramadigital.id berstatus Reserved dengan tanggal pembaruan 17 September 2026. Status ini berarti username sudah disetujui, tetapi pengguna belum melihatnya sampai fitur username tersedia untuk semua pengguna.

Aturan format username bisnis menurut Meta:

• Pakai huruf a-z, angka 0-9, titik, dan garis bawah saja.
• Pakai 3 sampai 35 karakter, dengan minimal 1 huruf.
• Jangan mulai atau akhiri dengan titik, dan jangan pakai 2 titik berurutan.
• Jangan mulai dengan www, dan jangan akhiri dengan domain seperti .com.

Username bisnis tidak menyembunyikan nomor bisnis Anda. Di jendela chat, WhatsApp memakai urutan ini: nama kontak tersimpan, nama bisnis terverifikasi, username, lalu nomor.

Error 147002 berarti batas pesan (messaging limit) portofolio Anda masih terlalu rendah. Sumber: Meta, Business usernames.

Langkah 7: Periksa kotak masuk tim

Pastikan tim CS melihat chat tanpa nomor sebagai chat biasa. Di Konektor, produk yang Rama Digital bangun dan jalankan sendiri, buka Percakapan > Kotak Masuk. Kontak dari pengguna username tampil dengan nama profil, atau @username bila tidak ada nama profil.

Menurut panduan Konektor untuk chat dari pengguna username WhatsApp, 3 hal belum terjadi sebelum nomor diketahui:

• Lead otomatis belum dibuat.
• KonversiKonversiTindakan yang Anda hitung sebagai hasil, misalnya pesanan terbayar, pendaftaran, atau chat yang menjadi calon pembeli.Buka glosarium ke platform iklan belum dikirim.
• Template otentikasi one-tap, zero-tap, dan copy code tidak bisa dikirim.

Saat ini Konektor menampilkan chat tanpa nomor hanya lewat koneksi WhatsApp Business resmi. Istilah lengkapnya ada di glosarium BSUID Konektor. Pada 2 Oktober 2026, kotak masuk kami belum memuat chat dari pengguna username, jadi artikel ini tidak memuat screenshot kontak tersebut.

Verifikasi: kirim payload skenario 2 ke staging. Tim CS bisa membuka chat itu dan membalasnya dari inbox.

Contoh kerja: 1 chat tanpa nomor sampai nomor diketahui

Pada uji kami, 2 Oktober 2026, asisten WhatsApp Rama Digital (Wulan) membuang pesan yang tidak punya field from. Pada hari yang sama, kami mengubahnya: parser membaca from_user_id, chat disimpan dengan BSUID utuh, dan balasan memakai recipient. Kami menguji perubahan itu dengan payload dummy skenario 2.

Kami juga menemukan 2 batas. Invoice atau order dari chat butuh nomor, jadi chat dari pengirim yang hanya punya BSUID pindah ke tim. Catatan serah terima ke tim juga tidak memuat tautan wa.me, karena tautan itu butuh nomor.

Tabel berikut adalah simulasi dengan data dummy. Tabel ini memakai alur yang sama.

Waktu	Input	Yang sistem catat	Keluaran
2 Okt, 09.00	Sinta (@sinta.contoh) mengirim chat pertama. Tidak ada interaksi dalam 30 hari.	from_user_id = ID.1234567890123456789, tanpa from	Kontak baru dengan kunci BSUID dan label @sinta.contoh
2 Okt, 09.01	Chatbot membalas jam buka.	Request dengan recipient	Respons memuat contacts[].user_id
2 Okt, 09.05	Sinta meminta invoice.	Alur invoice butuh nomor	Chatbot mengirim tombol request_contact_info
2 Okt, 09.06	Sinta menekan tombol.	Webhook contacts, origin: contact_request, nomor 62812XXXXXXX	Nomor masuk ke kontak yang sama
2 Okt, 09.08	Tim menerbitkan invoice.	Kontak punya nomor dan BSUID	Invoice terkirim, riwayat chat tetap 1
30 Okt, 10.00	Sinta mengganti nomor.	Pesan system, previous_user_id = BSUID lama	BSUID baru ID.9876543210987654321 pindah ke kontak yang sama

Checklist 7 hari

1. Developer mengirim 4 skenario uji ke endpoint staging. Bukti: 4 payload tersimpan di log.
2. Developer menambah test untuk pesan tanpa from. Bukti: test skenario 2 lulus.
3. Admin CRM menambah kolom BSUID dan username pada kontak. Bukti: skema data baru.
4. Developer mengirim balasan dengan recipient untuk kontak tanpa nomor. Bukti: respons dengan contacts[].user_id.
5. Pemilik proses mendaftar alur yang butuh nomor, misalnya invoice, OTP, dan konversi iklan. Bukti: daftar alur dan jalur penggantinya.
6. Tim CS menyiapkan pesan request_contact_info. Bukti: 1 uji dari nomor pribadi dengan origin: contact_request.
7. Developer menangani pesan system pergantian ID. Bukti: test dengan previous_user_id lulus.
8. Kriteria berhenti: hentikan pekerjaan ini bila 4 skenario lulus dan log mencatat 0 pesan terbuang selama 7 hari.

Pertanyaan yang sering diajukan

Apakah saya harus mendukung BSUID walau belum ada pelanggan yang memakai username? Ya. Meta menyebut dukungan BSUID wajib bagi partner, bisnis yang terhubung langsung, dan pengiklan CTWA. Bisnis tidak bisa mengatur kapan pelanggan memakai username.

Apa yang terjadi bila sistem saya belum siap saat pelanggan memakai username? Webhook tetap datang, tetapi tanpa nomor bila syarat nomor tidak terpenuhi. FAQ Meta menulis bahwa tidak ada jalan perbaikan untuk pesan yang gagal diproses karena sistem belum mendukung BSUID.

Apakah username bisnis menyembunyikan nomor bisnis saya? Tidak. Meta menulis bahwa username bisnis tidak dibuat untuk privasi. Nomor bisnis tetap tampil di profil bisnis Anda.

Apakah template marketing bisa dikirim ke BSUID? Ya. Marketing Messages API menerima nomor, BSUID, dan parent BSUID. Meta tetap menyarankan nomor, karena kiriman ke nomor membuat nomor tetap ikut di webhook berikutnya.

Apakah BSUID sama untuk semua nomor bisnis saya? BSUID sama untuk semua nomor dalam 1 portofolio bisnis. Nomor dari portofolio lain gagal mengirim ke BSUID itu, kecuali Anda memakai parent BSUID.

Berapa lama nomor pelanggan tetap ikut di webhook? Nomor ikut bila nomor bisnis yang sama berinteraksi dengan nomor pelanggan dalam 30 hari terakhir. Buku kontak Meta juga bisa menambahkan nomor, tetapi hanya untuk interaksi setelah fitur itu aktif.

Langkah berikutnya

Batas yang tetap berlaku: BSUID membuat chat tetap hidup, tetapi alur yang butuh nomor tetap butuh nomor. Lead otomatis, konversi iklan, invoice, dan template otentikasi menunggu sampai pelanggan membagikan nomor.

Bila chatbot WhatsApp Anda sudah berjalan dan perlu disiapkan untuk BSUID, lihat Jasa Optimasi Chatbot AI WhatsApp. Untuk memetakan parser, CRM, dan alur nomor bersama tim kami, jadwalkan Sesi Scoping Teknis 60 menit.

Sumber

• Meta for Developers: Business-scoped user IDs, diperbarui 15 September 2026, dibaca 2 Oktober 2026.
• Meta for Developers: Webhook testing, dibaca 2 Oktober 2026.
• Meta for Developers: FAQs tentang BSUID, dibaca 2 Oktober 2026.
• Konektor: Chat dari Pengguna Username WhatsApp, dibaca 2 Oktober 2026.
• Konektor: Glosarium BSUID, diperbarui 2 Oktober 2026.