# إرسال رسائل واتساب الجماعية

> أرسل قالب واتساب معتمداً واحداً إلى أرقام كثيرة عبر الواجهة البرمجية العامة لمجيب، بقيم خاصة بكل مستلم، وتابع تسليم كل رسالة حتى تنتهي الرسالة الجماعية.

الرسالة الجماعية ترسل قالباً معتمداً واحداً من أحد أرقام واتساب لديك إلى أشخاص كثيرين دفعة واحدة، كما تفعل صفحة [رسائل واتساب الجماعية](/docs/channels/whatsapp-broadcasts) في لوحة التحكم. وعبر الواجهة البرمجية العامة تستطيع أنظمتك إرسال واحدة، ثم متابعة كل رسالة حتى تُسلَّم أو تُقرأ. والرسائل الجماعية متاحة في الباقات التي تشملها.

## كيف أرسل رسالة جماعية؟

أرسل بـ `POST` القالب و`id` قناة رقم واتساب والمستلمين:

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/broadcasts \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eid-offer-2026" \
  -d '{
    "name": "Eid offer",
    "connection_id": "YOUR_CONNECTION_ID",
    "template": { "name": "eid_offer", "language": "ar" },
    "parameters": { "2": "EID20" },
    "recipients": [
      { "phone": "+201001234567", "name": "Sara", "parameters": { "1": "Sara" } },
      { "phone": "+201001234568", "name": "Omar", "parameters": { "1": "Omar" } }
    ]
  }'
