npm SDK — whatsapp-data-sdk

Düzenlemek

npm install whatsapp-data-sdk
# or
pnpm add whatsapp-data-sdk
# or
yarn add whatsapp-data-sdk

Yerel fetch fonksiyonunu kullanır — Node 18+, Bun, Deno ve tarayıcılarda çalışır. Axios veya polyfill gerektirmez.

Hızlı başlangıç

import { WhatsAppDataClient } from 'whatsapp-data-sdk'

const client = new WhatsAppDataClient({
  apiKey: process.env.WA_API_KEY!, // sent as x-rapidapi-key
})

const profile = await client.getProfile('59898297150')
console.log(profile.exists, profile.about, profile.profilePic)

Kimlik doğrulama ve taşıma

API anahtarınız her zaman x-rapidapi-key başlığında gönderilir. İsteklerin nereye yönlendirileceğini taşıma yöntemiyle seçin.

// RapidAPI marketplace (live + DB-only hosts)
const client = new WhatsAppDataClient({
  apiKey: process.env.RAPIDAPI_KEY!,
  transport: 'rapidapi',
})

baseUrl, cacheBaseUrl, rapidApiHost, rapidApiCacheHost aracılığıyla herhangi bir URL/ana bilgisayarı geçersiz kılabilirsiniz.

Önbelleğe öncelikli aramalar (para tasarrufu sağlar)

checkCached() işlevi önce ucuz önbellek/yalnızca veritabanı uç noktasını okur ve sayı henüz önbelleğe alınmadığında ücretli canlı kontrole geri döner.

// cacheFirst (default): DB first → live only on a miss
const r1 = await client.checkCached('59898297150')
console.log(r1._source) // 'cache' | 'live'

// cacheOnly: never spend on a live check
const r2 = await client.checkCached('59898297150', { mode: 'cacheOnly' })

// live: always fresh
const r3 = await client.checkCached('59898297150', { mode: 'live' })

Rapidapi taşıma protokolünde, önbellek okuma işlemi wp-data-db-only.p.rapidapi.com adresine, canlı yedekleme işlemi ise wp-data.p.rapidapi.com adresine yönlendirilir; bu da iki sunucu üzerinden maliyet tasarrufu sağlayan bir akıştır.

API referansı

Her yöntem, bir pazar yeri uç noktasıyla birebir eşleşir.

Profil ve resimler

await client.getProfile(number, options?)            // Get Profile Information
await client.getProfileNoPicture(number, options?)   // Get Profile Information (No profile pic)
await client.getLastPicture(number)                  // Get Last Saved Picture (JPEG bytes)
await client.getDeviceCount(number)                  // Device count
await client.getOsintInfo(number)                    // OSINT Info

getProfile seçenekleri arasında telegram, google, lookup, includeCarrier, base64, geminiFaceAnalysis, reverseImageSearch, fullAiReport, includeDeviceCount, onlyCheck, useCache, forceBypassCache ve daha fazlası yer almaktadır.

const pic = await client.getLastPicture('59898297150')
// pic.bytes: Uint8Array, pic.contentType: string
htmlImg.src = pic.toDataUri()

Telefon ihlalleri

await client.getPhoneBreaches(number, { limit, offset }) // Get Phone Breaches (no external key)
await client.getPhoneBreachesExternal(number, apiKey)     // Get Phone Breaches (your checkleaked.cc key)

Arama ve veritabanı

await client.search({ countryCode: 'UY', isBusiness: true, limit: 20 })   // Search
await client.searchGoogleMaps({ latitude: -34.9, longitude: -56.16, radius: 2000 }) // Search in Google Maps

// Bulk downloads return a Google Drive link to the full dataset (MEGA tier only)
const leaks = await client.getLeakedNumbersInfo()   // Leaked Numbers (500M database)
console.log(leaks.driveFolder.url)

const backup = await client.downloadEntireDatabase() // Download the Entire DB
console.log(backup.driveFolder.url)

