WhatsApp Profil Zenginleştirme için WA Lookup API Entegrasyonu

WA Lookup API kullanarak eşzamanlı WhatsApp profil ve avatar sorgularının nasıl uygulanacağını anlatan, geliştiricilere yönelik teknik bir rehber.

WA Lookup API, geliştiricilerin WhatsApp profil zenginleştirmeyi otomatikleştirmesini destekleyen eşzamanlı bir REST arayüzü sunar. Belirli bir hizmet türü (ws, ws_avatar veya ws_business) ve E.164 formatında bir telefon numarasıyla /api/v1/check uç noktasına bir POST isteği gönderdiğinizde API, hesap varlığı sinyallerini doğrudan HTTP yanıtı içinde anında döndürür. Bu sinyaller kayıt durumunu, avatar mevcudiyetini, avatar URL'lerini ve işletme hesabı göstergelerini içerir; bunlar CRM yönlendirmesi, hedef kitle segmentasyonu ve dahili karar destek iş akışları için girdi olarak kullanılabilir.

WA Lookup API'ye Giriş

İletişim kanallarını iş süreçlerine entegre ederken teknik ekiplerin, yönlendirme ve segmentasyon mantıklarını beslemek için doğru hesap varlığı sinyallerine ihtiyacı vardır. WA Lookup; WhatsApp kaydı, avatar mevcudiyeti ve Business hesap durumu için eşzamanlı tekli ve küçük toplu kontroller sunar. Tekli uç nokta bir tanımlayıcıyı kontrol eder, eşzamanlı çoklu uç nokta ise en fazla 100 tanımlayıcı kabul eder; her ikisi de verileri aynı HTTP yanıtında döndürür. Bu eşzamanlı mimari, asenkron webhook'lara, yoklama (polling) altyapısına veya toplu işlem kuyruklarına gerek kalmadan anında karar vermeyi destekler. Bu hesap varlığı sinyalinin sınırlarını anlamak kritik önem taşır. Kayıtlı sonucu, kontrolün yapıldığı andaki mevcut WhatsApp durum alanlarını bildirir. Canlı çevrimiçi durumu, mesaj geçmişini, kullanıcı onayını veya numaraya şu anda ulaşılıp ulaşılamayacağını bildirmez. Bunun yerine daha geniş bir iş akışına katkıda bulunarak ekiplerin kayıtları incelemesine ve iletişim önceliklerini platform varlığına göre belirlemesine yardımcı olur.

Hizmet Türlerini Anlamak

WA Lookup API, yeteneklerini tek bir eşzamanlı uç noktada toplar. Geliştiriciler, istek gövdesindeki service_type parametresini değiştirerek hangi profil sinyallerinin alınacağını ve hangi bakiye maliyetinin uygulanacağını kontrol eder. API üç farklı hizmet türünü destekler:

• WhatsApp Checker (ws): Temel hizmet türüdür. Kapsamı yalnızca gönderilen telefon numarasının WhatsApp'ta kayıtlı olup olmadığını doğrulamakla sınırlıdır. Temel bir platform kayıt sinyali sağlar.
• WhatsApp Avatar Checker (ws_avatar): Bu hizmet türü, temel kontrolü profil zenginleştirmeyle genişletir. WhatsApp kaydını kontrol etmenin yanı sıra avatar mevcudiyetini de kontrol eder ve bir avatar_url alanı döndürür. Kullanılabilir bir URL olmadığında URL alanı boştur.
• WhatsApp Business Checker (ws_business): Bu hizmet türü B2B iş akışları için tasarlanmıştır. Standart WhatsApp kaydını kontrol eder ve ek olarak hesabın WhatsApp Business kullanıp kullanmadığını belirleyerek özel bir işletme profili sinyali sağlar.

Uygun hizmet türünü seçerek teknik ürün yöneticileri, API çıktısını iş akışı gereksinimlerine tam olarak uyarlayabilir ve yalnızca kendi kullanım senaryoları için gerekli verileri talep edip kullandıklarından emin olabilir.

Teknik Uygulama

WA Lookup API entegrasyonu, katı bir JSON istek sözleşmesine ve biçimlendirme kurallarına uymayı gerektirir. Tüm etkileşimler POST /api/v1/check uç noktası üzerinden gerçekleşir. İsteğin kimliğini doğrulamak ve doğru biçimlendirmek için geliştiricilerin belirli başlıkları eklemesi gerekir: etkin API anahtarını içeren X-API-Key başlığı ve Content-Type: application/json başlığı. İsteğin JSON gövdesi tam olarak iki alan içermelidir:

