WhatsApp numarası bağlama (API)

Kendi uygulamanızdan çalışma alanınıza bir WhatsApp numarası bağlamaya başlayın. Wbiztool yeni bir WhatsApp oturumu açar ve webhook URL'nize bir QR kodu veya login_method=phone ile 8 karakterli bir kod gönderir. Bunu telefonun sahibine gösterin; QR kodunu tarar veya kodu WhatsApp'a yazar ve numara mesaj göndermeye hazır olur. QR koduyla numarayı önceden bilmeniz gerekmez: Wbiztool taramadan sonra numarayı WhatsApp'tan okur ve webhook'unuza gönderir.

Kendi numaranızı elle mi bağlıyorsunuz? WhatsApp numaranızı bağlayın rehberini izleyin.

POST /api/v1/whatsapp-client/create/ birebir aynı bir takma addır: aynı kodu çalıştırır ve aynı yanıtları döndürür. İki yol da çalışmaya devam eder.

Bağlanma nasıl çalışır#

API çağrısı bağlantıyı yalnızca başlatır. QR kodu veya telefon kodu daha sonra webhook URL'nize gelir.

1. Bağlama API'sini çağırın

   webhook_url değerinizi ve login_method=phone ile birlikte whatsapp_number değerini gönderin. Daha önce eklediğiniz bir numarayı yeniden bağlamak için ayrıca onun whatsapp_client_id değerini gönderin. Yanıt size bir whatsapp_client_id verir. Bunu kaydedin.

2. QR kodunu veya telefon kodunu alın

   Varsayılan login_method=qr ile webhook'unuz, qr_image içinde QR görseliyle birlikte status=qr_generated alır. Wbiztool bir tarama beklerken QR kodu birkaç saniyede bir yeniden gönderilir; bu yüzden her zaman en sonuncusunu gösterin. Kişinin taramak için yaklaşık iki dakikası vardır.

   login_method=phone ile webhook'unuz, pairing_code içinde K5EWPGY5 gibi 8 karakterli bir kodla birlikte status=pairing_code alır. Bir kez gönderilir ve yaklaşık üç dakika geçerlidir.

   Görseli veya kodu telefonun sahibine gösterin. Zamanında kullanılmazsa veya WhatsApp kodu yenilemeyi isterse not_connected alırsınız; yenisini almak için API'yi tekrar çağırın.

3. Telefonu bağlayın

   Telefonda WhatsApp → Bağlı cihazlar → Cihaz bağla yolunu açın. QR kodunu tarayın veya Bunun yerine telefon numarasıyla bağlan (Link with phone number instead) seçeneğine dokunup 8 karakterli kodu yazın.

4. Sonucu alın

   Numara bağlandığında webhook'unuz whatsapp_number içinde bağlanan numarayla birlikte status=connected, kod zamanında taranmadıysa veya bağlantı başarısız olduysa status=not_connected alır. connected olayı, Bağlantı durumu Connected döndürmeden birkaç saniye önce gelebilir. Önce webhook'a yanıt verin, ardından bir dakikaya kadar birkaç saniyede bir Bağlantı durumu'nu sorgulayın. Webhook işleyicinizin içinden yalnızca bir kez kontrol etmeyin.

Hızlı örnek#

curl -X POST https://wbiztool.com/api/v1/whatsapp/connect/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET"
  }'

import requests

response = requests.post(
    "https://wbiztool.com/api/v1/whatsapp/connect/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
        "webhook_url": "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
    },
    timeout=30,
)
result = response.json()  # read the body even when the HTTP code is 400 or 403

if result.get("status") == 1:
    print("Waiting for QR code, whatsapp_client_id", result["whatsapp_client_id"])
else:
    print("Failed:", result.get("message"))

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/whatsapp/connect/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
    webhook_url: "https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400 or 403

if (result.status === 1) {
  console.log("Waiting for QR code, whatsapp_client_id", result.whatsapp_client_id);
} else {
  console.error("Failed:", result.message);
}

<?php
$payload = [
    'client_id'       => 12345,
    'api_key'         => 'YOUR_API_KEY',
    'webhook_url'     => 'https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET',
];

$ch = curl_init('https://wbiztool.com/api/v1/whatsapp/connect/');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? 0) === 1) {
    echo 'Waiting for QR code, whatsapp_client_id ' . $result['whatsapp_client_id'];
} else {
    echo 'Failed: ' . ($result['message'] ?? 'no response');
}

12345 ve YOUR_API_KEY değerlerini kendi değerlerinizle değiştirin. Bunları nerede bulacağınız için Kimlik doğrulama bölümüne bakın. Bunun yerine bir telefon kodu almak için "login_method": "phone" ve "whatsapp_number": "919876543210" ekleyin.

