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

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

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

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

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

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:

{
  "id":                  "01c45011-d803-4eb0-a762-3228a4c392f3",
  "status":              "delivered",
  "agent_id":            "12345678-1234-1234-1234-123456789012",
  "to":                  "",
  "type":                "template",
  "platform_message_id": "wamid.EXAMPLE_PLACEHOLDER_FROM_META_REPLACE_AT_RUNTIME==",
  "created_at":          "2026-04-30T09:18:31Z",
  "sent_at":             "2026-04-30T09:18:32Z",
  "failed_at":           null
}

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

statusالمعنى
queuedمقبول من مجيب؛ لم يُسلَّم لميتا بعد
sentميتا أكّدت الاستلام — platform_message_id معبّأ الآن
deliveredميتا أكّدت التسليم لجهاز العميل
readالعميل فتح الرسالة (فقط إن كانت إيصالات القراءة مُمكَّنة عنده)
failedفشل الإرسال في مرحلة ما — راجع failed_at للطابع الزمني

الحالة تتحرّك للأمام فقط — بمجرد delivered، تبقى delivered أو تتقدّم إلى read. لا تتراجع إلى sent.

ما platform_message_id؟​

wamid ميتا للرسالة. يكون null بينما الحالة queued؛ يُعبَّأ بمجرد بلوغ الحالة sent أو لاحقة. استخدمه للمرجعية في سجلات 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 لتفادي تسريب وجود الرسائل عبر المنظمات)
  • شوّهت العنوان — المعرّفات يجب أن تكون UUIDs صالحة

أسئلة شائعة​

لماذا to فارغ؟​

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

لماذا sent_at معبّأ لكن failed_at أيضاً null على رسالة failed؟​

sent_at يُعبَّأ عندما مجيب أرسل الطلب لميتا — مستقل عمّا إذا قبلتها ميتا. إن رفضت ميتا التسليم لاحقاً، يُعبَّأ failed_at وتصبح status هي failed، لكن sent_at يبقى كطابع التسليم الأصلي. لاكتشاف فشل نهائي، تفرّع على status === "failed"، وليس على ما إذا كان failed_at فارغاً.

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

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

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

نعم. كل نقاط /v1/ تتشارك ميزانية المفتاح. راجع حدود المعدّل للتفاصيل.

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

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