npm SDK — whatsapp-data-sdk

Cài đặt

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

Sử dụng hàm `fetch` gốc — hoạt động trên Node 18+, Bun, Deno và trình duyệt. Không cần axios, không cần polyfill.

Khởi động nhanh

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)

Xác thực & vận chuyển

Khóa API của bạn luôn được gửi trong tiêu đề x-rapidapi-key. Chọn nơi các yêu cầu được gửi đến bằng tham số transport.

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

Bạn có thể ghi đè bất kỳ URL/máy chủ nào thông qua baseUrl, cacheBaseUrl, rapidApiHost, rapidApiCacheHost.

Tra cứu ưu tiên bộ nhớ cache (tiết kiệm chi phí)

Hàm checkCached() sẽ đọc dữ liệu từ bộ nhớ đệm/điểm cuối chỉ dành cho cơ sở dữ liệu trước, và chỉ chuyển sang phương thức kiểm tra trực tiếp có trả phí khi số điện thoại chưa được lưu vào bộ nhớ đệm.

// 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' })

Trên giao thức vận chuyển rapidapi, việc đọc dữ liệu từ bộ nhớ cache được định tuyến đến wp-data-db-only.p.rapidapi.com và việc chuyển hướng dự phòng trực tiếp đến wp-data.p.rapidapi.com — tạo nên luồng tiết kiệm chi phí với hai máy chủ.

Tài liệu tham khảo API

Mỗi phương thức đều tương ứng 1:1 với một điểm cuối trên thị trường.

Hồ sơ & hình ảnh

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

Các tùy chọn getProfile bao gồm telegram, google, lookup, includeCarrier, base64, geminiFaceAnalysis, reverseImageSearch, fullAiReport, includeDeviceCount, onlyCheck, useCache, forceBypassCache, và nhiều tùy chọn khác.

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

rò rỉ điện thoại

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

Tìm kiếm & cơ sở dữ liệu

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)

Kiểm tra hàng loạt

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)

Điện tín & nhà mạng

// 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)

"Không tìm thấy" sẽ được giải quyết — nó không báo lỗi.

Việc số điện thoại không có trên WhatsApp là điều bình thường, không phải lỗi, vì vậy chúng sẽ được xử lý (chúng không bao giờ bị từ chối):

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

Những lỗi xảy ra: số không hợp lệ (400), lỗi xác thực (401/403), giới hạn số lượng truy cập (429), hết thời gian chờ, lỗi mạng và 5xx.

Lỗi

Tất cả các lỗi bị từ chối đều là một lớp con của WhatsAppDataError, vì vậy chỉ cần một khối catch duy nhất là có thể xử lý mọi thứ.

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)
  }
}

Cấu hình

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)
})

Định dạng số điện thoại

Bạn có thể truyền các số ở bất kỳ định dạng nào — SDK sẽ chuẩn hóa chúng và xuất các hàm hỗ trợ để bạn có thể sử dụng lại cùng một phương pháp chuẩn hóa:

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

Tùy chọn theo yêu cầu

Mỗi phương thức đều nhận một đối tượng tùy chọn theo sau, đối tượng này cũng chấp nhận tín hiệu, thời gian chờ (timeoutMs) và số lần thử lại — để hủy và điều chỉnh cho từng lần gọi:

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

Có liên quan