Hubungkan nomor WhatsApp (API)

Mulai hubungkan nomor WhatsApp ke workspace Anda dari aplikasi Anda sendiri. Wbiztool membuka sesi WhatsApp baru dan mengirim kode QR, atau dengan login_method=phone sebuah kode 8 karakter, ke URL webhook Anda. Tampilkan kode tersebut kepada pemilik ponsel, lalu mereka memindai kode QR atau mengetik kode di WhatsApp, dan nomor tersebut siap mengirim pesan. Dengan kode QR, Anda tidak perlu mengetahui nomornya terlebih dahulu: Wbiztool membacanya dari WhatsApp setelah pemindaian dan mengirimkannya ke webhook Anda.

Ingin menautkan nomor Anda sendiri secara manual? Ikuti Hubungkan nomor WhatsApp Anda.

POST /api/v1/whatsapp-client/create/ adalah alias yang identik: menjalankan kode yang sama dan mengembalikan respons yang sama. Kedua path tetap berfungsi.

Cara kerja koneksi#

Panggilan API hanya memulai koneksi. Kode QR atau kode telepon tiba kemudian, di URL webhook Anda.

1. Panggil API connect

   Kirim webhook_url Anda, ditambah whatsapp_number dengan login_method=phone. Untuk menghubungkan kembali nomor yang sudah pernah Anda tambahkan, kirim juga whatsapp_client_id-nya. Respons memberi Anda whatsapp_client_id. Simpan ID tersebut.

2. Terima kode QR atau kode telepon

   Dengan login_method=qr default, webhook Anda menerima status=qr_generated dengan gambar QR di qr_image. Kode QR dikirim ulang setiap beberapa detik selama Wbiztool menunggu pemindaian, jadi selalu tampilkan yang terbaru. Orang tersebut memiliki waktu sekitar dua menit untuk memindai.

   Dengan login_method=phone, webhook Anda menerima status=pairing_code dengan kode 8 karakter di pairing_code, misalnya K5EWPGY5. Kode ini dikirim sekali dan berlaku sekitar tiga menit.

   Tampilkan gambar atau kode tersebut kepada pemilik ponsel. Jika tidak digunakan tepat waktu, atau WhatsApp meminta memuat ulang kode, Anda menerima not_connected; panggil API lagi untuk mendapatkan kode baru.

3. Tautkan ponsel

   Di ponsel, buka WhatsApp → Linked devices (Perangkat tertaut) → Link a device (Tautkan perangkat). Pindai kode QR, atau ketuk Link with phone number instead (Tautkan dengan nomor telepon saja) lalu ketik kode 8 karakter.

4. Dapatkan hasilnya

   Webhook Anda menerima status=connected dengan nomor yang tertaut di whatsapp_number saat nomor berhasil ditautkan, atau status=not_connected jika kode tidak dipindai tepat waktu atau koneksi gagal. Event connected bisa tiba beberapa detik sebelum Status koneksi mengembalikan Connected. Balas webhook terlebih dahulu, lalu lakukan polling ke Status koneksi setiap beberapa detik hingga satu menit. Jangan memeriksanya sekali saja dari dalam handler webhook Anda.

Contoh singkat#

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

Ganti 12345 dan YOUR_API_KEY dengan nilai Anda sendiri. Lihat Autentikasi untuk mengetahui di mana menemukannya. Untuk mendapatkan kode telepon, tambahkan "login_method": "phone" dan "whatsapp_number": "919876543210".

Parameter request#

Menggunakan klien resmi#

Klien Python memanggil /api/v1/whatsapp-client/create/ untuk Anda. Klien ini meminta whatsapp_number; dengan kode QR, nilainya 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 memunculkan requests.exceptions.HTTPError ketika API mengembalikan HTTP 400 atau 403, jadi bungkus panggilan dengan try/except.

Respons#

Saat request koneksi dibuat, API mengembalikan HTTP 200:

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

"status": 1 berarti request sudah dibuat, belum berarti nomor sudah terhubung. Memanggil API lagi tidak menumpuk nomor:

• Dengan kode QR dan tanpa whatsapp_client_id, Anda mendapatkan whatsapp_client_id yang sama sampai salah satu kode QR-nya dipindai.
• Dengan login_method=phone, nomor yang sudah pernah ditambahkan tetapi tidak terhubung mendapatkan kembali whatsapp_client_id yang sudah ada.
• Dengan whatsapp_client_id, nomor tersebut dihubungkan kembali.

Sampai kode QR pertamanya dipindai, nomor tersebut belum memiliki nomor telepon: Daftar nomor terhubung dan Status koneksi mengembalikan nomor kosong untuknya.

Error#

Request yang bukan POST mengembalikan objek kosong {} dengan HTTP 200.

Event webhook#

Wbiztool mengirim POST ke webhook_url Anda di setiap langkah. Body-nya dienkode sebagai formulir (application/x-www-form-urlencoded), bukan JSON.

Kode QR siap (dikirim ulang setiap beberapa detik selama menunggu pemindaian, sering kali dengan URL yang sama):

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

Kode telepon siap (dengan login_method=phone, dikirim sekali):

status=pairing_code&whatsapp_client_id=678&pairing_code=K5EWPGY5

Nomor terhubung, dengan nomor yang login, seperti yang dilaporkan WhatsApp:

status=connected&whatsapp_client_id=678&whatsapp_number=919876543210

Koneksi gagal, misalnya karena kode QR tidak dipindai atau kode telepon tidak dimasukkan tepat waktu:

status=not_connected&whatsapp_client_id=678

URL Anda harus dapat dijangkau secara publik dan sebaiknya merespons dalam beberapa detik. Wbiztool menunggu balasan Anda hingga 10 detik; jika server Anda lambat atau tidak dapat dijangkau, event tersebut hilang tetapi percobaan koneksi tetap berjalan. Kode status HTTP apa pun diterima. Pengiriman yang gagal tidak dicoba ulang, dan tidak ada yang dikirim jika nomor terputus di kemudian hari. Untuk memantau nomor setelah terhubung, lakukan polling ke Status koneksi.

Polling sebagai ganti webhook#

Jika server Anda tidak dapat menerima webhook, Anda tetap memerlukan webhook untuk mendapatkan kode QR, tetapi Anda tidak harus mengandalkannya untuk hasilnya. Setelah kode QR dipindai, panggil Status koneksi dengan whatsapp_client_id setiap beberapa detik sampai mengembalikan Connected. Daftar akun menampilkan hal yang sama untuk semua nomor Anda.

Tips#

• Tangani event duplikat: pastikan handler Anda aman dijalankan lebih dari sekali, untuk berjaga-jaga jika sebuah event terkirim dua kali.
• Tampilkan kode QR terbaru: ganti gambar setiap kali event qr_generated baru tiba, dengan menambahkan query cache-busting ke URL https. Kode yang lebih lama berhenti berfungsi.
• Pindai dalam sekitar dua menit: setelah itu Anda menerima not_connected. Panggil API lagi untuk kode baru.
• Periksa nomor setelah pemindaian QR: whatsapp_number di event connected adalah nomor yang benar-benar ditautkan, yang mungkin berbeda dari yang Anda harapkan.
• Masukkan kode telepon dalam sekitar tiga menit: setiap percobaan memberikan satu kode. Jika kedaluwarsa, Anda menerima not_connected; panggil API lagi.
• Tidak ada kode QR atau kode telepon setelah 10 menit? Request sudah kedaluwarsa. Panggil API lagi.
• Menghubungkan dari dashboard lebih sederhana jika Anda menautkan nomor Anda sendiri. Gunakan WhatsApp settings dan pindai kode di sana.