انتقل إلى المحتوى
WbizTool

API v2 (تجريبي)

الأرقام

الرقم هو رقم WhatsApp أو حساب Telegram متصل بمساحة عملك. ومعرّفه id هو قيمة from التي ترسل بها الرسائل. باستخدام API v2 يمكنك عرض الأرقام، ومعرفة ما إذا كان كل منها متصلًا، وربط رقم WhatsApp من تطبيقك الخاص، برمز QR أو برمز الربط.

العمليةنقطة النهايةالنطاق
عرض الأرقامGET /api/v2/numbersnumbers
جلب رقمGET /api/v2/numbers/{id}numbers
ربط رقم WhatsAppPOST /api/v2/numbersnumbers

المفتاح المقيد ببعض الأرقام لا يرى ولا يعيد ربط إلا تلك الأرقام، ولا يستطيع إضافة رقم.

عرض الأرقام#

GEThttps://wbiztool.com/api/v2/numbers

كل أرقام مساحة العمل، الأقدم أولًا، في قائمة data واحدة (بدون صفحات).

curl https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"
{
  "data": [
    {
      "id": 101,
      "phone": "919800000000",
      "label": "Shop",
      "platform": "whatsapp",
      "status": "connected",
      "login_method": "qr",
      "connect": null
    },
    {
      "id": 102,
      "phone": null,
      "label": "",
      "platform": "whatsapp",
      "status": "disconnected",
      "login_method": "qr",
      "connect": null
    }
  ]
}

تكون قيمة connect دائمًا null في القائمة. ولمتابعة عملية ربط، اجلب الرقم.

جلب رقم#

GEThttps://wbiztool.com/api/v2/numbers/{id}

رقم واحد. أثناء ربطه، يحتوي connect على رمز QR الذي يجب مسحه أو رمز الربط الذي يجب كتابته.

curl https://wbiztool.com/api/v2/numbers/102 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"
{
  "id": 102,
  "phone": null,
  "label": "",
  "platform": "whatsapp",
  "status": "connecting",
  "login_method": "qr",
  "connect": {
    "qr_code_url": "https://…/qr_codes/…png?X-Amz-Signature=…",
    "pairing_code": null,
    "pairing_code_expires_at": null,
    "linking": false,
    "requested_at": "2026-10-18T11:02:15.402Z"
  }
}

الرقم غير الموجود، أو الذي لا يُسمح للمفتاح باستخدامه، يُرجع 404 number_not_found.

كائن Number#

الحقلالنوعالوصف
idintegerمعرّف الرقم: قيمة from لرسالة أو تذكير.
phonestring or nullخاناته مع رمز الدولة، بدون +، مثل 919800000000. وتكون null للرقم الجديد الذي يُربط برمز QR إلى أن يُمسح الرمز.
labelstringاسمه في لوحة التحكم؛ و"" إذا لم يكن له اسم.
platformstring‏whatsapp أو telegram.
statusstring‏connected، أو connecting (طُلب الربط خلال آخر 10 دقائق وما زال جاريًا)، أو disconnected.
login_methodstringطريقة الربط: qr أو phone_code (رمز ربط).
connectobject or nullما دامت قيمة status هي connecting، وفقط من جلب رقم؛ وإلا null.

يحتوي connect على:

الحقلالنوعالوصف
qr_code_urlstring or nullرابط إلى صورة رمز QR التي يجب مسحها. يعطي كل استدعاء رابطًا جديدًا صالحًا لمدة 10 دقائق؛ وتكون null إلى أن يحصل الخادم على رمز QR.
pairing_codestring or nullلـphone_code: الرمز الذي يُكتب على الهاتف. وتكون null إلى أن يصبح جاهزًا.
pairing_code_expires_atstring or nullالوقت الذي يتوقف فيه رمز الربط عن العمل.
linkingboolean‏true بعد مسح رمز QR أو قبول الرمز، ريثما ينهي WhatsApp الربط.
requested_atstring or nullوقت طلب الربط.

الرسائل المرسلة مع رقم disconnected في from تُقبل مع ذلك: فهي تنتظر وتُرسَل عندما يعود الرقم متصلًا. ستأتي أحداث webhook للأرقام لاحقًا؛ وإلى ذلك الحين، استعلم دوريًا عن GET /numbers لملاحظة الرقم الذي سُجّل خروجه.

