API الرسائل
API سجل الرسائل
احصل على قائمة بالرسائل في مساحة العمل الخاصة بك لنطاق تاريخ محدد، مع حالة كل رسالة. استخدمه لمطابقة ما أُرسل، أو لإعداد التقارير، أو للعثور على الرسائل الفاشلة لإعادة المحاولة.
https://wbiztool.com/api/v1/report/النص (Body): JSON (مطلوب للصفحات بعد الأولى) أو حقول نموذج
يشمل السجل كل رسالة في مساحة العمل الخاصة بمفتاح API، سواء أُرسلت عبر API أو لوحة التحكم أو حملة. تأتي النتائج بمعدل 200 رسالة في الصفحة، من الأقدم إلى الأحدث. البيانات نفسها متاحة في صفحة التقارير.
مثال سريع#
curl -X POST https://wbiztool.com/api/v1/report/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": 1
}'import requests
page = 1
history = []
while True:
response = requests.post(
"https://wbiztool.com/api/v1/report/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": page, # must be a JSON number, not a string
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") != "Success" or "total" not in result:
print("Failed:", result.get("message", "no message in response"))
break
history.extend(result["history"])
if page * 200 >= result["total"]:
break
page += 1
failed = [m for m in history if m["message_status"] == "Failed"]
print(len(history), "messages,", len(failed), "failed")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const history = [];
let page = 1;
while (true) {
const response = await fetch("https://wbiztool.com/api/v1/report/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
start_date: "01-09-2026",
end_date: "08-09-2026",
page, // must be a JSON number, not a string
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message !== "Success" || !("total" in result)) {
console.error("Failed:", result.message ?? "no message in response");
break;
}
history.push(...result.history);
if (page * 200 >= result.total) break;
page += 1;
}
const failed = history.filter((m) => m.message_status === "Failed");
console.log(`${history.length} messages, ${failed.length} failed`);<?php
$history = [];
$page = 1;
do {
$ch = curl_init('https://wbiztool.com/api/v1/report/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'start_date' => '01-09-2026',
'end_date' => '08-09-2026',
'page' => $page, // an integer, so json_encode sends a number
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') !== 'Success' || !isset($result['total'])) {
echo 'Failed: ' . ($result['message'] ?? 'no message in response');
break;
}
$history = array_merge($history, $result['history']);
$page++;
} while (($page - 1) * 200 < $result['total']);
echo count($history) . ' messages';استبدل 12345 وYOUR_API_KEY بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.
معاملات الطلب#
المصادقة
client_idintegerمطلوبمعرّف العميل في API (API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).
api_keystringمطلوبمفتاح API الخاص بك من الصفحة نفسها.
عوامل التصفية
start_datestringمطلوبأول يوم يُشمل، بالصيغة
DD-MM-YYYY، مثل01-09-2026.end_datestringمطلوبنهاية النطاق، بالصيغة
DD-MM-YYYY. هذا اليوم نفسه غير مشمول. راجع نطاق التاريخ.whatsapp_clientintegerاختيارييُرجع فقط الرسائل المرسلة من رقم WhatsApp هذا، باستخدام معرّفه من إعدادات WhatsApp. احذفه للحصول على الرسائل من كل أرقامك.
pageintegerاختياريرقم الصفحة، بدءًا من
1(القيمة الافتراضية). تحتوي كل صفحة على 200 رسالة كحد أقصى. أرسله كرقم JSON. القيمة0أو أي رقم سالب تُرجعtotalمعhistoryفارغ.
نطاق التاريخ#
تُقرأ التواريخ على أنها منتصف الليل عند بداية ذلك اليوم بتوقيت الهند القياسي (IST، UTC+5:30)، وتُطابَق الرسائل حسب وقت إنشائها (دخولها قائمة الانتظار أو جدولتها)، لا حسب وقت إرسالها. يمتد النطاق من الساعة 00:00 في start_date حتى الساعة 00:00 في end_date، وبالتالي:
-
"start_date": "01-09-2026", "end_date": "08-09-2026"يُرجع الأيام من 1 إلى 7 سبتمبر. يوم 8 سبتمبر غير مشمول. - للحصول على يوم واحد، اضبط
end_dateعلى اليوم التالي:"start_date": "15-09-2026", "end_date": "16-09-2026". - إذا كان التاريخان متطابقين، فلن تحصل على أي رسائل.
التقسيم إلى صفحات#
تحتوي كل استجابة على total، وهو عدد الرسائل في النطاق كله، وعلى 200 رسالة منها كحد أقصى في history. اطلب قيمة page تساوي 2 ثم 3 وهكذا، حتى يصبح page × 200 مساويًا لـ total أو أكبر منه.
الاستجابة#
يُرجع الطلب الناجح HTTP 200:
{
"message": "Success",
"status": 0,
"total": 3,
"history": [
{ "id": 9817263, "msg_type": "Text", "contact": "919876543210", "message_status": "Sent" },
{ "id": 9817264, "msg_type": "File", "contact": "919812345670", "message_status": "Failed" },
{ "id": 9817265, "msg_type": "Image", "contact": "Sales Team Mumbai", "message_status": "Pending" }
]
}
| الحقل | النوع | الوصف |
|---|---|---|
message | string | Success عند نجاح الطلب، وإلا نص الخطأ. |
status | integer | دائمًا 0. لا تستخدمه لاكتشاف النجاح. |
total | integer | عدد الرسائل في نطاق التاريخ عبر كل الصفحات. يظهر عند النجاح فقط. |
history | array | حتى 200 رسالة في هذه الصفحة، من الأقدم إلى الأحدث. يكون فارغًا عند حدوث خطأ. |
history[].id | integer | معرّف الرسالة، وهو نفس msg_id الذي أُرجع عند إرسالها. |
history[].msg_type | string | Text أو Image أو File. |
history[].contact | string | رقم هاتف المستلم مع رمز الدولة، أو اسم المجموعة لرسائل المجموعات. |
history[].message_status | string | راجع الجدول أدناه. |
قيم حالة الرسالة#
message_status | المعنى |
|---|---|
Pending | في قائمة الانتظار أو مجدولة، ولم تُرسَل بعد (الحالة 0). |
Sent | أُرسلت من رقم WhatsApp الخاص بك (الحالة 1). |
Delivered | قيمة محجوزة، لا تُرجَع حاليًا. |
Read | قيمة محجوزة، لا تُرجَع حاليًا. |
Failed | تعذّر إرسالها، أو انقطع الإرسال (الحالة 2). استخدم حالة الرسالة لمعرفة error. |
Cancelled | أُلغيت قبل إرسالها (الحالة 3). |
Expired | لم تُرسَل قبل المهلة المحددة في expire_after_seconds (الحالة 4). |
لا تُسجَّل علامات التسليم والقراءة حاليًا، لذا تظهر الرسائل المرسلة دائمًا بالحالة Sent. القيمتان Delivered وRead محجوزتان؛ وإذا ظهرتا يومًا ما، فاعتبرهما Sent.
الأخطاء#
تُرجع الأخطاء HTTP 200 مع status بقيمة 0، ما لم يُذكر خلاف ذلك:
{ "message": "Error", "status": 0, "history": [] }
| الرسالة | طريقة الإصلاح |
|---|---|
Error | start_date أو end_date مفقود أو ليس بالصيغة DD-MM-YYYY، أو أن جسم JSON غير صالح (غالبًا بسبب فاصلة زائدة في النهاية)، أو أن الطلب لم يكن POST. |
Auth Error | أرسل client_id وapi_key كليهما. |
Invalid Client Id | أرسل client_id كرقم. يُرجَع مع HTTP 403، بدون history. |
Auth Error: invalid api key | تأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. يُرجَع مع HTTP 400، بدون history. |
Demo Account can not access apis | استخدم حسابًا عاديًا. |
نصائح#
- اسحب السجل على نطاقات صغيرة: يومًا أو أسبوعًا في كل مرة، ليبقى عدد الصفحات قليلًا.
- اعثر على الرسائل الفاشلة: صفِّ
historyبحثًا عنFailed، ثم استدعِ حالة الرسالة مع كلidلمعرفة سبب الفشل. قبل إعادة المحاولة، تحقّق منerror: تعنيSending was interrupted and may have been delivered…أن الرسالة قد تكون وصلت إلى المستلم بالفعل. - تُحذف الرسائل القديمة: الرسائل التي وصلت إلى حالة نهائية ولم تتغير لمدة 90 يومًا تقريبًا قد تُحذف ولا تعود تظهر هنا، وكذلك الرسائل التي لا تزال في قائمة الانتظار بعد 90 يومًا من إنشائها أو جدولتها، على رقم غير متصل أو محذوف.
- التتبع الفوري: للتفاعل مع الرسائل فور إرسالها، مرّر
webhookعند إرسال الرسالة بدلًا من الاستعلام المتكرر من نقطة النهاية هذه.
