انتقل إلى المحتوى
مستندات المطورينتجريبي

الحالات والأخطاء

دورة حياة الحملة وكل رسالة فيها، وكل أكواد الأخطاء.

حالات الحملة

in_reviewscheduledpreparingsendingcompleted
وقد تنتهي أو تتوقف عند:pausedcancelledfailed
الحالةالمعنى
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: يمكنك قراءة أي حملة في مساحة العمل.

حالات الرسالة

pendingqueuedsentdeliveredread
أو تنتهي بـ:failedskippedcancelled
الحالةالمعنى
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 اختيارية.

HTTPcodeماذا تفعل
400validation_failedالمحتوى ليس JSON صالحًا.
400body_abortedانقطع المحتوى قبل أن يكتمل. أرسله مرة أخرى.
401invalid_api_keyراجع المفتاح وترويسة Authorization: Bearer.
402plan_requiredاشترك بمساحة العمل في باقة مدفوعة.
403insufficient_scopeاستخدم مفتاحًا له الصلاحية (details.missing).
403publishable_key_not_allowedاستخدم مفتاحًا سريًا (mwg_sk_…).
403workspace_unavailableمساحة العمل موقوفة أو قيد الإغلاق. تواصل مع موجود.
403campaigns_offالحملات متوقفة في مساحة العمل هذه.
403test_key_cannot_sendالطلب صحيح؛ أرسله بمفتاح حقيقي.
404not_foundراجع المعرّف. المعرّفات تخص مساحة عمل واحدة.
404template_not_foundلا يوجد قالب بهذا المعرّف، أو بهذا الاسم واللغة.
404number_not_foundfrom ليس من أرقام واتساب الخاصة بك.
409idempotency_conflictاستُخدم هذا Idempotency-Key مع محتوى آخر. استخدم مفتاحًا جديدًا.
409idempotency_in_progressالطلب الأول بهذا المفتاح ما زال يعمل. أعد المحاولة بعد قليل.
409wrong_stateالحملة لا تقبل هذا الآن (الإلغاء بعد انتهائها).
413too_largeالمحتوى أكبر من 8 ميجابايت. قسّم القائمة.
415unsupported_media_typeأرسل المحتوى مع Content-Type: application/json.
422validation_failedصحح الطلب (أو أضف Idempotency-Key)، وdetails يشير إلى الحقل.
422missing_variablesأعط كل مستلم كل قيم القالب.
422template_not_approvedاختر قالبًا معتمدًا (GET /templates?status=approved).
422template_not_on_numberالقالب غير معتمد على هذا الرقم (أو على أي رقم مربوط).
422template_not_supportedالواجهة لا ترسل هذا النوع من القوالب (details.reason).
422number_requiredأكثر من رقم يستطيع إرساله: مرّر from (details.numbers).
422no_valid_recipientsلا يوجد مستلم برقم واتساب صالح (details.skipped).
422split_requiredالمستلمون أكثر من اللازم حتى بأبطأ سرعة. قسّم القائمة.
422not_readyيجب إصلاح شيء أولًا (details.blockers: no_number، quality…).
429rate_limitedتجاوزت 600 طلب في الدقيقة بهذا المفتاح. انتظر Retry-After ثانية.
500internalمشكلة عندنا. أعد المحاولة مع التراجع والـ Idempotency-Key نفسه.

أعد المحاولة فقط مع أخطاء 429 و409 idempotency_in_progress و5xx، بفاصل زمني متزايد وبنفس Idempotency-Key. أما أخطاء 4xx الأخرى فستفشل بالطريقة نفسها حتى تغير الطلب.

في هذه الصفحة