الحالات والأخطاء
دورة حياة الحملة وكل رسالة فيها، وكل أكواد الأخطاء.
حالات الحملة
in_reviewscheduledpreparingsendingcompletedpausedcancelledfailed| الحالة | المعنى |
|---|---|
draft | لم تبدأ: محفوظة في لوحة التحكم، أو أُعيدت من المراجعة (campaign.rejected). |
in_review | بانتظار موافقة فريق موجود (لمساحات العمل في وضع المراجعة). |
scheduled | بانتظار موعد scheduledAt. |
preparing | فحص المستلمين (إلغاء الاشتراك، الحدود، الأرقام) ووضع الرسائل في الطابور. |
sending | الرسائل تخرج بالسرعة المحددة للحملة. يصلك campaign.started. |
paused | متوقفة مؤقتًا، وpauseReason يوضح السبب. يصلك campaign.paused. |
completed | كل الرسائل أُرسلت أو تم تخطيها. يصلك campaign.completed. |
cancelled | أوقفتها الواجهة أو لوحة التحكم أو فريق موجود. يصلك campaign.cancelled. |
failed | تعذر تشغيلها، أو فشلت كل رسائلها لدى واتساب. يصلك campaign.failed. |
قد تصبح الحملة completed ثم failed: تكتمل عند تسليم آخر رسالة إلى واتساب، وتفشل إذا رفض واتساب
بعدها كل رسائلها.
ويعيد GET /campaigns/{id} الحملة كاملة:
{
"id": "cmp_9Xa4Lr",
"name": "Eid offer",
"status": "sending",
"pauseReason": null,
"reviewNote": null,
"source": "api",
"template": { "id": "tpl_8Kq2mZ", "name": "eid_offer", "language": "ar" },
"from": "num_3Fh7Ws",
"total": 900,
"pacing": { "mode": "steady", "overHours": 6 },
"counts": {
"pending": 400,
"queued": 20,
"sent": 120,
"delivered": 300,
"read": 40,
"failed": 5,
"skipped": 15,
"cancelled": 0,
"replied": 12
},
"scheduledAt": null,
"createdAt": "2026-11-20T10:00:00Z",
"launchedAt": "2026-11-20T10:00:02Z",
"completedAt": null
}تُحسب كل رسالة مرة واحدة بحالتها الحالية، وreplied يعدّ من ردّوا. وtotal هو كل الصفوف ما عدا
الملغاة. وsource إما api أو dashboard: يمكنك قراءة أي حملة في مساحة العمل.
حالات الرسالة
pendingqueuedsentdeliveredreadfailedskippedcancelled| الحالة | المعنى |
|---|---|
pending | قُبلت ولم تُفحص بعد. |
queued | فُحصت وتنتظر دورها. |
sent | سُلّمت إلى واتساب. |
delivered | وصلت إلى هاتف العميل. |
read | قُرئت (فقط إذا كان العميل يفعّل إيصالات القراءة). |
failed | رفضها واتساب. يحتوي error على code وtitle من ميتا. |
skipped | لم تُرسل بسبب قاعدة، وskipReason يوضح أيها. لا تكلف شيئًا. |
cancelled | أُلغيت الحملة قبل خروج هذه الرسالة. |
قيمة error.explanation دائمًا null حاليًا. ويعرض GET /campaigns/{id}/recipients الرسائل
بالترتيب الذي أرسلتها به، 100 في الصفحة افتراضيًا (limit حتى 500، وstatus للتصفية، وcursor
للصفحة التالية)، ومع كل منها externalId وname اللذان أرسلتهما.
عند رد العميل يُسجَّل repliedAt على المستلم (وتبقى الحالة read أو delivered) ويصلك
message.replied.
قد تتخطى الحالات بعض الخطوات
لا يبلغ واتساب دائمًا عن كل خطوة، وقد تصل التقارير بغير ترتيبها. قد تنتقل رسالة من sent إلى
read مباشرة. اعتمد على التوقيتات (sentAt وdeliveredAt وreadAt) ولا تُرجع الحالة إلى الخلف
أبدًا.
الأخطاء
كل الأخطاء لها الغلاف نفسه:
{
"error": {
"code": "template_not_approved",
"message": "Template order_shipped (ar) is not approved.",
"details": { "template": "order_shipped" }
}
}اعتمد في منطقك على code، أما message فهي للقراءة وقد تتغير، وdetails اختيارية.
| HTTP | code | ماذا تفعل |
|---|---|---|
| 400 | validation_failed | المحتوى ليس JSON صالحًا. |
| 400 | body_aborted | انقطع المحتوى قبل أن يكتمل. أرسله مرة أخرى. |
| 401 | invalid_api_key | راجع المفتاح وترويسة Authorization: Bearer. |
| 402 | plan_required | اشترك بمساحة العمل في باقة مدفوعة. |
| 403 | insufficient_scope | استخدم مفتاحًا له الصلاحية (details.missing). |
| 403 | publishable_key_not_allowed | استخدم مفتاحًا سريًا (mwg_sk_…). |
| 403 | workspace_unavailable | مساحة العمل موقوفة أو قيد الإغلاق. تواصل مع موجود. |
| 403 | campaigns_off | الحملات متوقفة في مساحة العمل هذه. |
| 403 | test_key_cannot_send | الطلب صحيح؛ أرسله بمفتاح حقيقي. |
| 404 | not_found | راجع المعرّف. المعرّفات تخص مساحة عمل واحدة. |
| 404 | template_not_found | لا يوجد قالب بهذا المعرّف، أو بهذا الاسم واللغة. |
| 404 | number_not_found | from ليس من أرقام واتساب الخاصة بك. |
| 409 | idempotency_conflict | استُخدم هذا Idempotency-Key مع محتوى آخر. استخدم مفتاحًا جديدًا. |
| 409 | idempotency_in_progress | الطلب الأول بهذا المفتاح ما زال يعمل. أعد المحاولة بعد قليل. |
| 409 | wrong_state | الحملة لا تقبل هذا الآن (الإلغاء بعد انتهائها). |
| 413 | too_large | المحتوى أكبر من 8 ميجابايت. قسّم القائمة. |
| 415 | unsupported_media_type | أرسل المحتوى مع Content-Type: application/json. |
| 422 | validation_failed | صحح الطلب (أو أضف Idempotency-Key)، وdetails يشير إلى الحقل. |
| 422 | missing_variables | أعط كل مستلم كل قيم القالب. |
| 422 | template_not_approved | اختر قالبًا معتمدًا (GET /templates?status=approved). |
| 422 | template_not_on_number | القالب غير معتمد على هذا الرقم (أو على أي رقم مربوط). |
| 422 | template_not_supported | الواجهة لا ترسل هذا النوع من القوالب (details.reason). |
| 422 | number_required | أكثر من رقم يستطيع إرساله: مرّر from (details.numbers). |
| 422 | no_valid_recipients | لا يوجد مستلم برقم واتساب صالح (details.skipped). |
| 422 | split_required | المستلمون أكثر من اللازم حتى بأبطأ سرعة. قسّم القائمة. |
| 422 | not_ready | يجب إصلاح شيء أولًا (details.blockers: no_number، quality…). |
| 429 | rate_limited | تجاوزت 600 طلب في الدقيقة بهذا المفتاح. انتظر Retry-After ثانية. |
| 500 | internal | مشكلة عندنا. أعد المحاولة مع التراجع والـ Idempotency-Key نفسه. |
أعد المحاولة فقط مع أخطاء 429 و409 idempotency_in_progress و5xx، بفاصل زمني متزايد وبنفس
Idempotency-Key. أما أخطاء 4xx الأخرى فستفشل بالطريقة نفسها حتى تغير الطلب.