API v2

API v2 ialah REST API WbizTool yang baharu: satu kunci bagi setiap aplikasi dengan akses yang diperlukannya sahaja, URL gaya sumber, kod status HTTP yang sebenar, webhook JSON bertandatangan dan cubaan semula yang selamat. Halaman ini menerangkan perkara yang sama bagi setiap permintaan. Halaman sumber menerangkan setiap endpoint.

URL asas#

https://wbiztool.com/api/v2

Laluan tidak mempunyai garis miring di hujung (/api/v2/messages), tetapi garis miring di hujung juga diterima. Alamat yang tidak wujud menjawab 404 dengan kod not_found.

Contoh ringkas#

Semak kunci anda dengan GET /me. Ia berfungsi dengan mana-mana skop dan tidak menghantar apa-apa:

curl https://wbiztool.com/api/v2/me \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

import os
import requests

response = requests.get(
    "https://wbiztool.com/api/v2/me",
    headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/me", {
  headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
console.log(response.status, await response.json());

<?php
$ch = curl_init('https://wbiztool.com/api/v2/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$body = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n";
print_r($body);
curl_close($ch);

{
  "workspace": { "id": 5012, "name": "Acme Bakery" },
  "key": {
    "id": 7,
    "name": "Order system",
    "mode": "live",
    "scopes": ["messages:send", "messages:read"],
    "limited_to_numbers": false,
    "number_ids": [],
    "expires_at": null
  },
  "plan": { "name": "Starter" },
  "limits": {
    "requests_per_minute": 60,
    "requests_per_day": 10000,
    "messages_per_number_per_day": 1000,
    "messages_remaining": null
  }
}

messages_remaining ialah null apabila pelan menghantar mesej tanpa had. plan ialah null apabila ruang kerja tiada pelan aktif.

Kunci#

Hantar kunci anda dalam pengepala Authorization pada setiap permintaan:

Authorization: Bearer wbz_live_…

Tiada client_id: kunci itu sendiri menamakan ruang kerjanya. Kunci v2 bermula dengan wbz_live_ atau wbz_test_, diikuti 38 huruf dan digit. Kunci v1 tidak berfungsi pada v2 (ia mendapat v1_key_on_v2), dan kunci v2 tidak berfungsi pada v1.

Cipta kunci#

Pemilik mencipta kunci di Tetapan → Kunci API, dalam kad Kunci API v2: klik Cipta kunci v2, kemudian pilih:

• Nama: aplikasi yang akan menggunakannya, sehingga 50 aksara.
• Jenis kunci: Langsung menghantar mesej sebenar; Ujian menyemak semuanya dan tidak menghantar apa-apa (lihat Mod ujian).
• Apa yang boleh dilakukan: skop, atau Semua.
• Nombor yang boleh digunakan: semua nombor, termasuk yang ditambah kemudian, atau sebahagian sahaja (lihat Kunci yang dihadkan kepada sebahagian nombor).
• Tamat tempoh: tidak pernah, atau dalam 30 hari, 90 hari atau 1 tahun.

Kunci dipaparkan sekali sahaja. Salinnya serta-merta dan simpan pada pelayan anda, contohnya dalam pemboleh ubah persekitaran. WbizTool hanya menyimpan cincangan kunci dan empat aksara terakhirnya, jadi kunci yang hilang tidak boleh dipaparkan semula: tarik baliknya dan cipta yang baharu.

Satu ruang kerja boleh mempunyai sehingga 10 kunci v2 yang belum ditarik balik. Kad ini menunjukkan empat aksara terakhir setiap kunci, skop, nombor, tarikh tamat tempoh, serta bila dan dari alamat IP mana ia kali terakhir digunakan. Tarik balik menghentikan kunci serta-merta, bersama endpoint webhook yang diciptanya. Kunci yang melepasi tarikh tamat tempohnya mendapat api_key_expired.

Skop#

Setiap kunci hanya boleh melakukan apa yang dibenarkan oleh skopnya. Permintaan di luar skop itu menjawab 403 dengan missing_scope, dan required_scope dalam ralat menyatakan skop yang diperlukan.

GET /me tidak memerlukan skop tertentu. Menghantar kepada kenalan yang disimpan dengan to.contact_id hanya memerlukan messages:send.

Kunci yang dihadkan kepada sebahagian nombor#

Kunci yang dihadkan kepada sebahagian nombor hanya berfungsi dengan nombor tersebut:

• Ia hanya menghantar dari nombor itu, dan hanya menyenaraikan, membaca dan membatalkan mesej nombor itu. Nombor lain dalam from mendapat number_not_allowed.
• GET /numbers hanya menyenaraikan nombor itu. Ia boleh menyambungkannya semula tetapi tidak boleh menambah nombor baharu.
• Ia hanya melihat dan mengubah peringatan yang dihantar dari nombor itu, dan peringatan baharu mesti menamakan salah satu daripadanya sebagai from.
• Ia langsung tidak boleh mengurus endpoint webhook, kerana endpoint menerima peristiwa seluruh ruang kerja.

GET /me menunjukkan limited_to_numbers dan number_ids yang boleh digunakan oleh kunci.

Permintaan#

• JSON masuk dan keluar. Hantar badan sebagai Content-Type: application/json. Satu-satunya pengecualian ialah memuat naik fail, yang menggunakan multipart/form-data. Setiap respons ialah JSON, termasuk ralat.
• Nama medan menggunakan snake_case, dan medan yang tidak dikenali ditolak: salah taip seperti txt menjawab validation_failed dan bukannya diabaikan.
• Nombor telefon dalam format antarabangsa dengan + (E.164), contohnya +919876543210. Ruang dan sengkang dibenarkan; nombor tanpa + ditolak dengan invalid_phone.
• Masa dalam ISO 8601 dengan ofset, contohnya 2026-10-20T09:30:00+05:30 atau 2026-10-20T04:00:00Z. Masa tanpa ofset ditolak dengan invalid_datetime. Masa dalam respons adalah dalam UTC dan berakhir dengan Z, kecuali next_run_at peringatan, yang menggunakan zon waktu peringatan itu.
• ID ialah integer, seperti id nombor (from semasa anda menghantar) atau id mesej.
• Kod status bermaksud seperti yang dinyatakan: 200 OK, 201 dicipta, 202 diterima (dalam baris gilir), 400 permintaan salah, 401 kunci salah, 402 tiada mesej berbaki, 403 tidak dibenarkan, 404 tidak ditemui, 409 konflik, 413 terlalu besar, 415 jenis kandungan salah, 422 nilai tidak boleh digunakan, 429 terlalu banyak permintaan, 5xx masalah di pihak kami.

Respons membawa Cache-Control: no-store.

Ralat#

Setiap ralat mempunyai bentuk yang sama:

{
  "error": {
    "code": "invalid_phone",
    "message": "This is not a valid phone number. Write it in international format with +, e.g. +919876543210.",
    "field": "to.phone",
    "docs": "https://wbiztool.com/docs/api/v2/errors/#invalid_phone",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817"
  }
}

• code adalah tetap: gunakannya untuk membuat keputusan dalam kod anda. message ialah teks bahasa Inggeris untuk pembangun dan mungkin berubah.
• field menamakan medan yang berkaitan dengan ralat (to.phone, to[3].phone, schedule.cron), atau ialah null.
• docs memaut ke kod itu di halaman ralat.
• request_id sama dengan pengepala X-Request-Id. Nyatakannya jika anda menghubungi kami.
• Sesetengah ralat menambah butiran, contohnya status pada not_cancellable atau used dan limit pada storage_full. Apabila permintaan mempunyai beberapa masalah, errors menyenaraikan yang lain, masing-masing dengan field dan message.

Setiap kod, status HTTP-nya dan apa yang perlu dilakukan ada di halaman ralat.

Idempotency-Key#

Ralat rangkaian atau tamat masa menyebabkan anda tidak pasti sama ada permintaan berjaya. Hantar pengepala Idempotency-Key bersama POST yang mencipta sesuatu, dan anda boleh menghantarnya semula dengan selamat:

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{"to": {"phone": "+919876543210"}, "text": "Hi Asha, your order #1042 is ready."}'

• Nilainya milik anda: sebarang rentetan unik sepanjang 1 hingga 255 aksara boleh cetak, seperti UUID atau ID pesanan anda sendiri. Cipta nilai baharu bagi setiap permintaan baharu, dan gunakannya semula hanya untuk cubaan semula permintaan yang sama.
• Cubaan semula mendapat respons pertama semula dengan pengepala Idempotent-Replayed: true. Tiada apa yang dilakukan dua kali: tiada mesej, peringatan, fail atau endpoint kedua.
• Key bertahan 24 jam dari permintaan pertama, dan dimiliki oleh kunci API anda: kunci API lain dalam ruang kerja boleh menggunakan nilai yang sama tanpa bertembung.
• Key sama, permintaan berbeza: permintaan dengan key yang sudah digunakan untuk kaedah, laluan atau badan yang berbeza menjawab 422 idempotency_key_reused.
• Masih berjalan: semasa permintaan pertama dengan key itu masih diproses, cubaan semula menjawab 409 idempotency_in_progress dengan Retry-After: 1. Tunggu sebentar dan hantar semula.
• Ralat tidak disimpan. Jika permintaan pertama menjawab dengan ralat, tiada apa yang disimpan: betulkan permintaan dan hantar semula dengan key yang sama.
• Rahsia tidak dimainkan semula. Main semula POST /webhooks tidak menyertakan secret endpoint, yang hanya dipaparkan dalam respons pertama.

Ia berfungsi pada POST /messages, POST /messages/batch, POST /numbers, POST /reminders, POST /media, POST /number-checks dan POST /webhooks, dan adalah pilihan pada setiap satu. Permintaan lain mengabaikan pengepala ini. Nilai yang kosong atau terlalu panjang menjawab 400 invalid_idempotency_key.

Had kadar#

Setiap kunci boleh membuat 60 permintaan seminit dan 10,000 permintaan sehari. Ini ialah tetingkap tetap: tetingkap minit bermula pada minit jam, tetingkap hari pada 00:00 UTC. Jika melebihi had, permintaan menjawab 429 rate_limited.

Respons kepada permintaan dengan kunci yang sah membawa pengepala ini:

Berasingan daripada had ini:

• Kunci salah: lebih daripada 30 permintaan seminit dengan kunci yang salah dari satu alamat IP menjawab 429 too_many_auth_failures dengan Retry-After: 60.
• Mesej bagi setiap nombor: satu nombor menghantar paling banyak 1,000 mesej dalam 24 jam (penggunaan berpatutan). Penghantaran yang melebihinya menjawab 429 number_daily_cap_reached.

Penomboran halaman#

Senarai yang boleh bertambah (GET /messages, /reminders, /media, /number-checks dan /results sesuatu semakan) dipulangkan dalam halaman, yang terbaharu dahulu:

{
  "data": [ … ],
  "next_cursor": "eyJpZCI6OTgxNzI2MywidCI6IjIwMjYtMTAtMThUMTA6MTU6MDIuMzExWiIsImYiOiI0NGIxMzZmYTM1NWIifQ"
}

• limit menetapkan saiz halaman, dari 1 hingga 100 (lalai 25).
• Untuk mendapatkan halaman seterusnya, hantar permintaan yang sama dengan cursor ditetapkan kepada next_cursor halaman terakhir. next_cursor ialah null pada halaman terakhir.
• Kekalkan penapis lain yang sama: kursor yang digunakan dengan penapis berbeza menjawab 400 invalid_cursor. Mulakan semula tanpa kursor.
• Anggap kursor sebagai rentetan legap. Item yang ditambah semasa anda menyelak halaman tidak mengalihkan halaman.

curl "https://wbiztool.com/api/v2/messages?limit=100&cursor=eyJpZCI6OTgxNzI2MywidCI6..." \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

GET /numbers dan GET /webhooks memulangkan semuanya dalam satu senarai data.

ID permintaan#

Setiap respons, termasuk ralat, mempunyai pengepala X-Request-Id seperti req_4f1c2a9b8e7d6c5b4a392817. Ralat membawa nilai yang sama sebagai request_id. Rekodkannya, dan nyatakannya jika anda menghubungi kami: ia membolehkan kami mencari permintaan itu dalam log kami, yang merekodkan ID kunci anda tetapi tidak sekali-kali kunci itu sendiri.

Jika anda menghantar X-Request-Id anda sendiri (sehingga 100 aksara boleh cetak), ia kembali sebagai X-Client-Request-Id, supaya anda boleh memadankan respons dengan log anda sendiri.

Mod ujian#

Kunci ujian (wbz_test_…) membolehkan anda membina dan menguji integrasi tanpa menghantar apa-apa. Cipta satu di Tetapan → Kunci API dengan Jenis kunci: Ujian. GET /me menunjukkan "mode": "test".

Apa yang dilakukan oleh kunci ujian sama seperti kunci langsung:

• POST /messages dan POST /messages/batch menyemak semua yang disemak oleh penghantaran langsung: penerima, teks, media, send_at dan expires_at, nombor penghantar, serta skop dan nombor kunci. Kesilapan yang sama mendapat ralat yang sama.
• Skop, nombor, had kadar dan Idempotency-Key berfungsi dengan cara yang sama.
• Setiap bacaan bahagian lain ruang kerja (GET /me, /numbers, /reminders, /media, /number-checks, /webhooks) menunjukkan data sebenarnya, baca sahaja.

Apa yang berbeza:

• Tiada apa yang dihantar. Penghantaran ujian disimpan sebagai mesej ujian, dan tidak menggunakan mesej pelan atau had harian 1,000 nombor itu, jadi ia tidak sekali-kali mendapat no_credits atau number_daily_cap_reached.
• Statusnya bergerak dengan sendirinya: queued, kemudian sent 5 saat kemudian dan delivered 15 saat selepas ia dicipta (dikira dari send_at bagi mesej yang dijadualkan). Mesej yang expires_at-nya tiba sebelum ia dihantar menjadi expired. Mesej ujian tidak sekali-kali menjadi read atau failed.
• Kunci ujian hanya melihat mesej ujiannya sendiri. GET /messages dan GET /messages/{id} hanya menunjukkan mesej itu, dan DELETE /messages/{id} membatalkannya semasa ia queued atau scheduled. Kunci langsung tidak sekali-kali melihat mesej ujian. Penapis status bagi GET /messages tidak disokong untuk kunci ujian dan menjawab test_mode_unsupported; number, since dan until berfungsi.
• Penulisan lain ditolak dengan 403 test_mode_unsupported: menyambungkan nombor, mencipta, mengubah atau memadam peringatan, memuat naik atau memadam media, memulakan semakan nombor, serta menambah, membuang, menukar ganti atau menguji endpoint webhook.
• Tiada peristiwa webhook dihantar untuk mesej ujian.
• Mesej ujian disimpan selama 30 hari.

Sumber#

• Mesej: hantar sekarang atau kemudian, hantar kepada sehingga 1,000 penerima, baca sejarah, batalkan.
• Nombor: senaraikan nombor WhatsApp dan akaun Telegram anda, dan sambungkan nombor WhatsApp dengan kod QR atau kod pautan.
• Peringatan: mesej berulang mengikut jadual cron.
• Media: muat naik fail sekali dan hantarnya dengan media_id.
• Semakan nombor: ketahui nombor mana yang ada di WhatsApp.
• Webhook: peristiwa bertandatangan apabila mesej dihantar, gagal, dibatalkan atau tamat tempoh.
• Ralat: setiap kod ralat.
• Berpindah dari v1 ke v2: setiap endpoint dan medan v1, serta padanannya dalam v2.