İstek parametreleri#

Resmi istemcileri kullanma#

Python istemcisi sizin için /api/v1/whatsapp-client/create/ çağrısını yapar. whatsapp_number ister; QR koduyla bu değer yok sayılır.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.create_whatsapp_client(
    whatsapp_number="919876543210",
    webhook_url="https://example.com/wbiztool/connect-events?token=LONG_RANDOM_SECRET",
)
print(result)

Python istemcisi, API HTTP 400 veya 403 döndürdüğünde requests.exceptions.HTTPError fırlatır; bu yüzden çağrıyı try/except içine alın.

Yanıt#

Bağlantı isteği oluşturulduğunda API HTTP 200 döndürür:

{
  "message": "Whatsapp Client Created",
  "whatsapp_client_id": 678,
  "login_method": "qr",
  "status": 1
}

"status": 1, numaranın bağlandığı değil, isteğin oluşturulduğu anlamına gelir. API'yi tekrar çağırmak numara biriktirmez:

• QR koduyla ve whatsapp_client_id olmadan, QR kodlarından biri taranana kadar aynı whatsapp_client_id değerini geri alırsınız.
• login_method=phone ile, daha önce eklenmiş ama bağlı olmayan bir numara mevcut whatsapp_client_id değerini geri alır.
• whatsapp_client_id ile o numara yeniden bağlanır.

İlk QR kodu taranana kadar numaranın henüz bir telefon numarası yoktur: Bağlı numaraları listeleme ve Bağlantı durumu bunun için boş bir numara döndürür.

Hatalar#

POST olmayan bir istek HTTP 200 ile boş bir nesne {} döndürür.

Webhook olayları#

Wbiztool her adımda webhook_url adresinize bir POST gönderir. Gövde JSON değil, form kodludur (application/x-www-form-urlencoded).

QR kodu hazır (tarama beklenirken birkaç saniyede bir, çoğu zaman aynı URL ile yeniden gönderilir):

status=qr_generated&whatsapp_client_id=678&qr_image=...

Telefon kodu hazır (login_method=phone ile, bir kez gönderilir):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Numara bağlandı, WhatsApp'ın bildirdiği şekilde oturum açan numarayla birlikte:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Bağlantı başarısız, örneğin QR kodu taranmadığı veya telefon kodu zamanında girilmediği için:

status=not_connected&whatsapp_client_id=678

URL'niz herkese açık olarak erişilebilir olmalı ve birkaç saniye içinde yanıt vermelidir. Wbiztool yanıtınız için en fazla 10 saniye bekler; sunucunuz yavaşsa veya erişilemiyorsa o olay kaybolur ama bağlantı denemesi devam eder. Her HTTP durum kodu kabul edilir. Başarısız teslimatlar yeniden denenmez ve numaranın bağlantısı daha sonra kesilirse hiçbir şey gönderilmez. Bir numarayı bağlandıktan sonra takip etmek için Bağlantı durumu endpoint'ini sorgulayın.

Webhook yerine sorgulama#

Sunucunuz webhook alamıyorsa, QR kodunu almak için yine de webhook'a ihtiyacınız vardır, ancak sonuç için ona güvenmek zorunda değilsiniz. QR kodu tarandıktan sonra, Connected döndürene kadar birkaç saniyede bir whatsapp_client_id ile Bağlantı durumu endpoint'ini çağırın. Hesapları listeleme aynı bilgiyi tüm numaralarınız için gösterir.

İpuçları#

• Yinelenen olayları ele alın: bir olayın iki kez teslim edilme ihtimaline karşı işleyicinizin birden fazla kez çalıştırılmasının güvenli olmasını sağlayın.
• En yeni QR kodunu gösterin: her yeni qr_generated olayı geldiğinde görseli değiştirin ve https URL'sine önbelleği atlatan bir sorgu ekleyin. Eski kodlar çalışmaz.
• Yaklaşık iki dakika içinde tarayın: bundan sonra not_connected alırsınız. Yeni bir kod için API'yi tekrar çağırın.
• QR taramasından sonra numarayı kontrol edin: connected olayındaki whatsapp_number gerçekten bağlanan numaradır ve beklediğinizden farklı olabilir.
• Telefon kodunu yaklaşık üç dakika içinde girin: her deneme bir kod verir. Süresi dolarsa not_connected alırsınız; API'yi tekrar çağırın.
• 10 dakika sonra QR kodu veya telefon kodu gelmedi mi? İsteğin süresi doldu. API'yi tekrar çağırın.
• Panelden bağlanmak daha basittir: kendi numaranızı bağlıyorsanız WhatsApp ayarları sayfasını kullanın ve kodu orada tarayın.