Pindah dari v1 ke v2

API v2 melakukan apa yang dilakukan v1, dengan kunci yang lebih aman, satu gaya URL, kode status HTTP yang sebenarnya, dan webhook JSON yang ditandatangani. Halaman ini memetakan setiap endpoint dan field v1 ke padanannya di v2. Hal-hal yang baru di v2 sendiri ada di ikhtisar.

Yang berubah di semua endpoint#

• Kunci: client_id + api_key di v1 menjadi satu header, Authorization: Bearer wbz_live_…. Buat kunci v2 di Pengaturan → Kunci API, pada kartu Kunci API v2, hanya dengan scope yang dibutuhkan aplikasi. Kunci v1 tidak berfungsi di v2, dan kunci v2 tidak berfungsi di v1.
• Hanya JSON: tanpa field formulir. Unggahan file dikirim ke POST /media (multipart) dan dikirim dengan media_id.
• Method dan URL: GET untuk membaca, POST untuk membuat, PATCH untuk mengubah, DELETE untuk membatalkan atau menghapus, di bawah https://wbiztool.com/api/v2.
• Kode status HTTP sebagai pengganti "status": 0 atau 1 (lihat Respons dan error).
• Nomor telepon dalam format internasional dengan +, tanpa country_code.
• Waktu dalam ISO 8601 dengan offset, sebagai pengganti field tanggal, waktu, dan zona waktu yang terpisah.
• Webhook berupa endpoint yang Anda tambahkan sekali untuk workspace, dengan peristiwa JSON yang ditandatangani, sebagai pengganti URL webhook di setiap pesan.

Per endpoint#

Path v2 relatif terhadap https://wbiztool.com/api/v2.

Mengirim, per field#

Pengiriman yang sama di v1 dan v2:

# v1
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_V1_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "msg_type": 1, "country_code": "91", "phone": "9876543210",
       "img_url": "https://example.com/offers/diwali-sale.jpg", "msg": "Our Diwali sale starts today",
       "expire_after_seconds": 3600}'

# v2
curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: diwali-9876543210" \
  -d '{"from": 101, "to": {"phone": "+919876543210"},
       "media": {"url": "https://example.com/offers/diwali-sale.jpg"}, "text": "Our Diwali sale starts today",
       "expires_at": "2026-10-20T11:30:00+05:30"}'

Beberapa perilaku v1 sengaja dihilangkan:

• Tidak ada tebakan kode negara. v1 menaruh country_code di depan nomor (dengan 91, selalu di depan nomor 10 digit). v2 menerima nomor persis seperti yang ditulis dengan +.
• Tidak ada pengunduhan file saat Anda memanggil API. v1 mengambil img_url dan file_url selama request. v2 memeriksa bahwa tautan itu publik dan mengambil file saat pesan dikirim; tautan yang buruk muncul sebagai pesan failed.
• Tidak ada baris gagal saat ditolak. Saat v1 menolak pengiriman yang melewati batas harian 1.000, v1 tetap menyimpan pesan itu sebagai gagal. v2 tidak menyimpan apa pun saat menolak pengiriman.
• Field yang tidak dikenal ditolak, bukan diabaikan.

Status#

Angka dan kata di v1 menjadi satu field status:

Peristiwa webhook adalah message.sent, message.failed, message.cancelled, dan message.expired, sesuai dengan SENT, FAILED, CANCELLED, dan EXPIRED di v1.

Respons dan error#

v1 menjawab banyak error dengan HTTP 200 atau 400 dan "status": 0, dan keberhasilan dengan "status": 1. v2 memakai kode status HTTP:

• Berhasil berarti 200, 201 (dibuat), atau 202 (masuk antrean), dan body-nya adalah objek itu sendiri, seperti Message. Tidak ada pembungkus status: 1.
• Error berupa 4xx atau 5xx dengan satu bentuk: {"error": {"code", "message", "field", "docs", "request_id"}}. Gunakan code untuk percabangan, bukan message berbahasa Inggris. Setiap kode ada di halaman error.

# v1
result = response.json()
if result.get("status") == 1:
    msg_id = result["msg_id"]

# v2
if response.status_code == 202:
    message_id = response.json()["id"]
else:
    error = response.json()["error"]
    if error["code"] == "number_daily_cap_reached":
        ...  # try again tomorrow

Beberapa pesan v1 dan kode v2-nya:

Webhook#

Di v1, setiap pesan dapat membawa URL webhook yang menerima msg_id=…&status=SENT dalam format form-encoded. Di v2:

1. Tambahkan endpoint sekali dengan POST /webhooks dan simpan secret-nya.
2. Endpoint menerima peristiwa JSON untuk setiap pesan di workspace, dengan Message lengkap di data.message. Cocokkan dengan catatan Anda berdasarkan data.message.id.
3. Verifikasi tanda tangan: skemanya sama dengan v1 (WbizTool-Timestamp, WbizTool-Signature: v1=…), tetapi dengan rahasia milik endpoint itu sendiri, bukan rahasia workspace.
4. Buang duplikat dengan WbizTool-Event-Id. Percobaan ulang berlangsung sekitar 23 jam, bukan 4 percobaan dalam beberapa menit seperti di v1, dan respons 4xx juga dicoba ulang.

Peristiwa koneksi v1 (webhook_url di whatsapp/connect/) belum memiliki peristiwa v2: lakukan polling GET /numbers/{id} sebagai gantinya.

Daftar periksa#

1. Buat kunci v2 per aplikasi

   Di Pengaturan → Kunci API, hanya dengan scope yang dibutuhkan. Coba dulu dengan kunci uji, yang memeriksa semuanya dan tidak mengirim apa pun.

2. Ubah request

   URL dan method baru, body JSON, to / from / text / media, nomor telepon dengan +, waktu dengan offset. Tambahkan Idempotency-Key ke setiap pengiriman.

3. Ubah penanganan error

   Periksa status HTTP, lalu error.code. Tangani 429 dengan menunggu selama Retry-After.

4. Pindahkan webhook

   Tambahkan endpoint, verifikasi tanda tangan dengan rahasianya, dan buang duplikat berdasarkan ID peristiwa.

5. Beralih dan cabut

   Setelah aplikasi berjalan di v2, hapus kunci v1-nya di Pengaturan → Kunci API.

Terkait#

• Ikhtisar API v2
• Pesan
• Webhook
• Error
• Kunci API dan Client ID (v1)