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

> استعلام عن حالة تسليم رسالة واتساب سبق إرسالها عبر GET /v1/whatsapp/messages/{id} — تصنيف الحالات، wamid من ميتا، وإرشادات الاستعلام.

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

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

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

```
GET /v1/whatsapp/messages/{id}
```

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

```bash
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`، وتفاصيل الإرسال الأصلي، وسبب الفشل حين يفشل التسليم. كل الحقول مع مثال في [مرجع نقطة النهاية هذه](../api-reference/get-whats-app-message-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` نهائية؟](#هل-failed-نهائية)

## ما `platform_message_id`؟

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

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

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

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

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

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

```json
{
  "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 — إظهار كل الرسائل سيكشف أنواعاً داخلية لم نلتزم بها.

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

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

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

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