Sambung nombor WhatsApp (API)

Mula menyambungkan nombor WhatsApp ke ruang kerja anda dari aplikasi anda sendiri. Wbiztool membuka sesi WhatsApp baharu dan menghantar kod QR, atau dengan login_method=phone kod 8 aksara, ke URL webhook anda. Tunjukkan kod itu kepada pemilik telefon, mereka mengimbas kod QR atau menaip kod itu dalam WhatsApp, dan nombor itu sedia untuk menghantar mesej. Dengan kod QR, anda tidak perlu tahu nombornya terlebih dahulu: Wbiztool membacanya daripada WhatsApp selepas imbasan dan menghantarnya ke webhook anda.

Memautkan nombor anda sendiri secara manual? Ikuti Sambung nombor WhatsApp anda.

POST /api/v1/whatsapp-client/create/ ialah alias yang sama: ia menjalankan kod yang sama dan memulangkan respons yang sama. Kedua-dua laluan terus berfungsi.

Cara penyambungan berfungsi#

Panggilan API hanya memulakan sambungan. Kod QR atau kod telefon tiba kemudian, di URL webhook anda.

1. Panggil API sambung

   Hantar webhook_url anda, serta whatsapp_number dengan login_method=phone. Untuk menyambung semula nombor yang pernah anda tambah, hantar juga whatsapp_client_idnya. Respons memberikan anda whatsapp_client_id. Simpan ID ini.

2. Terima kod QR atau kod telefon

   Dengan login_method=qr lalai, webhook anda menerima status=qr_generated dengan imej QR dalam qr_image. Kod QR dihantar semula setiap beberapa saat semasa Wbiztool menunggu imbasan, jadi sentiasa tunjukkan yang terkini. Orang itu mempunyai kira-kira dua minit untuk mengimbas.

   Dengan login_method=phone, webhook anda menerima status=pairing_code dengan kod 8 aksara dalam pairing_code, seperti K5EWPGY5. Kod ini dihantar sekali dan sah selama kira-kira tiga minit.

   Tunjukkan imej atau kod itu kepada pemilik telefon. Jika ia tidak digunakan dalam masa yang ditetapkan, atau WhatsApp meminta kod dimuat semula, anda akan menerima not_connected; panggil API sekali lagi untuk mendapatkan kod baharu.

3. Pautkan telefon

   Di telefon, buka WhatsApp → Linked devices (Peranti dipautkan) → Link a device (Pautkan peranti). Imbas kod QR, atau ketik Link with phone number instead (Pautkan dengan nombor telefon) dan taip kod 8 aksara itu.

4. Dapatkan hasilnya

   Webhook anda menerima status=connected dengan nombor yang dipautkan dalam whatsapp_number apabila nombor itu dipautkan, atau status=not_connected jika kod tidak diimbas dalam masa yang ditetapkan atau sambungan gagal. Peristiwa connected boleh tiba beberapa saat sebelum Status sambungan memulangkan Connected. Balas webhook dahulu, kemudian tinjau Status sambungan setiap beberapa saat sehingga satu minit. Jangan menyemaknya sekali sahaja dari dalam pengendali webhook anda.

Contoh ringkas#

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

Gantikan 12345 dan YOUR_API_KEY dengan nilai anda sendiri. Lihat Pengesahan identiti untuk mengetahui di mana nilai ini boleh didapati. Untuk mendapatkan kod telefon, tambah "login_method": "phone" dan "whatsapp_number": "919876543210".

Parameter permintaan#

Menggunakan klien rasmi#

Klien Python memanggil /api/v1/whatsapp-client/create/ untuk anda. Ia meminta whatsapp_number; dengan kod QR, nilai itu diabaikan.

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)

Klien Python menimbulkan requests.exceptions.HTTPError apabila API memulangkan HTTP 400 atau 403, jadi balut panggilan dalam try/except.

Respons#

