Giriş yapınÜcretsiz denemeyi başlatın
Meta Tech Provider

WhatsApp kullanıcı adları ve işletmeye özel kullanıcı kimlikleri (BSUID): Cloud API webhook'larında neler değişiyor

WhatsApp kullanıcı adları, kullanıcıların telefon numarası yerine bir ad göstermesini sağlar. Bu yüzden 2026 Nisan başından itibaren Cloud API webhook'ları, user_id ve from_user_id alanlarında işletmeye özel bir kullanıcı kimliği (BSUID) da taşır; örneğin US.13491208655302741918. Kullanıcı adı olan ve son 30 gündür bu numarayla mesaj veya çağrı alışverişi olmayan, rehberde de bulunmayan bir kullanıcı için wa_id ve from alanları çıkarılır.

easyCoexistence, bir WhatsApp Business uygulama numarasını Coexistence üzerinden Cloud API'ye bağlar ve messages ile smb_message_echoes webhook'larını Meta'nın gönderdiği biçimde, BSUID alanları dahil, uç noktanıza yönlendirir; get_api_credentials ise kodunuza recipient ile yanıt vermesi için gereken bilgileri verir.

April 2026

BSUID'lerin, kullanıcı adlarının WhatsApp kullanıcılarına ulaşmasından önce Cloud API webhook'larında görünmeye başlaması.

July 2026

API'lerin BSUID'ye gönderilen mesajları kabul etmeye başladığı tarih; bu mesajlar to yerine recipient içinde belirtilir.

30 days

Her işletme telefon numarası için geçerli, kullanıcıyla yapılan herhangi bir mesaj veya çağrının numarasını webhook'larda tuttuğu geriye dönük süre.

128

BSUID'nin iki harfli ülke kodu ve noktadan sonraki alfanümerik karakterlerin çoğu.

131062

Messages API hatası: Bu mesaj için işletmeye özel kullanıcı kimliği (BSUID) alıcıları desteklenmiyor.

user_changed_user_id

Telefon numarası bildirilmeden iletilen BSUID değişikliğine ait sistem mesajı türü; eski BSUID previous_user_id alanında yer alır.

WhatsApp kullanıcı adları ve BSUID'ler nedir?

Kullanıcı adı, bir WhatsApp kullanıcısının ayarlayabildiği, uygulamada telefon numarası yerine gösterilen isteğe bağlı ve benzersiz bir addır; Meta kullanıcı adlarını 2026 boyunca kademeli olarak yayıyor. BSUID ise işletmelerin kullanıcıları yine de ayırt edebilmesi için Meta'nın eklediği arka uç tanımlayıcısıdır: otomatik üretilir, her Business Portfolio ve kullanıcı çifti için benzersizdir ve kullanıcının ISO 3166 iki harfli ülke kodu, bir nokta ve en fazla 128 alfanümerik karakterden oluşan bir değer olarak yazılır. Meta, iş ortaklarından ve doğrudan entegre olan işletmelerden bunu desteklemelerini istiyor; çünkü hiçbir işletme kullanıcılarının kullanıcı adı kullanıp kullanmayacağını kontrol edemez.

Yeni tanımlayıcıları hangi alanlar taşır?

Telefon numarasını taşıyan alanların yanına eklenen yeni özellikler; bunlar messages, status, system ve user_preferences webhook'ları genelinde yer alır. Üst alanlar yalnızca Meta'nın üst BSUID'lere kaydettiği Business Portfolio'lar için görünür; bu BSUID'ler kayıtlı portföyler arasında çalışır:

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

Telefon numarası ne zaman çıkarılır?

Kullanıcının bir kullanıcı adı olduğunda ve Meta'nın üç koşulundan hiçbirinin geçerli olmadığı durumda. Numara webhook'larda kalır; işletme telefon numarası son 30 gün içinde o kullanıcının numarasına mesaj gönderdiyse ya da onu aradıysa, bu süre içinde o numaradan mesaj veya çağrı aldıysa, ya da kullanıcı Business Portfolio'nun rehberinde kayıtlıysa. 30 günlük geri bakış süresi her işletme telefon numarası için ayrı sayılır; bu yüzden aynı portföydeki ikinci bir numara, aynı kullanıcı için yalnızca BSUID alabilir. Kullanıcı adı olmayan kullanıcılar ise hâlâ hem telefon numarası hem de BSUID ile gelmeye devam eder.

Gelen bir mesaj artık nasıl görünüyor?

Eskisi gibi, BSUID telefon numarasının yanında ya da onun yerine yer alır. Meta'nın örneğinde, numarası paylaşılamayan bir kullanıcı adı sahibi için contacts; profile.name, profile.username ve user_id taşır, mesajda ise eskiden from'un bulunduğu yerde from_user_id yer alır:

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

Durum webhook'ları nasıl değişiyor?

