إنتقل إلى المحتوى الرئيسي

استعلام حالة رسالة واتساب

يُعيد الحالة الحالية لرسالة سبق إرسالها عبر الواجهة العامة. استخدمه لتتبّع تطوّر التسليم — queued → sent → delivered → read (أو failed).

أي نقطة أستدعي؟​

GET إلى /v1/whatsapp/messages/{id} عبر HTTPS، حيث id هو معرّف الرسالة المُعاد من استدعاء سابق لـإرسال رسالة أو إرسال قالب. تحتاج إلى النطاق whatsapp:send، وهو نطاق نقطتي الإرسال نفسه، ويحمله كل مفتاح اليوم. والمفتاح المقيّد ببعض الوكلاء لا يقرأ إلا الرسائل المُرسَلة عبر هؤلاء الوكلاء.

GET /v1/whatsapp/messages/{id}

كيف يبدو الطلب؟​

curl https://api.mojeeb.app/v1/whatsapp/messages/01c45011-d803-4eb0-a762-3228a4c392f3 \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

كيف تبدو استجابة النجاح؟​

HTTP 200 OK مع كائن الرسالة: حالتها الحالية status، وتفاصيل الإرسال الأصلي، وسبب الفشل حين يفشل التسليم. كل الحقول مع مثال في مرجع نقطة النهاية هذه، المُولَّد من عقد الواجهة نفسه فلا يتقادم أبداً.

ماذا تعني قيم الحالة؟​

statusالمعنى
queuedمقبول من مجيب؛ لم يُسلَّم لميتا بعد
sentميتا أكّدت الاستلام — platform_message_id معبّأ الآن
deliveredميتا أكّدت التسليم لجهاز العميل
readالعميل فتح الرسالة (فقط إن كانت إيصالات القراءة مُمكَّنة عنده)
failedفشل الإرسال في مرحلة ما — failure_reason (ثابت) يوضّح السبب، ومعه failure_code وfailure_detail وfailure_href من ميتا حين تُبلغ ميتا عنها (النص الحر الذي رفضته ميتا لحظة الإرسال يظهر حالياً بقيمة Unknown دون رمز)، وfailed_at وقت الفشل

بمجرد delivered أو read، لا تعود الرسالة أبداً إلى sent. الاستثناء هو failed: يُعيد مجيب محاولة الإرسال الفاشل بضع مرات، لذا قد تتحوّل failed إلى sent بعد قليل. راجع هل failed نهائية؟

ما platform_message_id؟​

wamid ميتا للرسالة. يكون null بينما الحالة queued؛ يُعبَّأ بمجرد بلوغ الحالة sent، ويبقى خلال delivered وread. الرسالة التي فشلت قبل أن تقبلها ميتا ليس لها wamid. استخدمه للمرجعية في سجلات WhatsApp Business Manager من ميتا إن احتجت يوماً تتبّع مشكلة تسليم مع دعم ميتا.

كم مرّة ينبغي أن أستعلم؟​

لمعظم سير العمل، الاستعلام كل 5–10 ثوانٍ في الدقيقة الأولى يكفي — معظم الرسائل تصل sent خلال ثوانٍ. بعدها، أبطئ: استعلم كل 30 ثانية لتأكيد التسليم، أو توقّف تماماً إن لم تحتجه.

استعلامات الحالة تُحسَب ضد حد المعدّل (60/دقيقة/مفتاح افتراضياً)، فلا تُكثر على النقطة. إن احتجت تحديثات فورية لرسائل كثيرة، تواصل مع الدعم — قد نُضيف callbacks للتسليم عبر webhook في إصدار مستقبلي.

كيف تبدو استجابة "غير موجود"؟​

HTTP 404 Not Found مع الظرف القياسي:

{
  "error": {
    "type":           "not_found_error",
    "code":           "message_not_found",
    "message":        "No message found with the supplied id.",
    "correlation_id": "req_01KQ..."
  }
}

سترى هذا إن:

  • المعرّف غير موجود
  • المعرّف ينتمي لمنظمة مختلفة
  • الرسالة أُرسلت عبر وكيل لا يستطيع مفتاحك العمل عليه، حين يكون المفتاح مقيّداً ببعض الوكلاء

تُعيد الحالتان الأخيرتان 404 لا 403 عمداً، حتى لا يعرف المفتاح بوجود رسالة لا يحق له قراءتها.

المعرّف الذي ليس UUID صالحاً لا يصل إلى نقطة النهاية هذه: يُعيد 404 endpoint_not_found.

أسئلة شائعة​

هل تتضمّن استجابة الحالة المستلم ونوع الرسالة؟​

نعم. يُعيد to رقم المستلم بصيغة E.164 ويكون type إما text أو template، تماماً كما وردا في استجابة الإرسال، فتستطيع مطابقة الحالة بالرسالة التي أرسلتها دون الاحتفاظ بجدول خاص. قبل 11 أكتوبر 2026 كانت استجابة الحالة تُعيد to كنص فارغ؛ وقد سُدّت هذه الفجوة.

متى يُعبَّأ sent_at وfailed_at؟​

sent_at له قيمة فقط ما دامت status هي sent: يكون null أثناء queued، ويعود null بمجرد أن تصبح الرسالة delivered أو read أو failed، فلا تحتفظ به كوقت إرسال دائم. failed_at له قيمة كلما كانت status هي failed. تفرّع على status، وليس على أي طابع زمني فارغ.

هل failed نهائية؟​

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

هل يمكنني الاستعلام عن رسالة أرسلتها عبر لوحة التحكم وليس عبر الواجهة؟​

حالياً، لا تُعيد الواجهة إلا الرسائل المُرسَلة عبر الواجهة العامة. إرسال لوحة التحكم والرسائل المُعالَجة بـwebhook لا تُعاد. هذا مقصود في v1 — إظهار كل الرسائل سيكشف أنواعاً داخلية لم نلتزم بها.

هل هذه النقطة تُحسَب ضد حدود المعدّل؟​

نعم. استعلامات الحالة تستهلك ميزانية مفتاحك الافتراضية، التي تتشاركها كل نقاط النهاية التي تأخذ مفتاحاً عدا عرض قوالب واتساب، فحدّه الأقل يُحسب منفصلاً. راجع حدود المعدّل للتفاصيل.

هل يمكنني الاستعلام عن رسائل كثيرة دفعة واحدة؟​

ليس في v1. كل استعلام طلب منفصل. الاستعلام بالجملة محجوز كنقطة إضافية مستقبلية POST /v1/whatsapp/messages/lookup إن احتاج العملاء ذلك.