Bộ SDK Python — whatsapp-data-sdk

Cài đặt

pip install whatsapp-data-sdk

Hỗ trợ Python 3.8-3.13. Đi kèm với dấu hiệu py.typed để hỗ trợ đầy đủ trình kiểm tra kiểu (mypy, pyright).

Khởi động nhanh

from whatsapp_data_sdk import WhatsAppDataClient

client = WhatsAppDataClient(api_key="YOUR_KEY")  # sent as x-rapidapi-key

profile = client.get_profile("59898297150")
print(profile.get("exists"), profile.get("about"), profile.get("profilePic"))

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

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

client = WhatsAppDataClient(api_key="RAPIDAPI_KEY", transport="rapidapi")

Ghi đè URL/máy chủ thông qua base_url, cache_base_url, rapidapi_host, rapidapi_cache_host.

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

Hàm check_cached() sẽ đọc bộ nhớ đệm giá rẻ / điểm cuối chỉ dành cho cơ sở dữ liệu trước và chỉ chuyển sang kiểm tra trực tiếp có trả phí khi thực sự không tìm thấy kết quả.

r1 = client.check_cached("59898297150")                  # cacheFirst (default)
print(r1["_source"])                                     # "cache" | "live"
r2 = client.check_cached("59898297150", mode="cacheOnly")  # never a live call
r3 = client.check_cached("59898297150", mode="live")       # always fresh

Một bản ghi được lưu trong bộ nhớ cache có độ tin cậy cao nhưng không có trên WhatsApp được tính là một lượt truy cập thành công (không cần kiểm tra lại trực tiếp một cách lãng phí); chỉ khi thực sự không tìm thấy thông tin trong cơ sở dữ liệu thì mới được cập nhật trực tiếp.

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 marketplace - phạm vi phủ sóng tương tự như npm SDK, đặt tên theo kiểu snake_case.

# Profile & pictures
client.get_profile(number, telegram=True, include_carrier=True)  # Get Profile Information
client.get_profile_no_picture(number)                            # (No profile pic)
pic = client.get_last_picture(number)                            # JPEG bytes -> pic.content, pic.to_data_uri()
client.get_device_count(number)                                  # Device count
client.get_osint_info(number)                                    # OSINT Info

# Breaches
client.get_phone_breaches(number, limit=50)                      # built-in (no external key)
client.get_phone_breaches_external(number, api_key="...")        # your checkleaked.cc key

# Search & database
client.search(country_code="UY", is_business=True, limit=20)     # Search
client.search_google_maps(latitude=-34.9, longitude=-56.16, radius=2000)  # Search in Google Maps
client.get_leaked_numbers_info()                                 # Leaked Numbers (500M) -> Drive link (MEGA tier)
client.download_entire_database()                                # Download the Entire DB -> Drive link (MEGA tier)

# Bulk
client.bulk_check(numbers)                                       # live (max 50)
client.bulk_check_db_basic(numbers)                              # DB basic (max 1000)
client.bulk_check_db_full(numbers)                                # DB full (max 1000)

# Telegram / carrier
client.get_telegram_profile("59898297150")                      # experimental
client.get_telegram_profile(["num1", "num2"])
client.carrier_lookup(number)                                    # Carrier Lookup
client.carrier_lookup_alt(number, page=2)                        # Carrier Lookup Alternative

"Không tìm thấy" được giải quyết — nó không gây ra lỗi.

Việc số điện thoại không có trong WhatsApp là kết quả bình thường, vì vậy vấn đề này sẽ được giải quyết (không bao giờ gây ra lỗi):

p = client.get_profile("14155552671")
if not p.get("exists"):
    print("not on WhatsApp")

Nguyên nhân gây ra lỗi: số không hợp lệ (400), xác thực (401/403), giới hạn tỷ lệ (429), hết thời gian chờ, mạng, 5xx.

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

Mỗi phương thức đều chấp nhận thời gian chờ (giây) và số lần thử lại:

client.get_profile("59898297150", timeout=5, retries=0)

Lỗi

Mọi lỗi đều dẫn đến một lớp con của WhatsAppDataError.

from whatsapp_data_sdk import AuthError, RateLimitError, WhatsAppDataError

try:
    client.get_profile("59898297150")
except AuthError:
    ...  # 401/403
except RateLimitError as e:
    print(e.retry_after_ms)
except WhatsAppDataError as e:
    print(e.status, e.body)

Các yêu cầu POST (bulk_check, bulk_check_db_*) không được tự động thử lại để tránh việc sử dụng hạn mức hai lần.

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

Mọi định dạng đều hoạt động — SDK sẽ chuẩn hóa; các hàm hỗ trợ được xuất ra:

from whatsapp_data_sdk import to_digits, to_e164
to_digits("+598 98 297 150")  # "59898297150"  (path & live endpoints)
to_e164("59898297150")        # "+59898297150" (bulk-DB endpoints require it)

Có liên quan