API الرسائل
API حالة الرسالة
تحقّق مما إذا كانت الرسالة التي أرسلتها عبر API لا تزال في قائمة الانتظار، أو أُرسلت، أو فشلت. استخدمه للتأكد من أن الرسائل المهمة قد أُرسلت، ولمعرفة سبب عدم إرسال إحداها.
https://wbiztool.com/api/v1/message/status/{msg_id}/النص (Body): JSON أو حقول نموذج
ضع معرّف الرسالة في عنوان URL، مستبدلًا {msg_id} بقيمة msg_id التي أرجعها إرسال رسالة أو الإرسال إلى مجموعة أو الإرسال إلى عدة أرقام أو جدولة رسالة. مثال: https://wbiztool.com/api/v1/message/status/9817263/.
مثال سريع#
curl -X POST https://wbiztool.com/api/v1/message/status/9817263/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY"
}'import requests
msg_id = 9817263
response = requests.post(
f"https://wbiztool.com/api/v1/message/status/{msg_id}/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") == "Unknown message id":
print("No message with this ID in your workspace")
elif "status_text" not in result:
print("Request failed:", result.get("message", "no message in response"))
elif result["status"] == 1:
print("Sent")
elif result["status"] == 2:
print("Failed:", result["error"])
else:
print("Status:", result["status_text"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const msgId = 9817263;
const response = await fetch(`https://wbiztool.com/api/v1/message/status/${msgId}/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message === "Unknown message id") {
console.log("No message with this ID in your workspace");
} else if (!("status_text" in result)) {
console.error("Request failed:", result.message ?? "no message in response");
} else if (result.status === 1) {
console.log("Sent");
} else if (result.status === 2) {
console.log("Failed:", result.error);
} else {
console.log("Status:", result.status_text);
}<?php
$msgId = 9817263;
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
];
$ch = curl_init("https://wbiztool.com/api/v1/message/status/{$msgId}/");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') === 'Unknown message id') {
echo 'No message with this ID in your workspace';
} elseif (!isset($result['status_text'])) {
echo 'Request failed: ' . ($result['message'] ?? 'no message in response');
} elseif ($result['status'] === 1) {
echo 'Sent';
} elseif ($result['status'] === 2) {
echo 'Failed: ' . $result['error'];
} else {
echo 'Status: ' . $result['status_text'];
}استبدل 12345 وYOUR_API_KEY بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.
معاملات الطلب#
URL
msg_idintegerمطلوبمعرّف الرسالة، كجزء من مسار عنوان URL. يجب أن يكون عددًا صحيحًا وأن ينتمي إلى مساحة العمل الخاصة بمفتاح API.
الجسم
client_idintegerمطلوبمعرّف العميل في API (API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).
api_keystringمطلوبمفتاح API الخاص بك من الصفحة نفسها.
استخدام مكتبة العميل الرسمية#
تستدعي مكتبة Python نقطة النهاية هذه نيابةً عنك.
from wbiztool_client import WbizToolClient
client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)
result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))تُرجع المكتبة الحقول نفسها التي يُرجعها API، لذا فإن result["status"] هي حالة الرسالة، وليست مؤشرًا على نجاح الطلب. تُطلق أخطاء المصادقة الاستثناء requests.HTTPError؛ اقرأ السبب باستخدام e.response.json()["message"].
الاستجابة#
تُرجع نقطة النهاية HTTP 200 مع الحالة الحالية للرسالة:
{
"message": "Sent",
"status": 1,
"status_text": "Sent",
"error": ""
}
رسالة فاشلة:
{
"message": "Failed",
"status": 2,
"status_text": "Failed",
"error": "Phone number invalid"
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | رمز حالة الرسالة. راجع الجدول أدناه. |
status_text | string | اسم الحالة: Created أو Sent أو Failed أو Cancelled أو Expired. |
message | string | القيمة نفسها الموجودة في status_text. |
error | string or null | سبب فشل الرسالة. موجود دائمًا؛ ويكون فارغًا ("" أو null) عند عدم وجود خطأ. |
قيم الحالة#
status | status_text | المعنى |
|---|---|---|
0 | Created | في قائمة الانتظار أو مجدولة، بانتظار الإرسال. |
1 | Sent | أُرسلت من رقم WhatsApp الخاص بك. |
2 | Failed | تعذّر إرسالها، أو انقطع الإرسال. يوضّح error السبب. إذا كانت قيمة error هي Sending was interrupted and may have been delivered. Check WhatsApp before resending.، فقد تكون الرسالة قد وصلت إلى المستلم بالفعل، لذا لا تُعِد إرسالها تلقائيًا. |
3 | Cancelled | أُلغيت قبل إرسالها، مثلًا باستخدام إلغاء رسالة. |
4 | Expired | لم تُرسَل قبل المهلة المحددة في expire_after_seconds. |
Sent هي حالة النجاح النهائية. لا تُبلغ نقطة النهاية هذه عمّا إذا كانت الرسالة قد سُلّمت إلى الهاتف أو قُرئت.
أمثلة على قيم error للرسائل الفاشلة: Phone number invalid، Group not found، Image Url Error، File Url Error، Blocked Contact، File exceeds WhatsApp size limit (…)، File type not supported، Sending was interrupted and may have been delivered. Check WhatsApp before resending.
الأخطاء#
{
"message": "Unknown message id",
"status": 0,
"status_text": "pending",
"error": "Invalid message id"
}
| الرسالة | طريقة الإصلاح |
|---|---|
Unknown message id | لا توجد رسالة بهذا المعرّف في مساحة العمل الخاصة بمفتاح API. تحقّق من المعرّف ومن أنك تستخدم مفتاحًا من مساحة العمل نفسها. |
Auth Error | أرسل client_id وapi_key كليهما. جسم JSON غير الصالح (مثلًا بسبب فاصلة زائدة في النهاية) يُرجع أيضًا Auth Error. |
Invalid Client Id | أرسل client_id كرقم. يُرجَع مع HTTP 403. |
Auth Error: invalid api key | تأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. يُرجَع مع HTTP 400. |
نصائح#
- فضّل webhooks للتحديثات الفورية: مرّر
webhookعند إرسال الرسالة، وسيُعلمك Wbiztool عند إرسالها أو فشلها، فلا تحتاج إلى الاستعلام المتكرر. الرسائل الملغاة والمنتهية الصلاحية لا تستدعي webhook، لذا تحقّق منها هنا. - الاستعلام المتكرر: إذا كنت تستعلم بشكل متكرر، فتوقف بمجرد أن تصبح قيمة
statusغير0. اترك بضع ثوانٍ بين كل فحص وآخر. - رسائل كثيرة دفعة واحدة: للتحقق من رسائل يوم كامل، استخدم سجل الرسائل بدلًا من استدعاء نقطة النهاية هذه لكل معرّف.
- تُحذف الرسائل القديمة: الرسائل المرسلة والفاشلة والملغاة والمنتهية الصلاحية التي لم يطرأ عليها تغيير لمدة 90 يومًا تقريبًا تُرجع
Unknown message id. وكذلك الرسائل التي لا تزال في قائمة الانتظار بعد 90 يومًا من إنشائها أو جدولتها، على رقم غير متصل أو محذوف. - التكاملات القديمة: الطلب
POST /api/v1/msg_status/معmsg_idفي الجسم مهمل (deprecated). وهو يُرجع الحقول نفسها. ويقبل أيضًاGETمعclient_idوapi_keyوmsg_idفي سلسلة الاستعلام (query string)، ما يكشف مفتاح API في عناوين URL والسجلات. انتقل إلى نقطة النهاية هذه.
