Özet: WhatsApp, Haziran 2026'da telefon numaralarını BSUID'ler (Business-Scoped User IDs) ile değiştiriyor. Her iki alanı da veritabanınızda saklayın, tanımlayıcı çözümleme için 3 katmanlı yedekleme modelini uygulayın ve webhook'lardaki from alanının null olmasını bekleyin. BSUID formatı: ülke.alfanümerik — örn.: US.13491208655302741918.
Haziran 2026, telefon tabanlı chatbot'ları bozacak. WhatsApp, kullanıcı adları ve BSUID (Business-Scoped User ID) adlı yeni bir tanımlama sistemi sunuyor. Telefon numaraları kayboluyor; BSUID'ler kalıyor. Entegrasyonunuz sadece telefon numaralarını saklıyorsa, E.164 adreslerine mesaj gönderiyorsa veya from alanının her zaman telefon numarası içerdiğini varsayıyorsa, haftalar içinde çökecek bir temel üzerine inşa ediyorsunuz.
Bu rehber, üretim ortamında WhatsApp otomasyonu çalıştıran backend geliştiricileri için: chatbot oluşturucular, bildirim sistemleri olan SaaS kurucuları ve kurumsal mesajlaşma yığınlarını sürdüren entegrasyon mühendisleri. BSUID'nin ne olduğunu, neden mevcut sistemleri bozduğunu ve Haziran 2026'dan önce tam olarak nasıl geçiş yapılacağını anlamanız gerekir.
BSUID Nedir ve Haziran 2026 Neden Her Şeyi Değiştiriyor
BSUID formatı: saklamanız gereken ülke kodu artı entropi. Bir Business-Scoped User ID, ülke kodunu alfanümerik bir diziyle birleştirir: {ülke}.{alfanümerik}. Örnek: US.13491208655302741918. Bu tanımlayıcı, WhatsApp Business API etkileşimleri için birincil adres olarak telefon numarasının yerini alır.
Değişim kozmetik değil. WhatsApp, kullanıcıların işletme kişilerinden telefon numaralarını gizlemek için ayarlayabileceği kullanıcı adları tanıtıyor. Bir kullanıcı telefon numarasını gizlediğinde, BSUID tek kullanılabilir tanımlayıcı haline gelir. Bu kavramsal olarak, WhatsApp'ın 2024'ten beri geçiş yaptığı LID (Line Identity) ile aynıdır. Fark: LID dahili bir geçişti; BSUID, kodunuzun ele alması gereken halka açık gerçekliktir.
Yetkili kaynak zaman çizelgesini onaylıyor: WhatsApp kullanıcı adları ve BSUID, Haziran 2026'da başlatılıyor. Whapi.Cloud'un WhatsApp kullanıcı adları hakkındaki SSS'sinde belirtildiği gibi, BSUID kavramsal olarak LID ile aynıdır — API çalışması için yeni birincil tanımlayıcıdır. Uyarlanmayan sistemler, başarılı gönderimlerden ayırt edilemez sessiz arızalar yaşayacaktır.
Bu göç modelini daha önce gördük. WhatsApp, dahili altyapıyı telefon tabanlı adreslemeden LID tabanlı yönlendirmeye geçirdiğinde, açık kaynak kütüphaneleri kritik değişikliklerle karşılaştı. Aynı modeller BSUID ile tekrarlanıyor — ancak bu kez etki dışa dönük. Mesajınız gönderildi olarak bildirilebilirken kullanıcı asla ulaşmayabilir.
Arıza Senaryosu: Telefon Numaraları Hayalet Olduğunda
Hayalet sohbetler: kimseye ulaşmayan numaralara gönderilen mesajlar. Bu, geçiş yapmazsanız kullanıcılarınızın yaşayacağı somut arızadır. WhatsApp, kullanıcı adı gizliliğini tam olarak etkinleştirdiğinde, telefon numaralarını gizlemiş kullanıcılar artık E.164 adreslerine gönderilen mesajları almayacak. API çağrınız başarı döndürür — HTTP 200, mesaj ID'si atanır — ancak mesaj bir teslimat boşluğuna girer.
İşte hayalet sohbet senaryosunun pratikte nasıl göründüğü. Sisteminiz bir müşterinin telefon numarasını saklar: +12025551234. Bu numarayı hedef olarak kullanarak bir mesaj gönderirsiniz. API isteği kabul eder. Ancak kullanıcı kullanıcı adı gizliliğini etkinleştirdiği için WhatsApp istemcisi artık telefon numarasıyla adreslenen mesajları yönlendirmiyor. Mesaj sessizce atılır. Aldığınız webhook payload'ları da kullanıcılar numaralarını gizlediğinde değişebilir.
// HAYALET SOHBET SENARYOSU — Bu kod Haziran 2026'da bozulacak
// Kullanıcı gizlediğinde telefon numarasına göndermek = sessiz arıza
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WHAPI_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '+12025551234', // Telefon numarası — ULAŞMAYABİLİR
body: 'Siparişiniz kargolandı!'
})
});
// HTTP 200 döndü, mesaj gönderildi görünüyor
// Ancak kullanıcı asla almıyor — hayalet sohbet oluşturuldu
console.log('Mesaj gönderildi:', response.data);
Hayalet sohbet fenomeni zaten LID geçiş aşamasında gözlemlenebilir. Geliştiriciler, geçerli telefon numaralarının lookup API'lerinden null döndürdüğünü ve bu numaralara gönderilen mesajların teslim edilmemiş konuşmalar oluşturduğunu bildiriyor. BSUID geçişi Haziran 2026'da tamamlandığında, bu, gizlilik etkin kullanıcılar için varsayılan davranış olacak — bir uç durum değil.
Tipik hususlar: Hayalet sohbetler, görünür hatalardan daha kötüdür. Hata koduyla başarısız teslimat, yeniden deneme mantığını ve uyarıları tetikler. Hayalet sohbet, müşteri hiçbir şey almazken loglarınızda başarı gibi görünür. Metrikleriniz %98 teslimat gösterirken, gerçek erişim gizlilik etkin kullanıcılar için %60 veya daha düşük olabilir.
API Nasıl Bozulur: Webhook'lardan Veritabanı Anahtarlarına
From alanı null: veritabanı varsayımlarınız ölür. En kritik değişiklik webhook payload'larındadır. Bir kullanıcı telefon numarasını gizlediğinde, gelen mesaj webhook'larındaki from alanı boş veya null olabilir. Her mesajın geçerli bir telefon numarası göndericisi olduğu varsayımıyla inşa edilmiş sistemler, ayrıştırma aşamasında başarısız olacaktır.
Azure Communication Services'ın belgelediği gibi (2024): "Bir kullanıcı telefon numarasını gizlediğinde, from alanı artık boş veya null olabilir." Bu teorik bir risk değil. Webhook'ları nasıl ayrıştırdığınızı, konuşma geçmişini nasıl sakladığınızı ve gelen mesajları müşteri kayıtlarına nasıl bağladığınızı etkileyen belgelenmiş bir davranış değişikliğidir.
Veritabanı etkisi aynı derecede ciddidir. E.164, WhatsApp sonsuzluğu değiştirene kadar sonsuzdu. Mevcut sistemler genellikle telefon numaralarını, konuşma tablolarını müşteri tablolarına bağlayan yabancı anahtarlar olarak kullanır. BSUID'ler birincil tanımlayıcılar olarak telefon numaralarının yerini aldığında, bu yabancı anahtar ilişkileri kırılır. WHERE phone = '+12025551234' kullanan bir veritabanı araması, tanımlayıcı artık US.13491208655302741918 olduğunda sonuç döndürmez.
Veri modeli uyumsuzluğu, bu göçün gizli maliyetidir. to ve from alanlarının her zaman E.164 telefon numaraları içerdiğini varsayan sistemler, yabancı anahtar kırılması, BSUID'ler altında oluşturulan yinelenen müşteri kayıtları ve kayıp konuşma threading'i yaşayacaktır. Göç, sadece kod güncellemeleri değil, şema değişiklikleri gerektirir.
Telefon Numarası vs LID vs BSUID Karşılaştırması:
| Öznitelik | Telefon Numarası (E.164) | LID (Line Identity) | BSUID (Business-Scoped User ID) |
| Format | +{ülke}{numara} örn.: +12025551234 |
{alfanümerik} örn.: [email protected] |
{ülke}.{alfanümerik} örn.: US.13491208655302741918 |
| Görünürlük | Halka açık (kullanıcı izin verirse) | Dahili | API odaklı |
| Kullanılabilirlik | Azalıyor — kullanıcılar gizleyebilir | BSUID'ye geçiş | Haziran 2026'dan itibaren birincil |
| Lookup güvenilirliği | Hâlâ çalışıyor (şimdilik) | Geçerli kullanıcılar için null döndürür | Doğrudan — lookup gerekmez |
| Saklama gereksinimi | Geri uyumluluk için sakla | Kullanımdan kaldırıldı | Zorunlu birincil anahtar |
Üç Katmanlı Yedekleme Modeli
LID lookup başarısız olur; yedeklemeler üretimi kurtarır. Telefon numaralarını LID'lere çözen lookup API'leri zaten geçerli WhatsApp kullanıcıları için null döndürüyor. lid-mapping.update webhook olayı tutarsız şekilde ateşleniyor, güvenilir LID-telefon eşlemesini engelliyor. Üretim sistemi yalnızca lookup'a güvenemez. Çözümleme başarısız olduğunda bir yedekleme stratejisi gerekir.
3 katmanlı yedekleme modeli, LID göçünden ortaya çıktı ve doğrudan BSUID adaptasyonuna uygulanıyor. Bu modeli milyonlarca mesajı işleyen üretim sistemlerinde gözlemledik. Katmanlar sırayla çalışır: önce BSUID, sonra LID lookup, sonra telefon yeniden deneme. Her katman, öncekinin arıza modunu ele alır.
Katman 1 — Doğrudan BSUID gönderimi: Önceki etkileşimden veya webhook'tan BSUID'niz varsa, doğrudan onu kullanarak gönderin. Bu en güvenilir yoldur — lookup gerekmez, çözümleme belirsizliği yok. BSUID formatı öngörülebilir: ülke.alfanümerik.
Katman 2 — Önbellekli LID lookup: Telefon numaranız var ancak BSUID'niz yoksa, /contacts/lids endpoint'i üzerinden LID lookup deneyin. Başarılı eşlemeleri Redis veya veritabanınızda TTL ile saklayın. Lookup null döndürebilir — bu beklenen bir durumdur. Böyle olduğunda 3. katmana geçin.
Katman 3 — Hayalet algılamalı telefon yeniden deneme: Yedekleme olarak telefon numarasına gönderin. Teslimat makbuzlarını izleyin. Bilinen aktif bir kullanıcıya gönderilen mesaj, diğer mesajlar teslim edilirken 24 saat içinde teslimat onayı göstermezse, manuel inceleme için işaretleyin. Bu sizin hayalet sohbet dedektörünüzdür.
// BSUID GÖÇÜ İÇİN ÜÇ KATMANLI YEDEKLEME MODELİ
// BSUID → LID Lookup → Hayalet algılamalı Telefon dener
async function sendWithFallback(phoneNumber, messageBody) {
// Katman 1: Önce önbelleğe alınmış BSUID'yi dene
const cachedBSUID = await db.get(`bsuid:${phoneNumber}`);
if (cachedBSUID) {
return await sendMessage(cachedBSUID, messageBody, 'bsuid');
}
// Katman 2: Önbellekleme ile LID lookup dene
try {
const lidResponse = await fetch(
`https://gate.whapi.cloud/contacts/lids/${phoneNumber}`,
{ headers: { Authorization: `Bearer ${token}` } }
);
const lidData = await lidResponse.json();
if (lidData.lid) {
// LID'yi BSUID formatına dönüştür ve önbelleğe al
const bsuid = `${lidData.country}.${lidData.identifier}`;
await db.setex(`bsuid:${phoneNumber}`, 86400, bsuid);
return await sendMessage(bsuid, messageBody, 'bsuid');
}
} catch (e) {
// Lookup başarısız oldu — logla ve yedeklemeye devam et
logger.warn(`LID lookup ${phoneNumber} için başarısız oldu`);
}
// Katman 3: Hayalet algılama bayrağı ile telefon yedeklemesi
// Bu yedekleme olmadan, geçerli kullanıcılar hiçbir şey almaz
const result = await sendMessage(phoneNumber, messageBody, 'phone');
await db.sadd('ghost-watch', phoneNumber); // Teslimatı izle
return result;
}
3 katmanlı modeli atlayan projeler, WhatsApp kullanıcı adı gizliliğini yeni bölgelerde başlattığında ani teslimat düşüşleri görmeye meyleder. Yedekleme modeli, savunmacı kodlama değil — Haziran 2026 için asgari yaşayabilir mimaridir.
Veritabanı Şemanız Şimdi Ne Saklamalı
Veritabanı yabancı anahtar kırılması, geliştiricilerin en sık bildirdiği göç ağrısıdır. E.164 telefon numaralarını değişmez tanımlayıcılar olarak varsayan sistemler başarısız olacaktır. Telefon numaralarını tek birincil anahtar değil, birden fazla olası tanımlayıcıdan biri olarak ele alan bir şemaya ihtiyacınız var.
Gerekli şema değişiklikleri:
-
Birincil tanımlayıcı alanı: WhatsApp işlemleri için birincil arama anahtarı olarak
bsuid VARCHAR(50)ekleyin. Format:XX.XXXXXXXXXXXXXXXXXXX(ülke kodu + nokta + 17-20 rakam). -
İkincil telefon alanı: Geri uyumluluk ve okunabilir görüntüleme için
phone VARCHAR(20)alanını tutun, ancak ona işaret eden yabancı anahtar kısıtlamalarını kaldırın. -
Tanımlayıcı çözümleme önbelleği: Çözümleme sonuçlarını önbelleğe almak ve kökeni izlemek için
identifier_mappings (phone, bsuid, lid, last_updated, source)lookup tablosu ekleyin. -
Null-güvenli webhook ayrıştırıcı: Nullable
fromalanlarını kabul etmek için webhook işleyicilerini güncelleyin. Null olduğunda, varsa BSUID alanlarından gönderici kimliğini çıkarın. -
Göç zaman damgası: Hangi kayıtların BSUID ile güncellendiğini izlemek için
bsuid_migrated_atekleyin.
Göçlerde en sık karşılaştığımız model: ekipler telefon numaralarını birincil anahtar olarak tutmaya ve BSUID'yi isteğe bağlı ikincil alan olarak saklamaya çalışır. Bu, bir kullanıcı telefon numarasını gizlediğinde başarısız olur — BSUID altında yinelenen bir müşteri kaydı oluşturursunuz, konuşma geçmişini ve sipariş verilerini parçalarsınız. BSUID kanonik tanımlayıcı olmalıdır; telefon görüntüleme metadata'sıdır.
Sektör Etkisi: E-ticaret ve Sağlık Örnekleri
%70 otomasyon, tanımlayıcılar bozulursa %0 demektir. BSUID göçü sadece teknik bir yeniden düzenleme değil — operasyonel değeri tehdit ediyor. WhatsApp üzerinden %70 destek sorgusunu otomatikleştiren e-ticaret işletmeleri, tanımlayıcı çözümlemeleri başarısız olursa bu otomasyonun sıfıra düştüğünü görecektir. Randevu hatırlatıcılarıyla %40-65 no-show azaltımı sağlayan sağlık klinikleri, mesajlar hayalet sohbetlere dönüşürse bu verimliliği kaybedecektir.
E-ticaret kullanım durumu: Sipariş takibi, terk edilmiş sepet kurtarma ve müşteri desteği otomasyonu, güvenilir mesaj teslimatına bağlıdır. Tipik bir kurulum günde binlerce mesaj gönderir. %30'u kullanıcı adı gizliliğini etkinleştirmiş kullanıcılara gidiyorsa ve sistem BSUID işlemeye geçmemişse, bu günde yüzlerce teslim edilmemiş mesaj demektir. Müşteriler kargo bildirimleri almaz. Destek talep hacmi patlar.
Sağlık kullanım durumu: Randevu hatırlatma botları, mesajlar güvenilir şekilde hastalara ulaştığında %40-65 no-show azaltımı sağlar. Otomasyon, onaylanmış telefon numaralarına planlanan giden mesajlara bağlıdır. Hatırlatma sistemi BSUID saklamamışsa ve LID lookup null döndürürse, hatırlatma bir hayalet sohbete dönüşür. Hasta randevuyu kaçırır. Klinik gelir kaybeder.
Her iki sektör de öngörülebilir mesaj yönlendirmesine bağlıdır. BSUID göçü, bu iş akışlarının güvenilirlik gerektirdiği yerde tam olarak öngörülemezlik getirir. Göç, isteğe bağlı bakım değil — operasyonel değerin korunmasıdır.
Haziran 2026 Göç Kontrol Listesi
Şimdi geçin veya sonra acil durumda geçin. Aşağıdaki kontrol listesi, WhatsApp entegrasyonunuzu BSUID geçişine hazırlamak için temel adımları kapsar. Hayalet sohbetlerden ve teslimat arızalarından kaçınmak için bunları Haziran 2026'dan önce tamamlayın.
Ön göç (Mayıs 2026'ya kadar tamamlayın):
-
Mevcut veritabanı şemasını denetle — telefon numaralarını yabancı anahtar olarak kullanan tüm tabloları belirle
-
Müşteri ve konuşma tablolarında telefon numaralarının yanına BSUID sütunu ekle
-
Mesaj gönderme mantığına 3 katmanlı yedekleme modelini uygula
-
Webhook ayrıştırıcılarını null
fromalanlarını düzgün şekilde ele alacak şekilde güncelle -
LID lookup endpoint davranışını test et — null yanıt işlemeyi belgele
Göç (1 Haziran 2026'ya kadar tamamlayın):
-
Mevcut kişiler için LID lookup API üzerinden toplu BSUID doldurma
-
Birincil gönderme mantığını birinci öncelikli tanımlayıcı olarak BSUID kullanacak şekilde değiştir
-
Hayalet sohbet izlemeyi etkinleştir — 24 saat içinde teslimat onayı olmayan mesajları izle
-
Müşteri destek dokümantasyonunu telefon numarası yerine BSUID'ye referans verecek şekilde güncelle
Göç sonrası izleme: Yinelenen müşteri kayıtlarına dikkat et — telefon tabanlı lookup'ların göç edilmiş BSUID kayıtlarını kaçırdığının bir işareti. Tanımlayıcı türüne göre teslimat oranlarını izle. BSUID üzerinden %95+ teslimat, telefon yedeklemesi üzerinden %80-90 bekleyin; fark hayalet sohbet riskini temsil eder.
Whapi.Cloud BSUID'yi Neden Bozulmadan İşliyor
Baileys bozuldu; Whapi.Cloud hazırlandı. Açık kaynak kütüphane ekosistemi, WhatsApp kimlik göçleriyle mücadele etti. Geliştiriciler, LID geçişlerinde Bad MAC hataları, No Session arızaları ve Invalid PreKey istisnaları bildiriyor. Bunlar uygulama katmanı hataları değil — altyapı düzeyinde düzeltmeler gerektiren protokol katmanı kırılmalarıdır.
Whapi.Cloud, API yüzeyinizin stabil kalması için protokol değişikliklerini yukarı akışta absorbe eder. Web oturum soket mimarisi — WhatsApp Web'in kullandığı aynı mekanizma — tarayıcı öykünme yaklaşımlarından daha stabil bir temel sağlar. WhatsApp tanımlayıcı formatlarını değiştirdiğinde, Whapi.Cloud altyapı ekibi protokol adaptasyonunu yönetir. HTTP API çağrılarınız değişmeden kalır.
Açık kaynak entegrasyonları, sorumlu taraf olmadan saat 3'te bozulur. Whapi.Cloud'un, üretim sorunlarını çözmek için müşterilere aktif olarak yardım eden canlı bir destek ekibi vardır — BSUID hazırlığı için göç rehberliği dahil. Yüzlerce entegrasyonu protokol değişikliklerinden geçirdik. Bu operasyonel geçmişten gelen model tanıma, kırılmaları önleyen altyapı iyileştirmelerini besler. Self-hosted kütüphaneler ile yönetilen ağ geçitleri arasında seçim yapan ekipler için BSUID göçü bir karar noktasıdır. Self-hosted yığınlar, GitHub sorunlarını izlemenizi, yamaları uygulamanızı, protokol değişikliklerini test etmenizi ve göç zamanlamasını kendiniz yönetmenizi gerektirir. Yönetilen altyapı, bu operasyonel yükü sağlayıcıya aktarır. WhatsApp'ın bildirimsiz protokol değişiklikleri yaptığı göz önüne alındığında, yönetilen yol küçük-orta ölçekte self-hosted'ın eşleşemediği öngörülebilirlik sunar.
BSUID göçünüz sırasında beklenmedik davranışla karşılaşırsanız, whapi.cloud'daki sohbet widget'ı üzerinden Whapi.Cloud destek ekibiyle iletişime geçin — ekip, üretim sorunlarını çözmek için müşterilere aktif olarak yardım eder.
Resmi WhatsApp Business API göç yolunu burada ele almayacağız — bu, Meta işletme doğrulaması, şablon onay iş akışları ve resmi olmayan API mimarisiyle uyumsuz mesaj başına fiyatlandırma katmanları gerektirir. Resmi API'ye bağlı kalan ekipler için doğrudan Meta BSP dokümantasyonuna başvurun.