1. service_type: "ws", "ws_avatar" veya "ws_business" değerlerinden birini alan bir dize.
2. identifier: Kesinlikle E.164 formatında gönderilen hedef telefon numarası.

E.164 formatı, telefon numaralarının küresel ölçekte tekil ve açık olmasını sağlayan uluslararası bir telefon numaralandırma planıdır. E.164 formatındaki bir numara artı işaretiyle (+) başlamalı, hemen ardından ülke kodu ve abone numarası gelmeli; boşluk, tire veya parantez içermemelidir (ör. +17253100591). E.164 formatının kullanılmaması kontrolün başarısız olmasına yol açar. API tamamen eşzamanlı olduğundan, kontrol yapılırken HTTP bağlantısı açık kalır ve sonuçlar doğrudan HTTP yanıtında iletilir.

API Yanıtlarını Yorumlama

WA Lookup API her kontrol yanıtında öngörülebilir bir alan kümesi döndürür; seçilen service_type değerine göre ek alanlar eklenir. Tamamlanmış bir WhatsApp kontrolünde döndürülen data; service_type, identifier ve registered alanlarını içerir. ws_avatar ayrıca avatar ve avatar_url alanlarını, ws_business ise business alanını içerir; dahili kayıt, işlem, durum ve faturalandırma alanları döndürülmez. service_type değeri ws olarak ayarlandığında sonuç, gönderildiği gibi geri döndürülen service_type ve identifier değerlerinin yanında yalnızca registered alanını içerir. service_type değeri ws_avatar olarak ayarlandığında yanıt şeması, bir avatar alanını (avatar ayarlanıp ayarlanmadığını gösteren bir boolean) ve bir avatar_url alanını içerecek şekilde genişler. Kullanılabilir bir URL olmadığında avatar_url boş bir dizedir. service_type değeri ws_business olarak ayarlandığında yanıt şemasına, kayıtlı numaranın bir WhatsApp Business hesabıyla ilişkili olup olmadığını gösteren boolean bir business alanı eklenir.

Panel ve Kullanım Yönetimi

API kullanımının yönetimi ve iş akışı girdilerinin izlenmesi platform paneli üzerinden yapılır. Panel, API anahtarı yönetimi için kapsamlı destek sunarak geliştiricilerin X-API-Key başlığı için gereken anahtarları güvenli şekilde oluşturmasına ve yenilemesine olanak tanır. Operasyonel gözetim için panel; bakiye takibi, kontrol geçmişini inceleme ve ürün düzeyinde raporlamaya erişim özellikleri içerir. Teknik ekipler son kontrolleri izleyebilir, bakiye harcamasını analiz edebilir ve kullanım alışkanlıklarını anlamak ve entegrasyonlarını optimize etmek için hesap etkinliğini görüntüleyebilir. Bakiyenizi ve kontrol geçmişinizi panelden inceleyin; güncel faturalandırma kuralları için fiyatlandırma sayfasına ve API dokümantasyonuna bakın.

SSS

WA Lookup API eşzamanlı mı çalışır?

Evet. Gerçek zamanlı uç noktalar eşzamanlıdır: sonuçlar, isteği başlatan HTTP isteğinin yanıtında döndürülür. Tek numaralı uç nokta bir tanımlayıcıyı kontrol eder; eşzamanlı çoklu uç nokta ise işler, geri çağrılar veya yoklama olmadan en fazla 100 tanımlayıcı kabul eder. Daha büyük listeler, bir dosya yükleyip sonucu daha sonra indirdiğiniz ayrı bir asenkron toplu ürün tarafından işlenir.

ws ve ws_avatar hizmet türleri arasındaki fark nedir?

ws hizmet türü yalnızca temel WhatsApp kayıt sinyalini döndürür. ws_avatar hizmet türü kayıt sinyalini döndürür ve ek olarak avatar mevcudiyetini kontrol ederek, kullanılabilir bir URL olmadığında boş olan bir avatar_url dizesi döndürür.

Telefon numaraları hangi formatta olmalıdır?

API'ye gönderilen tüm telefon numaraları E.164 standardına göre biçimlendirilmelidir. Bu, artı işaretinin (+) ardından ülke kodu ve abone numarasının gelmesini, boşluk veya özel karakter bulunmamasını gerektirir.