Apabila permintaan sambungan dicipta, API memulangkan HTTP 200:

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

"status": 1 bermaksud permintaan telah dicipta, bukan bermaksud nombor itu telah disambungkan. Memanggil API sekali lagi tidak menimbunkan nombor:

• Dengan kod QR dan tanpa whatsapp_client_id, anda mendapat whatsapp_client_id yang sama sehingga salah satu kod QR-nya diimbas.
• Dengan login_method=phone, nombor yang pernah ditambah tetapi tidak disambungkan mendapat semula whatsapp_client_id sedia adanya.
• Dengan whatsapp_client_id, nombor itu disambungkan semula.

Sehingga kod QR pertamanya diimbas, nombor itu belum mempunyai nombor telefon: Senarai nombor disambungkan dan Status sambungan memulangkan nombor kosong untuknya.

Ralat#

Permintaan yang bukan POST memulangkan objek kosong {} dengan HTTP 200.

Peristiwa webhook#

Wbiztool menghantar POST ke webhook_url anda pada setiap langkah. Badannya dikodkan sebagai borang (application/x-www-form-urlencoded), bukan JSON.

Kod QR sedia (dihantar semula setiap beberapa saat semasa menunggu imbasan, selalunya dengan URL yang sama):

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

Kod telefon sedia (dengan login_method=phone, dihantar sekali):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Nombor disambungkan, dengan nombor yang log masuk, seperti yang dilaporkan oleh WhatsApp:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Sambungan gagal, contohnya kerana kod QR tidak diimbas atau kod telefon tidak dimasukkan dalam masa yang ditetapkan:

status=not_connected&whatsapp_client_id=678

URL anda mesti boleh dicapai secara awam dan sepatutnya menjawab dalam beberapa saat. Wbiztool menunggu sehingga 10 saat untuk balasan anda; jika pelayan anda perlahan atau tidak dapat dicapai, peristiwa itu hilang tetapi percubaan sambungan diteruskan. Sebarang kod status HTTP diterima. Penghantaran yang gagal tidak dicuba semula, dan tiada apa-apa dihantar jika nombor itu terputus sambungan kemudian. Untuk memantau nombor selepas ia disambungkan, tinjau Status sambungan.

Meninjau dan bukannya menggunakan webhook#

Jika pelayan anda tidak dapat menerima webhook, anda masih memerlukan webhook untuk mendapatkan kod QR, tetapi anda tidak perlu bergantung padanya untuk hasilnya. Selepas kod QR diimbas, panggil Status sambungan dengan whatsapp_client_id setiap beberapa saat sehingga ia memulangkan Connected. Senarai akaun menunjukkan perkara yang sama untuk semua nombor anda.

Petua#

• Kendalikan peristiwa pendua: pastikan pengendali anda selamat dijalankan lebih daripada sekali, sekiranya sesuatu peristiwa dihantar dua kali.
• Tunjukkan kod QR terbaharu: gantikan imej setiap kali peristiwa qr_generated baharu tiba, dengan menambah pertanyaan pemintas cache pada URL https. Kod yang lebih lama berhenti berfungsi.
• Imbas dalam masa kira-kira dua minit: selepas itu anda akan menerima not_connected. Panggil API sekali lagi untuk kod baharu.
• Semak nombor selepas imbasan QR: whatsapp_number dalam peristiwa connected ialah nombor yang benar-benar dipautkan, yang mungkin berbeza daripada yang anda jangkakan.
• Masukkan kod telefon dalam masa kira-kira tiga minit: setiap percubaan memberikan satu kod. Jika ia tamat tempoh, anda akan menerima not_connected; panggil API sekali lagi.
• Tiada kod QR atau kod telefon selepas 10 minit? Permintaan telah tamat tempoh. Panggil API sekali lagi.
• Menyambung dari papan pemuka lebih mudah apabila anda memautkan nombor anda sendiri. Gunakan tetapan WhatsApp dan imbas kod di sana.