Berpindah dari v1 ke v2

API v2 melakukan apa yang dilakukan oleh v1, dengan kunci yang lebih selamat, satu gaya URL, kod status HTTP yang sebenar dan webhook JSON bertandatangan. Halaman ini memetakan setiap endpoint dan medan v1 kepada padanannya dalam v2. Perkara yang baharu dalam v2 itu sendiri ada dalam gambaran keseluruhan.

Perkara yang berubah di semua tempat#

• Kunci: client_id + api_key dalam v1 menjadi satu pengepala, Authorization: Bearer wbz_live_…. Cipta kunci v2 di Tetapan → Kunci API, dalam kad Kunci API v2, dengan skop yang diperlukan oleh aplikasi sahaja. Kunci v1 tidak berfungsi pada v2, dan kunci v2 tidak berfungsi pada v1.
• JSON sahaja: tiada medan borang. Muat naik fail dihantar ke POST /media (multipart) dan dihantar dengan media_id.
• Kaedah dan URL: GET untuk membaca, POST untuk mencipta, PATCH untuk mengubah, DELETE untuk membatalkan atau memadam, di bawah https://wbiztool.com/api/v2.
• Kod status HTTP sebagai ganti "status": 0 atau 1 (lihat Respons dan ralat).
• Nombor telefon dalam format antarabangsa dengan +, tanpa country_code.
• Masa dalam ISO 8601 dengan ofset, sebagai ganti medan tarikh, masa dan zon waktu yang berasingan.
• Webhook ialah endpoint yang anda tambah sekali untuk ruang kerja, dengan peristiwa JSON bertandatangan, sebagai ganti URL webhook pada setiap mesej.

Endpoint demi endpoint#

Laluan v2 adalah relatif kepada https://wbiztool.com/api/v2.

Menghantar, medan demi medan#

Penghantaran yang sama dalam 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 tingkah laku v1 sengaja dibuang:

• Tiada tekaan kod negara. v1 meletakkan country_code di hadapan nombor (dengan 91, sentiasa di hadapan nombor 10 digit). v2 menerima nombor tepat seperti yang ditulis dengan +.
• Tiada muat turun fail semasa anda memanggil. v1 mengambil img_url dan file_url semasa permintaan. v2 menyemak bahawa pautan itu awam dan mengambil fail semasa mesej dihantar; pautan yang rosak muncul sebagai mesej failed.
• Tiada baris gagal apabila ditolak. Apabila v1 menolak penghantaran yang melebihi had harian 1,000, ia masih menyimpan mesej itu sebagai gagal. v2 tidak menyimpan apa-apa apabila ia menolak penghantaran.
• Medan yang tidak dikenali ditolak dan bukannya diabaikan.

Status#

Nombor dan perkataan dalam v1 menjadi satu medan status:

Peristiwa webhook ialah message.sent, message.failed, message.cancelled dan message.expired, sepadan dengan SENT, FAILED, CANCELLED dan EXPIRED dalam v1.

Respons dan ralat#

v1 menjawab banyak ralat dengan HTTP 200 atau 400 dan "status": 0, dan kejayaan dengan "status": 1. v2 menggunakan kod status HTTP:

• Kejayaan ialah 200, 201 (dicipta) atau 202 (dalam baris gilir), dan badannya ialah objek itu sendiri, seperti Message. Tiada pembalut status: 1.
• Ralat ialah 4xx atau 5xx dengan satu bentuk: {"error": {"code", "message", "field", "docs", "request_id"}}. Buat keputusan berdasarkan code, bukan message dalam bahasa Inggeris. Setiap kod ada di halaman ralat.

# 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 mesej v1 dan kod v2-nya:

Webhook#

Dalam v1, setiap mesej boleh membawa URL webhook yang menerima msg_id=…&status=SENT dalam format form-encoded. Dalam v2:

1. Tambah endpoint sekali dengan POST /webhooks dan simpan secret-nya.
2. Ia menerima peristiwa JSON untuk setiap mesej ruang kerja, dengan Message penuh dalam data.message. Padankannya dengan rekod anda mengikut data.message.id.
3. Sahkan tandatangan: skema yang sama seperti v1 (WbizTool-Timestamp, WbizTool-Signature: v1=…), tetapi dengan rahsia endpoint itu sendiri dan bukannya rahsia ruang kerja.
4. Buang ulangan dengan WbizTool-Event-Id. Cubaan semula berterusan selama kira-kira 23 jam, bukan 4 cubaan dalam beberapa minit seperti dalam v1, dan respons 4xx juga dicuba semula.

Peristiwa sambungan v1 (webhook_url pada whatsapp/connect/) belum mempunyai peristiwa v2: tinjau GET /numbers/{id} sebaliknya.

Senarai semak#

1. Cipta kunci v2 bagi setiap aplikasi

   Di Tetapan → Kunci API, dengan skop yang diperlukannya sahaja. Cubanya dahulu dengan kunci ujian, yang menyemak semuanya dan tidak menghantar apa-apa.

2. Ubah permintaan

   URL dan kaedah baharu, badan JSON, to / from / text / media, nombor telefon dengan +, masa dengan ofset. Tambah Idempotency-Key pada setiap penghantaran.

3. Ubah pengendalian ralat

   Semak status HTTP, kemudian error.code. Kendalikan 429 dengan menunggu selama Retry-After.

4. Pindahkan webhook

   Tambah endpoint, sahkan tandatangan dengan rahsianya, dan buang ulangan mengikut ID peristiwa.

5. Beralih dan tarik balik

   Setelah aplikasi berjalan pada v2, padam kunci v1-nya di Tetapan → Kunci API.

Berkaitan#

• Gambaran keseluruhan API v2
• Mesej
• Webhook
• Ralat
• Kunci API dan Client ID (v1)