Toplu çekler

await client.bulkCheck(numbers, { includeBusiness, noBanStatus }) // Bulk Check (live, max 50)
await client.bulkCheckDbBasic(numbers)                            // Basic Check (DB, max 1000)
await client.bulkCheckDbFull(numbers)                            // Full Check (DB, max 1000)

Telegram ve operatör

// Telegram (experimental)
await client.getTelegramProfile('59898297150')            // single
await client.getTelegramProfile(['num1', 'num2'])         // batch

// Carrier
await client.carrierLookup(number)              // Carrier Lookup
await client.carrierLookupAlt(number)           // Carrier Lookup Alternative (spam-report signals)
await client.carrierLookupAlt(number, { page: 2 }) // page through the reports (response has a `pagination` block)

"Bulunamadı" hatası çözülür, hata vermez.

Bir numaranın WhatsApp'ta kayıtlı olmaması normal bir sonuçtur, hata değildir, bu nedenle bu tür istekler çözümlenir (asla reddedilmez):

const p = await client.getProfile('14155552671')
if (!p.exists) console.log('not on WhatsApp')

Hata veren durumlar şunlardır: geçersiz numara (400), kimlik doğrulama hatası (401/403), hız sınırlaması (429), zaman aşımı, ağ hatası ve 5xx.

Hatalar

Tüm reddetme işlemleri WhatsAppDataError'ın bir alt sınıfıdır, bu nedenle tek bir hata yakalama bloğu her şeyi halleder.

import { AuthError, RateLimitError, TimeoutError, WhatsAppDataError } from 'whatsapp-data-sdk'

try {
  await client.getProfile('59898297150')
} catch (err) {
  if (err instanceof AuthError) {/* 401/403 — bad/unsubscribed key */}
  else if (err instanceof RateLimitError) {/* 429 — err.retryAfterMs */}
  else if (err instanceof TimeoutError) {/* request timed out */}
  else if (err instanceof WhatsAppDataError) {
    console.error(err.status, err.body)
  }
}

Yapılandırma

new WhatsAppDataClient({
  apiKey: '...',           // required
  transport: 'proxy',      // 'proxy' | 'rapidapi'
  timeoutMs: 60000,        // request timeout (bounds headers AND body read)
  retries: 2,              // retry 5xx / 429 / network / timeout (GET only) with backoff
  retryDelayMs: 500,       // exponential base; 429 honors Retry-After when longer
  baseUrl: '...',          // override live base URL
  cacheBaseUrl: '...',     // override cache/DB-only base URL
  rapidApiHost: '...',     // override live x-rapidapi-host
  rapidApiCacheHost: '...',// override cache x-rapidapi-host
  userAgent: '...',        // custom User-Agent
  fetch: globalThis.fetch, // inject a custom fetch (tests / polyfills)
})

Telefon numarası formatları

Sayıları herhangi bir biçimde iletebilirsiniz; SDK bunları normalleştirir ve aynı normalleştirmeyi yeniden kullanabilmeniz için yardımcı fonksiyonları dışa aktarır:

import { toDigits, toE164 } from 'whatsapp-data-sdk'
toDigits('+598 98 297 150') // '59898297150'  (path & live endpoints)
toE164('59898297150')       // '+59898297150' (bulk-DB endpoints; their validator requires it)
// both throw ValidationError on input with no digits

Talep üzerine seçenekler

Her yöntem, çağrı başına iptal ve ayarlama için sinyal, zaman aşımı milisaniyesi ve yeniden deneme sayısını da kabul eden, sondaki bir seçenekler nesnesini alır:

const controller = new AbortController()
const p = client.getProfile('59898297150', {
  telegram: true,
  signal: controller.signal, // cancel this specific request
  timeoutMs: 5000,           // override the client timeout for this call
})
controller.abort() // rejects with WhatsAppDataError

İlgili