Gönderildi, iletildi ve okundu durumları, kullanıcının adı, user_id, numara paylaşılabildiğinde wa_id ve iletildi ile okundu durumlarında username içeren bir contacts dizisi kazanır. Durumlarda recipient_user_id BSUID'yi taşır; BSUID'ye gönderim yaptığınızda ve numara paylaşılamadığında recipient_id çıkarılır. Başarısız bir durumda contacts dizisi yoktur ve mesaj telefon numarasına gittiğinde recipient_user_id çıkarılır; bu yüzden başarısızlıkları mesaj kimliğine bağlayın.

Kullanıcıları nasıl saklayıp eşleştirmelisiniz?

Önce BSUID ile, telefon numarası geldiğinde ise ikinci anahtar olarak. BSUID'nin tamamını, ülke kodu ve nokta dahil, bir dize olarak saklayın; çünkü Meta, bunun herhangi bir bölümünü değiştiren istekleri reddeder. Portföyleriniz kayıtlıysa üst BSUID'yi de saklayın. Mevcut kayıtları, wa_id hâlâ geldiği sürece wa_id üzerinden eşleştirin ve BSUID'yi bunların yanında tutun; çünkü sonradan kullanıcı adı benimseyen bir kullanıcı numarası olmadan geri dönebilir. Meta'nın SSS sayfası, CRM'lerde ve onları besleyen araçlarda aynı eşleştirmeleri istiyor.

Bir kullanıcı telefon numarasını değiştirirse ne olur?

BSUID'si yeniden üretilir ve değişiklik, Meta'da abone olunabilecek bir user_id_update alanı olmadığı için messages alanında bir sistem mesajı olarak gelir. system.type, yeni numara sizinle paylaşılabildiğinde user_changed_number, yalnızca BSUID değişikliği bildirilebildiğinde user_changed_user_id değerini alır; system.user_id yeni BSUID'yi, system.previous_user_id eski BSUID'yi taşır ve kaydın nasıl devredildiği buradan anlaşılır. İki türü de ele alın.

Yalnızca BSUID ile bilinen bir kullanıcıya nasıl yanıt verirsiniz?

/<BUSINESS_PHONE_NUMBER_ID>/messages adresine, recipient alanı BSUID'ye ayarlı ve to alanı çıkarılmış olarak gönderin; ikisi de bulunduğunda to önceliklidir ve yanıt telefon numarasına gider. Bu durumda yanıtın contacts girdisi wa_id yerine input ve user_id taşır. One-tap, zero-tap ve copy code kimlik doğrulama şablonları hariç her mesaj türü çalışır; bunlar telefon numarası gerektirir. BSUID'ye yalnızca aynı Business Portfolio içindeki numaralar ulaşabilir. 131062 hatası, mesaj türünün BSUID alıcılarını kabul etmediği anlamına gelir.

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." }
}

Kullanıcıdan telefon numarasını nasıl istersiniz?

REQUEST_CONTACT_INFO düğmesiyle; bu düğme bir utility veya pazarlama şablonuna eklenir ya da request_contact_info türünde etkileşimli bir mesaj olarak gönderilir. Düğmeye dokunan kullanıcı numarasını konuşmaya paylaşır ve origin değeri contact_request, numara ise phones[].wa_id içinde olan bir contacts webhook'u gelir; elle paylaşılan bir kişi ise origin değeri other ve bir vCard ile gelir. Meta düğmeyi 2026 Temmuz başında kullanıma sundu ve etiketi özelleştirilemez.

Kişi defteri nedir?

Meta'nın her Business Portfolio için barındırdığı, entegrasyon çalışması gerektirmeyen bir depo: bir işletme telefon numarası bir kullanıcının telefon numarasıyla mesajlaştığında, aradığında ya da ondan çağrı aldığında, bu numara ve BSUID kaydedilir ve sonraki webhook'ları, kullanıcı adı olsun ya da olmasın, telefon numarasıyla doldurmak için kullanılır. Yalnızca başlatılmasından sonraki etkileşimler sayılır. Meta Business Suite'teki İşletme ayarları, İşletme bilgileri bölümünden kapatılabilir; bu işlem tuttuğu her şeyi siler. GET veya DELETE /<BUSINESS_PHONE_NUMBER_ID>/contact_book uç noktası, bir bsuid ile tek bir girdiyi kontrol eder veya siler.

Bir Coexistence entegrasyonu neyi değiştirmeli?

Yalnızca Coexistence numaralarının aldığı üç webhook'u işleme biçimi; bunlar da değişir. history'de her iş parçacığı wa_id, user_id ve username içeren bir context nesnesi kazanır; mesajlar ise from_user_id alanı kazanır. smb_message_echoes'te bir contacts dizisi eklenir; message_echoes[].to çıkarılabilir ve to_user_id BSUID'yi taşır. WhatsApp Business uygulamasında yapılan düzenlemeler ve iptaller de aynı biçimde gelir. smb_app_state_sync'te bir kişinin phone_number alanı çıkarılabilir; yanında user_id ve username bulunur. Yankıları ve içe aktarılan sohbetleri numaraya ek olarak user_id üzerinden de eşleştirin.

