API v2 (تجريبي)
الأرقام
الرقم هو رقم WhatsApp أو حساب Telegram متصل بمساحة عملك. ومعرّفه id هو قيمة from التي ترسل بها الرسائل. باستخدام API v2 يمكنك عرض الأرقام، ومعرفة ما إذا كان كل منها متصلًا، وربط رقم WhatsApp من تطبيقك الخاص، برمز QR أو برمز الربط.
| العملية | نقطة النهاية | النطاق |
|---|---|---|
| عرض الأرقام | GET /api/v2/numbers | numbers |
| جلب رقم | GET /api/v2/numbers/{id} | numbers |
| ربط رقم WhatsApp | POST /api/v2/numbers | numbers |
المفتاح المقيد ببعض الأرقام لا يرى ولا يعيد ربط إلا تلك الأرقام، ولا يستطيع إضافة رقم.
عرض الأرقام#
https://wbiztool.com/api/v2/numbersكل أرقام مساحة العمل، الأقدم أولًا، في قائمة data واحدة (بدون صفحات).
curl https://wbiztool.com/api/v2/numbers \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"import os
import requests
response = requests.get(
"https://wbiztool.com/api/v2/numbers",
headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
timeout=30,
)
for number in response.json()["data"]:
print(number["id"], number["phone"], number["label"], number["status"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/numbers", {
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
const { data } = await response.json();
for (const number of data) console.log(number.id, number.phone, number.label, number.status);<?php
$ch = curl_init('https://wbiztool.com/api/v2/numbers');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
]);
$numbers = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);
foreach ($numbers as $number) {
echo $number['id'] . ' ' . $number['phone'] . ' ' . $number['status'] . "\n";
}{
"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 في القائمة. ولمتابعة عملية ربط، اجلب الرقم.
جلب رقم#
https://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#
| الحقل | النوع | الوصف |
|---|---|---|
id | integer | معرّف الرقم: قيمة from لرسالة أو تذكير. |
phone | string or null | خاناته مع رمز الدولة، بدون +، مثل 919800000000. وتكون null للرقم الجديد الذي يُربط برمز QR إلى أن يُمسح الرمز. |
label | string | اسمه في لوحة التحكم؛ و"" إذا لم يكن له اسم. |
platform | string | whatsapp أو telegram. |
status | string | connected، أو connecting (طُلب الربط خلال آخر 10 دقائق وما زال جاريًا)، أو disconnected. |
login_method | string | طريقة الربط: qr أو phone_code (رمز ربط). |
connect | object or null | ما دامت قيمة status هي connecting، وفقط من جلب رقم؛ وإلا null. |
يحتوي connect على:
| الحقل | النوع | الوصف |
|---|---|---|
qr_code_url | string or null | رابط إلى صورة رمز QR التي يجب مسحها. يعطي كل استدعاء رابطًا جديدًا صالحًا لمدة 10 دقائق؛ وتكون null إلى أن يحصل الخادم على رمز QR. |
pairing_code | string or null | لـphone_code: الرمز الذي يُكتب على الهاتف. وتكون null إلى أن يصبح جاهزًا. |
pairing_code_expires_at | string or null | الوقت الذي يتوقف فيه رمز الربط عن العمل. |
linking | boolean | true بعد مسح رمز QR أو قبول الرمز، ريثما ينهي WhatsApp الربط. |
requested_at | string or null | وقت طلب الربط. |
الرسائل المرسلة مع رقم disconnected في from تُقبل مع ذلك: فهي تنتظر وتُرسَل عندما يعود الرقم متصلًا. ستأتي أحداث webhook للأرقام لاحقًا؛ وإلى ذلك الحين، استعلم دوريًا عن GET /numbers لملاحظة الرقم الذي سُجّل خروجه.
ربط رقم WhatsApp#
https://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}'import os
import time
import requests
API = "https://wbiztool.com/api/v2"
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}
number = requests.post(f"{API}/numbers", headers=headers,
json={"login_method": "phone_code", "phone": "+919876543210"}, timeout=30).json()
shown = None
while number["status"] == "connecting":
time.sleep(3)
number = requests.get(f"{API}/numbers/{number['id']}", headers=headers, timeout=30).json()
code = (number["connect"] or {}).get("pairing_code")
if code and code != shown:
print("On the phone: WhatsApp → Linked devices → Link with phone number, then type", code)
shown = code
print("Number", number["id"], "is", number["status"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const API = "https://wbiztool.com/api/v2";
const headers = { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" };
let number = await (await fetch(`${API}/numbers`, {
method: "POST", headers, body: JSON.stringify({ login_method: "qr" }),
})).json();
let shown = null;
while (number.status === "connecting") {
await new Promise((r) => setTimeout(r, 3000));
number = await (await fetch(`${API}/numbers/${number.id}`, { headers })).json();
const qr = number.connect?.qr_code_url;
if (qr && qr !== shown) {
console.log("Show this QR code to scan:", qr); // e.g. in an <img> on your page
shown = qr;
}
}
console.log(`Number ${number.id} is ${number.status}`);<?php
$ch = curl_init('https://wbiztool.com/api/v2/numbers');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['login_method' => 'qr']),
CURLOPT_RETURNTRANSFER => true,
]);
$number = json_decode(curl_exec($ch), true);
curl_close($ch);
// Save $number['id'], then poll GET /api/v2/numbers/{id} every few seconds (see The connect flow).
echo $number['id'] . ' ' . $number['status'];خطوات الربط#
اطلب الربط
POST /numbersمعlogin_method(وphoneلرمز الربط). احتفظ بـidمن الاستجابة. أرسلIdempotency-Keyحتى لا تطلب إعادةُ المحاولة الربطَ مرتين.استعلم عن الرقم كل بضع ثوانٍ
GET /numbers/{id}كل 2 إلى 5 ثوانٍ ما دامت قيمةstatusهيconnecting. يظهر رمز QR أو رمز الربط فيconnectخلال لحظات؛ وإلى ذلك الحين تكون حقولهnull.اعرض رمز 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 دقائق).انتظر حالة connected
بعد المسح أو كتابة الرمز، تكون قيمة
connect.linkingهيtrueريثما ينهي WhatsApp الربط. ثم تصبح قيمةstatusهيconnectedويعرضphoneالرقم. أوقف الاستعلام.
إذا لم يحدث شيء خلال 10 دقائق، تنتهي المحاولة وتعود قيمة status إلى disconnected. اطلب مجددًا باستخدام POST /numbers مع number_id الخاص به.
أثناء ربط رقم، يُرجع أي طلب آخر له 409 connect_in_progress مع number_id الخاص به: واصل الاستعلام عن ذلك الرقم بدلًا من ذلك.
أخطاء الربط#
| HTTP | الرمز | متى |
|---|---|---|
400 | validation_failed | login_method ليس qr أو phone_code، أو phone_code بدون phone |
403 | plan_required | الباقة لا تتضمن API رمز QR |
403 | number_limit_reached | لا مكان في الباقة لرقم آخر |
403 | number_not_allowed | المفتاح مقيد ببعض الأرقام، وnumber_id ليس منها (أو مفقود) |
409 | already_connected | ذلك الرقم متصل بالفعل |
409 | connect_in_progress | ذلك الرقم قيد الربط الآن؛ ويوضّح number_id أي رقم هو |
422 | invalid_phone | phone ليس رقمًا صالحًا بالصيغة الدولية مع + |
422 | number_not_found | number_id ليس رقمًا في مساحة العمل هذه |
صفحات ذات صلة#
- اربط رقم WhatsApp الخاص بك في لوحة التحكم
- اربط حساب Telegram
- الرسائل: أرسل من رقم باستخدام
from - الأخطاء