```

يكون الجواب `201` مع الرسالة الجماعية بالحالة `status: sending`، ويرسل مجيب الرسائل في الخلفية. أرسل `Idempotency-Key` كي لا تُرسل إعادةُ المحاولة بعد انتهاء المهلة الرسالةَ الجماعية مرتين؛ راجع [الإعادة الآمنة](../idempotency). وكل الحقول في [مرجع إرسال رسالة جماعية](../api-reference/send-broadcast).

## كيف أعطي كل مستلم قيمه الخاصة؟

تملأ `parameters` متغيّرات جسم القالب للجميع، بمفاتيح مثل `body.parameters` في [عرض قوالب واتساب](./list-templates). وتعلو `parameters` الخاصة بالمستلم عليها لذلك المستلم، فيجتمع رمز مشترك واسم شخصي في رسالة واحدة. ويحتاج كل مستلم إلى كل قيم الجسم، من هذه أو تلك.

## أي القوالب يمكن إرسالها جماعياً؟

القالب المعتمد الذي لا يحمل رأسه متغيّراً، ولا تحتاج أزراره قيمة لكل إرسال. فالرسالة الجماعية تملأ الجسم وحده: يبقى للرأس الصورة أو الفيديو أو المستند الذي اعتُمد به، وتبقى الروابط والردود السريعة كما هي. والقالب الذي يحتاج أكثر من ذلك يُرفض بـ `422 template_not_broadcastable`؛ فأرسله واحداً واحداً عبر [إرسال قالب واتساب](./send-template). ويُرفض كذلك القالب الذي رأسه موقع جغرافي، لأن مجيب لا يستطيع إرساله بعد.

## كيف أتابع رسالة جماعية؟

اقرأها بـ `GET` على `id` الخاص بها ([جلب رسالة جماعية](../api-reference/get-broadcast)). تتبع أعدادها كل رسالة كما يبلغ عنها واتساب: يشمل `sent_count` الرسائل المسلَّمة والمقروءة، ويشمل `delivered_count` المقروءة. وحين لا يبقى ما يُرسل تصبح `status` بقيمة `completed`. ولرسالة كل مستلم، اعرض [المستلمين](../api-reference/list-broadcast-recipients)؛ و`?status=failed` يعرض الرسائل الفاشلة، مع السبب في `failure_detail`، وهو عادةً جملة ميتا نفسها. وقد تتغيّر صياغته، فاعرضه على شخص ولا تبنِ عليه منطقاً.

## كيف أعيد إرسال الرسائل الفاشلة؟

أرسل `POST` إلى `retry` الخاص بالرسالة الجماعية بعد انتهائها، فيعيد مجيب إرسال القالب إلى المستلمين الذين فشلت رسائلهم. والرسالة الجماعية التي ما زالت تُرسل تجيب بـ `409 broadcast_still_sending`: انتظر حتى تتغيّر `status`، ثم أعد المحاولة. وقد تبقى الرسالة الجماعية التي قطعتها إعادة تشغيل بالحالة `sending`؛ فتواصل مع الدعم حينها. ويُفحص القالب من جديد، فالقالب الذي أُوقف أو تغيّر بعد الإرسال يُرفض بـ `422` قبل أن يُرسل شيء. وإعادة رسالة جماعية `paused` ترسل أيضاً إلى المستلمين الذين لم يصلهم الإرسال. وإن فشلت الرسائل لأن العميل حظر الرقم أو ليس على واتساب، فستفشل إعادة المحاولة كذلك. راجع [مرجع إعادة الإرسال](../api-reference/retry-broadcast).

## ما الذي قد يحدث خطأ؟

- `403 feature_not_available`: باقتك لا تشمل الرسائل الجماعية.
- `404 not_found`: `connection_id` ليس من أرقام واتساب لدى الوكيل، أو الرسالة الجماعية ليست للوكيل.
- `422 template_not_found` (مع `available_templates`، أسماء قوالب الرقم) أو `template_not_found_for_language` (مع `available_languages`) أو `template_not_approved` أو `template_not_broadcastable`: اختر قالباً آخر.
- `409 broadcast_still_sending`: إعادة إرسال قبل انتهاء الرسالة الجماعية.
- `422 invalid_request`: مستلم تنقصه قيمة في الجسم (ويسمّيه `param`)، أو الجمهور أكبر من حد الرسائل اليومي لرقم واتساب. قسّم القائمة، أو انتظر حتى ترفع ميتا الحد.
- `422 invalid_request_body`: رقم ليس بصيغة E.164، مثل `+201001234567`.

وتسرد [الأخطاء](../errors) كل الرموز.

## أسئلة شائعة

### هل تصل الرسالة الجماعية إلى من لم يراسلني من قبل؟

نعم، كأي قالب: يمكن إرسال القالب في أي وقت، داخل نافذة الـ24 ساعة أو خارجها. ولا ترسل إلا لمن وافق على تلقّي رسائلك؛ فميتا تخفض جودة الرقم وحدوده حين يحظره المستلمون أو يبلغون عنه.

### أين تذهب ردود العملاء؟

إلى محادثتهم مع الوكيل، التي تبدؤها الرسالة الجماعية إن لم تكن لهم محادثة، فيرد عليهم الذكاء الاصطناعي كأي رسالة أخرى.

### ماذا تعني `paused`؟

توقّف مجيب عن الإرسال في المنتصف، كما عند إعادة التشغيل، وما زال المستلمون الذين لم يصلهم الإرسال بالحالة `pending`. وإن فشلت بعض الرسائل، فإعادة الإرسال تصل إليهم وإلى من حالتهم `pending`. أما الرسالة الجماعية الموقوفة التي لم تفشل فيها رسالة فلا يمكن إعادتها، فتواصل مع الدعم لاستئنافها.

### هل يستطيع مساعد ذكاء اصطناعي إرسال رسائل جماعية؟

نعم. عبر [خادم MCP](../mcp) يستطيع المساعد إرسال رسالة جماعية وقراءة الرسائل الجماعية ومستلميها. وقد يصل استدعاء واحد إلى آلاف الأشخاص، فاستخدم عميلاً يسألك قبل تنفيذه، وراجع المستلمين والقالب قبل أن توافق.

### ما النطاقات التي تحتاجها هذه الاستدعاءات؟

`broadcasts:write` للإرسال وإعادة الإرسال، و`broadcasts:read` للقراءة. ويحملهما كل مفتاح اليوم؛ راجع [التوثيق](../authentication).