الانتقال من v1 إلى v2

يفعل API v2 ما يفعله v1، مع مفاتيح أكثر أمانًا، وأسلوب واحد للعناوين، ورموز حالة HTTP حقيقية، وwebhooks بصيغة JSON موقّعة. تطابق هذه الصفحة كل نقطة نهاية وكل حقل في v1 مع ما يقابله في v2. أما الجديد في v2 نفسه فتجده في النظرة العامة.

ما يتغيّر في كل مكان#

• المفاتيح: يصبح client_id + api_key في v1 ترويسة واحدة، Authorization: Bearer wbz_live_…. أنشئ مفتاح v2 في الإعدادات ← مفاتيح API، في بطاقة مفاتيح API v2، مع النطاقات التي يحتاج إليها التطبيق فقط. لا تعمل مفاتيح v1 على v2، ولا تعمل مفاتيح v2 على v1.
• JSON فقط: لا حقول نموذج. تذهب عمليات رفع الملفات إلى POST /media (بصيغة multipart) وتُرسَل عبر media_id.
• الطرق والعناوين: GET للقراءة، وPOST للإنشاء، وPATCH للتغيير، وDELETE للإلغاء أو الحذف، تحت https://wbiztool.com/api/v2.
• رموز حالة HTTP بدلًا من "status": 0 أو 1 (راجع الاستجابات والأخطاء).
• أرقام الهواتف بالصيغة الدولية مع +، دون country_code.
• الأوقات بصيغة ISO 8601 مع فارق التوقيت، بدلًا من حقول منفصلة للتاريخ والوقت والمنطقة الزمنية.
• Webhooks هي نقاط استقبال تضيفها مرة واحدة لمساحة العمل، مع أحداث JSON موقّعة، بدلًا من عنوان webhook في كل رسالة.

نقطة نهاية تلو الأخرى#

مسارات v2 نسبية إلى https://wbiztool.com/api/v2.

الإرسال حقلًا بحقل#

عملية الإرسال نفسها في v1 و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"}'

أُزيلت بعض سلوكيات v1 عن قصد:

• لا تخمين لرموز الدول. كان v1 يضع country_code أمام الرقم (ومع 91، دائمًا أمام الرقم المكوّن من 10 خانات). أما v2 فيأخذ الرقم كما كُتب تمامًا مع +.
• لا تنزيل للملف عند الاستدعاء. كان v1 يجلب img_url وfile_url أثناء الطلب. أما v2 فيتحقق من أن الرابط عام ويجلب الملف عند إرسال الرسالة؛ ويظهر الرابط السيئ كرسالة failed.
• لا صف فاشل عند الرفض. عندما يرفض v1 إرسالًا يتجاوز الحد اليومي البالغ 1,000، فإنه يحفظ الرسالة رغم ذلك كرسالة فاشلة. أما v2 فلا يحفظ شيئًا عندما يرفض إرسالًا.
• تُرفض الحقول غير المعروفة بدلًا من تجاهلها.

الحالات#

تصبح أرقام v1 وكلماته حقل status واحدًا:

أحداث webhook هي message.sent وmessage.failed وmessage.cancelled وmessage.expired، وتقابل SENT وFAILED وCANCELLED وEXPIRED في v1.

الاستجابات والأخطاء#

يجيب v1 عن كثير من الأخطاء بحالة HTTP ‏200 أو 400 مع "status": 0، وعن النجاح بـ "status": 1. أما v2 فيستخدم رمز حالة HTTP:

• النجاح هو 200 أو 201 (أُنشئ) أو 202 (في قائمة الانتظار)، والجسم هو الكائن نفسه، مثل الرسالة. لا يوجد غلاف status: 1.
• الأخطاء هي 4xx أو 5xx ببنية واحدة: {"error": {"code", "message", "field", "docs", "request_id"}}. اعتمد في التفرّع على code، لا على message الإنجليزي. كل رمز موجود في صفحة الأخطاء.

# 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

بعض رسائل v1 ورموزها في v2:

Webhooks#

في v1، يمكن أن تحمل كل رسالة عنوان webhook يتلقى msg_id=…&status=SENT بترميز النموذج. أما في v2:

1. أضف نقطة استقبال مرة واحدة عبر POST /webhooks واحفظ secret الخاص بها.
2. تتلقى أحداث JSON لكل رسائل مساحة العمل، مع الرسالة كاملة في data.message. طابقها مع سجلاتك عبر data.message.id.
3. تحقّق من التوقيع: المخطط نفسه المستخدم في v1 ‏(WbizTool-Timestamp، WbizTool-Signature: v1=…)، لكن بسرّ نقطة الاستقبال الخاص بها بدلًا من سرّ مساحة العمل.
4. تجاهل التكرارات عبر WbizTool-Event-Id. تستمر إعادة المحاولة نحو 23 ساعة، لا 4 محاولات خلال بضع دقائق كما في v1، ويُعاد إرسال الاستجابات 4xx أيضًا.

ليس لأحداث الربط في v1 ‏(webhook_url في whatsapp/connect/) حدث مقابل في v2 بعد: استطلع GET /numbers/{id} بدلًا من ذلك.

قائمة تحقق#

1. أنشئ مفتاح v2 لكل تطبيق

   في الإعدادات ← مفاتيح API، مع النطاقات التي يحتاج إليها فقط. جرّبه أولًا بـمفتاح اختبار، الذي يتحقق من كل شيء ولا يرسل شيئًا.

2. غيّر الطلبات

   عناوين وطرق جديدة، وأجسام JSON، وto / from / text / media، وأرقام هواتف مع +، وأوقات مع فارق التوقيت. أضف Idempotency-Key إلى كل عملية إرسال.

3. غيّر طريقة التعامل مع الأخطاء

   تحقّق من حالة HTTP، ثم من error.code. تعامل مع 429 بالانتظار مدة Retry-After.

4. انقل webhooks

   أضف نقطة استقبال، وتحقّق من التوقيعات بسرّها، وتجاهل التكرارات عبر معرّف الحدث.

5. انتقل وألغِ المفتاح القديم

   بمجرد أن يعمل التطبيق على v2، احذف مفتاح v1 الخاص به في الإعدادات ← مفاتيح API.

صفحات ذات صلة#

• نظرة عامة على API v2
• الرسائل
• Webhooks
• الأخطاء
• مفاتيح API وClient ID ‏(v1)