v1'den v2'ye geçiş

API v2, v1'in yaptığı her şeyi daha güvenli anahtarlar, tek bir URL stili, gerçek HTTP durum kodları ve imzalı JSON webhook'larıyla yapar. Bu sayfa her v1 endpoint'ini ve alanını v2'deki karşılığıyla eşleştirir. v2'nin kendisindeki yenilikler genel bakış sayfasındadır.

Her yerde değişenler#

• Anahtarlar: v1'deki client_id + api_key, tek bir başlığa dönüşür: Authorization: Bearer wbz_live_…. Ayarlar → API anahtarları sayfasındaki API v2 anahtarları kartında, yalnızca uygulamanın ihtiyaç duyduğu kapsamlarla bir v2 anahtarı oluşturun. v1 anahtarları v2'de, v2 anahtarları da v1'de çalışmaz.
• Yalnızca JSON: form alanları yok. Dosya yüklemeleri POST /media endpoint'ine (multipart) gider ve media_id ile gönderilir.
• Yöntemler ve URL'ler: okumak için GET, oluşturmak için POST, değiştirmek için PATCH, iptal etmek veya silmek için DELETE; hepsi https://wbiztool.com/api/v2 altında.
• "status": 0 veya 1 yerine HTTP durum kodları (bkz. Yanıtlar ve hatalar).
• country_code olmadan, + ile uluslararası biçimde telefon numaraları.
• Ayrı tarih, saat ve saat dilimi alanları yerine ofsetli ISO 8601 biçiminde zamanlar.
• Webhook'lar, her mesajdaki bir webhook URL'si yerine, çalışma alanı için bir kez eklediğiniz ve imzalı JSON olayları gönderen uç noktalardır.

Endpoint bazında#

v2 yolları https://wbiztool.com/api/v2 adresine göredir.

Gönderim, alan alan#

Aynı gönderim v1 ve v2'de:

# 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"}'

v1'in bazı davranışları bilerek kaldırıldı:

• Ülke kodu tahmini yok. v1, bir numaranın önüne country_code ekliyordu (91 ile, 10 haneli bir numaranın önüne her zaman). v2 numarayı + ile tam yazıldığı gibi alır.
• Çağrı sırasında dosya indirme yok. v1, img_url ve file_url dosyalarını istek sırasında indiriyordu. v2 bağlantının herkese açık olduğunu kontrol eder ve dosyayı mesaj gönderilirken indirir; hatalı bir bağlantı failed bir mesaj olarak görünür.
• Reddedilen gönderim için başarısız kayıt yok. v1, günlük 1.000 sınırını aşan bir gönderimi reddettiğinde mesajı yine de başarısız olarak kaydeder. v2, bir gönderimi reddettiğinde hiçbir şey kaydetmez.
• Bilinmeyen alanlar yok sayılmak yerine reddedilir.

Durumlar#

v1'in sayıları ve sözcükleri tek bir status alanına dönüşür:

Webhook olayları message.sent, message.failed, message.cancelled ve message.expired olup v1'deki SENT, FAILED, CANCELLED ve EXPIRED değerlerine karşılık gelir.

Yanıtlar ve hatalar#

v1 birçok hatayı HTTP 200 veya 400 ve "status": 0 ile, başarıyı ise "status": 1 ile yanıtlar. v2 HTTP durum kodunu kullanır:

• Başarı 200, 201 (oluşturuldu) veya 202 (kuyruğa alındı) olur ve gövde, Message gibi nesnenin kendisidir. status: 1 sarmalayıcısı yoktur.
• Hatalar tek bir yapıyla 4xx veya 5xx olur: {"error": {"code", "message", "field", "docs", "request_id"}}. İngilizce message değerine değil, code değerine göre dallanın. Tüm kodlar hatalar sayfasındadır.

# 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

Bazı v1 mesajları ve v2 kodları:

Webhook'lar#

v1'de her mesaj, form kodlamalı bir msg_id=…&status=SENT alan bir webhook URL'si taşıyabilir. v2'de:

1. POST /webhooks ile bir kez bir uç nokta ekleyin ve secret değerini saklayın.
2. Uç nokta, çalışma alanının her mesajı için, data.message içinde Message nesnesinin tamamıyla JSON olayları alır. Bunları kayıtlarınızla data.message.id üzerinden eşleştirin.
3. İmzayı doğrulayın: v1'dekiyle aynı yöntem (WbizTool-Timestamp, WbizTool-Signature: v1=…), ancak çalışma alanınınki yerine uç noktanın kendi gizli anahtarıyla.
4. Tekrarları WbizTool-Event-Id ile atın. Yeniden denemeler, v1'deki gibi birkaç dakika içinde 4 deneme değil, yaklaşık 23 saat sürer ve 4xx yanıtları da yeniden denenir.

v1'in bağlantı olaylarının (whatsapp/connect/ üzerindeki webhook_url) henüz v2 karşılığı yok: bunun yerine GET /numbers/{id} sorgulayın.

Kontrol listesi#

1. Her uygulama için bir v2 anahtarı oluşturun

   Ayarlar → API anahtarları sayfasında, yalnızca ihtiyaç duyduğu kapsamlarla. Önce her şeyi kontrol eden ve hiçbir şey göndermeyen bir test anahtarıyla deneyin.

2. İstekleri değiştirin

   Yeni URL'ler ve yöntemler, JSON gövdeler, to / from / text / media, + ile telefon numaraları, ofsetli zamanlar. Her gönderime bir Idempotency-Key ekleyin.

3. Hata işlemeyi değiştirin

   Önce HTTP durumunu, ardından error.code değerini kontrol edin. 429 yanıtında Retry-After kadar bekleyin.

4. Webhook'ları taşıyın

   Bir uç nokta ekleyin, imzaları onun gizli anahtarıyla doğrulayın ve tekrarları olay ID'sine göre atın.

5. Geçişi tamamlayın ve iptal edin

   Uygulama v2'de çalışmaya başladığında, Ayarlar → API anahtarları sayfasında onun v1 anahtarını silin.

İlgili sayfalar#

• API v2'ye genel bakış
• Mesajlar
• Webhook'lar
• Hatalar
• API anahtarları ve Client ID (v1)