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

API الرسائل

API سجل الرسائل

احصل على قائمة بالرسائل في مساحة العمل الخاصة بك لنطاق تاريخ محدد، مع حالة كل رسالة. استخدمه لمطابقة ما أُرسل، أو لإعداد التقارير، أو للعثور على الرسائل الفاشلة لإعادة المحاولة.

POSThttps://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
  }'

استبدل 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" }
  ]
}
الحقلالنوعالوصف
messagestring‏Success عند نجاح الطلب، وإلا نص الخطأ.
statusintegerدائمًا 0. لا تستخدمه لاكتشاف النجاح.
totalintegerعدد الرسائل في نطاق التاريخ عبر كل الصفحات. يظهر عند النجاح فقط.
historyarrayحتى 200 رسالة في هذه الصفحة، من الأقدم إلى الأحدث. يكون فارغًا عند حدوث خطأ.
history[].idintegerمعرّف الرسالة، وهو نفس msg_id الذي أُرجع عند إرسالها.
history[].msg_typestring‏Text أو Image أو File.
history[].contactstringرقم هاتف المستلم مع رمز الدولة، أو اسم المجموعة لرسائل المجموعات.
history[].message_statusstringراجع الجدول أدناه.

قيم حالة الرسالة#

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 عند إرسال الرسالة بدلًا من الاستعلام المتكرر من نقطة النهاية هذه.