Kullanıcılar kullanıcı adı benimsemeden önce nasıl test edersiniz?

Meta'nın uygulama panelindeki test aracıyla: Use cases altında, Connect with customers through WhatsApp, Customize, Configuration yolunu izleyin; messages webhook'unun yanındaki Test bağlantısı uç noktanıza bir örnek gönderir. Dört senaryoda gelen mesajları ve durumları kapsar:

  • Kullanıcı adı olmayan bir kullanıcı: BSUID ve telefon numarası alanları, kullanıcı adı yok.
  • Numarası paylaşılamayan bir kullanıcı adı sahibi: kullanıcı adı ve BSUID, telefon numarası alanı yok.
  • Numarası paylaşılabilen bir kullanıcı adı sahibi: kullanıcı adı, BSUID ve telefon numarası.
  • Üst BSUID'lere kayıtlı bir portföy: portföyün kendi BSUID'sinin yanında bir üst BSUID.

easyCoexistence BSUID'leri nasıl ele alır?

Bunları Meta'nın gönderdiği gibi iletir. set_webhook_destination ile uç noktanıza yönlendirilen bir numara, messages ve smb_message_echoes webhook'larını doğrudan Meta'dan alır; user_id, from_user_id, to_user_id ve username dahil. Otomasyonlar veya yönlendirme açıkken easyCoexistence, Meta'nın gönderdiği değeri değiştirmeden iletir. Bir BSUID'ye yanıt vermek için kodunuz get_api_credentials kullanır; bu araç numaranın telefon numarası kimliğini, gönderim uç noktasını ve varsa kendi token'ınızı döndürür. send_message ve send_template araçları uluslararası biçimde telefon numarası alır.

Yaygın hatalar

  • Kişileri yalnızca wa_id üzerinden eşleştirmek. Numarayla 30 gündür temas olmayan bir kullanıcı adı sahibi yalnızca user_id ve from_user_id ile gelir; wa_id isteyen bir işleyici mesajı kaçırır.
  • BSUID'nin ülke ön ekini kırpmak. Meta bütün değeri ister, ülke kodu ve nokta dahil; herhangi bir bölümü değiştirilmiş bir istek başarısız olur.
  • user_id_update alanını beklemek. Meta'da böyle bir alan yok: BSUID değişiklikleri, user_changed_number veya user_changed_user_id türünde sistem mesajları olarak messages üzerinden gelir.
  • Coexistence yankılarını yalnızca to ile eşleştirmek. smb_message_echoes içinde to alanı çıkarılabilir; bu yüzden uygulamada yazılan bir yanıt to_user_id da eşleştirilmezse gözden kaçar.
Bunu EasyCoexistence'la yapmak

Her bağlantı 7/24 izlenir. Bağlantı başına aylık US$ 9'dan US$ 0,75'e kadar, bağlantı ekledikçe düşer; ilk 3 gün ücretsiz deneme.

Sık sorulan sorular

Kullanıcı adı olmayan kullanıcıların da BSUID'si var mı?

Evet. Meta, kullanıcının kullanıcı adı olup olmadığına bakmaksızın messages webhook'larında user_id alanını doldurur; bu yüzden çoğu kullanıcı hem telefon numarası hem de BSUID ile gelir.

Bir Coexistence numarası işletme kullanıcı adına sahip olabilir mi?

Evet. 29 Haziran 2026'dan itibaren bir işletme, Meta Business Suite, WhatsApp Manager, WhatsApp Business uygulaması veya Username API üzerinden bir kullanıcı adı benimseyebilir ya da değiştirebilir; bu, işletme numarasını gizlemez ve business_username_updates her durum değişikliğini bildirir.

BSUID'ler Business Portfolio'lar arasında çalışır mı?

Hayır. Bir BSUID tek bir portföye ve kullanıcıya aittir; başka bir portföydeki bir numara ona mesaj gönderemez. Meta'nın kaydettiği yönetilen işletmeler, kayıtlı portföyleri arasında çalışan, ülke kodundan sonra ENT bulunan üst BSUID'ler alır.

easyCoexistence bir WhatsApp numarası için ne kadar tutar?

Bağlantı başına aylık US$ 9'dan US$ 0,75'e kadar, sahip olduğunuz bağlantı sayısına göre düşer; ilk 3 gün ücretsiz deneme. Meta'nın kendi mesaj ücretleri, WhatsApp Business Hesabınızın ödeme yönteminde kalır.

Okumaya devam edin

Başlamaya hazır mısınız?

WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.

Ücretsiz denemeyi başlatın

Doğrulama tarihi