ربط رقم WhatsApp#

POSThttps://wbiztool.com/api/v2/numbers

النص (Body): JSON (application/json)

يطلب من خادم WbizTool فتح WhatsApp لرقم ما، لتتمكن من ربطه من تطبيقك أو موقعك الخاص، كما تفعل في أرقام WhatsApp. والاستجابة 202 مع الرقم بحالة connecting. ثم استعلم عنه دوريًا حتى يصبح connected.

يحتاج إلى باقة تتضمن API رمز QR؛ وإلا يُرجع 403 plan_required. أما حسابات Telegram فتُربط من لوحة التحكم، لا من هنا.

الجسم

login_methodstringاختياري

‏qr (افتراضي): امسح رمز QR. ‏phone_code: اكتب رمز ربط على الهاتف بدلًا من ذلك، وهذا مفيد عندما يكون الهاتف هو الشاشة الوحيدة.

phonestringمطلوب مع phone_code

رقم WhatsApp المراد ربطه، بالصيغة الدولية مع +، مثل ‎+919876543210. لا يُستخدم مع qr: إذ يُقرأ الرقم من WhatsApp بعد المسح.

number_idintegerاختياري

أعد ربط هذا الرقم الموجود بدلًا من إضافة رقم جديد، مثلًا بعد تسجيل خروجه.

# By QR code
curl -X POST https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"login_method": "qr"}'

# By pairing code, reconnecting number 101
curl -X POST https://wbiztool.com/api/v2/numbers \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"login_method": "phone_code", "phone": "+919876543210", "number_id": 101}'

خطوات الربط#

  1. اطلب الربط

    ‏POST /numbers مع login_method (وphone لرمز الربط). احتفظ بـid من الاستجابة. أرسل Idempotency-Key حتى لا تطلب إعادةُ المحاولة الربطَ مرتين.

  2. استعلم عن الرقم كل بضع ثوانٍ

    ‏GET /numbers/{id} كل 2 إلى 5 ثوانٍ ما دامت قيمة status هي connecting. يظهر رمز QR أو رمز الربط في connect خلال لحظات؛ وإلى ذلك الحين تكون حقوله null.

  3. اعرض رمز QR أو رمز الربط

    رمز QR: اعرض الصورة الموجودة في connect.qr_code_url؛ وعلى الهاتف، افتح WhatsApp ← الأجهزة المرتبطة (Linked devices) ← ربط جهاز (Link a device) وامسحها. كل رابط يعمل لمدة 10 دقائق ويأتي رابط جديد مع كل استعلام، لذا اعرض الأحدث في كل مرة. رمز الربط: على الهاتف، افتح WhatsApp ← الأجهزة المرتبطة (Linked devices) ← ربط جهاز (Link a device) ← الربط برقم الهاتف بدلًا من ذلك (Link with phone number instead)، واكتب connect.pairing_code المكوّن من 8 أحرف قبل connect.pairing_code_expires_at (نحو 3 دقائق).

  4. انتظر حالة connected

    بعد المسح أو كتابة الرمز، تكون قيمة connect.linking هي true ريثما ينهي WhatsApp الربط. ثم تصبح قيمة status هي connected ويعرض phone الرقم. أوقف الاستعلام.

إذا لم يحدث شيء خلال 10 دقائق، تنتهي المحاولة وتعود قيمة status إلى disconnected. اطلب مجددًا باستخدام POST /numbers مع number_id الخاص به.

أثناء ربط رقم، يُرجع أي طلب آخر له 409 connect_in_progress مع number_id الخاص به: واصل الاستعلام عن ذلك الرقم بدلًا من ذلك.

أخطاء الربط#

HTTPالرمزمتى
400validation_failed‏login_method ليس qr أو phone_code، أو phone_code بدون phone
403plan_requiredالباقة لا تتضمن API رمز QR
403number_limit_reachedلا مكان في الباقة لرقم آخر
403number_not_allowedالمفتاح مقيد ببعض الأرقام، وnumber_id ليس منها (أو مفقود)
409already_connectedذلك الرقم متصل بالفعل
409connect_in_progressذلك الرقم قيد الربط الآن؛ ويوضّح number_id أي رقم هو
422invalid_phone‏phone ليس رقمًا صالحًا بالصيغة الدولية مع +
422number_not_found‏number_id ليس رقمًا في مساحة العمل هذه

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