# إنشاء قوالب واتساب وإدارتها

> أنشئ قوالب رسائل رقم واتساب وعدّلها واحذفها عبر الواجهة البرمجية العامة لمجيب، من الرأس النصي ورأس الوسائط إلى الأزرار وقوالب رموز التحقق، وتابع مراجعة ميتا حتى يصبح القالب قابلاً للإرسال.

القالب رسالة تعتمدها ميتا مسبقاً، فتستطيع إرسالها إلى العميل في أي وقت. وعبر الواجهة البرمجية العامة تستطيع أنظمتك إنشاء قوالب رقم واتساب وتعديلها وحذفها، كما في صفحة واتساب في لوحة التحكم. وتراجع ميتا كل قالب جديد وكل تعديل قبل أن يصبح قابلاً للإرسال.

## كيف أنشئ قالباً؟

اعثر على `id` قناة الرقم كما في [عرض القوالب](./list-templates)، ثم أرسل القالب بـ `POST`:

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/connections/YOUR_CONNECTION_ID/whatsapp-templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name":          "order_shipped",
    "language":      "en",
    "category":      "utility",
    "body":          "Hi {{1}}, your order {{2}} is on its way.",
    "body_examples": { "1": "Sara", "2": "A-100" },
    "footer":        "Acme Clinics",
    "buttons": [
      { "type": "url", "text": "Track order", "url": "https://example.com/track/{{1}}", "example": "A-100" }
    ]
  }'
```

يكون الجواب `201` مع القالب، وحالته عادةً `status: pending`. وكل الحقول في [مرجع إنشاء قالب](../api-reference/create-whats-app-template).

## كيف تعمل المتغيّرات والعيّنات؟

اكتب المتغيّرات بالأرقام `{{1}}` و`{{2}}` وهكذا بالترتيب، أو بأسماء بأحرف صغيرة مثل `{{first_name}}`، بأسلوب واحد في الرأس والجسم معاً. وتراجع ميتا القالب بقيم تجريبية، فأعطِ عيّنة لكل متغيّر: `body_examples` تربط كل متغيّر في الجسم بعيّنته، بمفاتيح مثل مفاتيح `parameters` في الإرسال (`"1"` أو `"first_name"`)، و`header.example` هي عيّنة المتغيّر الوحيد في الرأس النصي.

## كيف أضيف رأساً بصورة أو فيديو أو مستند؟

حدّد `header.format` وأعطِ `header.media_url`، وهو رابط https لملف تجريبي. ينزّله مجيب مرة واحدة ويسلّمه لميتا للمراجعة. وحين ترسل القالب تستطيع إرسال ملف مختلف عبر `template.header_media_url`. ويجب أن يجيب الرابط بالملف نفسه، ونوعُه في `Content-Type`، من عنوان عام؛ فإعادة التوجيه لا تُتّبع. ويذكر [المرجع](../api-reference/create-whats-app-template) أنواع الملفات والحجم الذي يقبله مجيب.

## ما الأزرار التي يمكن أن يحملها القالب؟

الردود السريعة، والروابط (`url`، وقد ينتهي بـ `{{1}}` يملؤه الإرسال)، ورقم هاتف واحد، وزر نسخ رمز واحد. أبقِ الردود السريعة معاً، قبل الأزرار الأخرى أو بعدها. أما رأس الموقع الجغرافي، والقوالب الدوّارة (carousel)، وعروض الوقت المحدود، وأزرار الكتالوج وFlow، فتُنشأ في WhatsApp Manager، لأن مجيب لا يستطيع إرسالها بعد.

## كيف أنشئ قالب رمز تحقق؟

اجعل `category` بقيمة `authentication`، وصِف زر الرمز في `otp`. يتيح `copy_code` للعميل نسخ الرمز، أما `one_tap` و`zero_tap` فيسلّمانه إلى تطبيقك على أندرويد المذكور في `supported_apps`. وتكتب ميتا الرسالة بنفسها بلغة القالب، ولا تختار أنت إلا إضافة سطر الأمان من عدمها ومتى ينتهي الرمز:

```json
{
  "name": "login_code",
  "language": "en",
  "category": "authentication",
  "otp": { "type": "copy_code", "add_security_recommendation": true, "code_expiration_minutes": 10 }
}
```

ولإرساله أعطِ الرمز في `"1"` الخاص بالجسم وفي `otp_code` الخاص بالزر؛ راجع [إرسال قالب واتساب](./send-template).

## كيف أعرف متى تعتمده ميتا؟

اقرأ القالب بـ `GET` على `id` الخاص به ([جلب قالب](../api-reference/get-whats-app-template)) حتى لا تبقى `status` بقيمة `pending`. القالب `approved` يمكن إرساله، والقالب `rejected` يذكر السبب في `rejected_reason`. وقد تستغرق مراجعة ميتا يوماً، فتحقّق كل بضع دقائق لا كل ثانية: نقاط نهاية القوالب تتشارك حد معدّل صغيراً تشرحه [حدود المعدّل](../rate-limits).

## كيف أعدّل قالباً؟

أرسل محتواه كاملاً بـ `PUT` إلى `id` الخاص به. تستبدل ميتا كل أجزاء القالب عند التعديل، فأرسل كل ما يجب أن يقوله لا التغيير وحده. ولا يتغيّر الاسم ولا اللغة؛ ولا ترسل `category` لتبقى كما هي. والرأس الذي فيه وسائط ويُرسل دون `media_url` يحتفظ بعيّنته، أما الرأس الذي يتغيّر نوعه فيحتاج `media_url`. وتسمح ميتا بتعديل القالب المعتمد مرة في اليوم وعشر مرات في الشهر، وتراجع كل تعديل؛ والمحتوى المطابق لما لدى ميتا لا يُرسل ولا يستهلك تعديلاً. أما قالب رمز التحقق، و`message_send_ttl_seconds`، و`media_url` الجديد، فتُعدّ تغييراً دائماً، لأن قائمة ميتا لا تعرضها للمقارنة. راجع [مرجع تعديل قالب](../api-reference/update-whats-app-template).

## كيف أحذف قالباً؟

احذفه بـ `DELETE` حسب `id`. يحذف هذا نسخة اللغة تلك وحدها، وتبقى لغاته الأخرى. وحذف قالب معتمد أو موقوف مؤقتاً يحجز اسمه لدى ميتا 30 يوماً، فأضف `?acknowledge_name_lock=true`؛ ودونه تجيب الواجهة بـ `409 template_delete_locks_name` مع التاريخ. ولا يمكن استعادة القالب المحذوف. راجع [مرجع حذف قالب](../api-reference/delete-whats-app-template).

## لماذا رُفض قالبي؟

لا يُرسل شيء إلى ميتا حتى يتّبع القالب قواعد ميتا التي يستطيع مجيب التحقق منها:

- `422 invalid_request_body`: جزء لا تقبله فئته، أو متغيّر دون عيّنة، أو أزرار بترتيب خاطئ. ويسمّي `param` الحقل، مثل `buttons[1].url`.
- `422 template_header_media_url_invalid`: لم يستطع مجيب تنزيل عيّنة الرأس؛ وتذكر الرسالة السبب.
- `422 template_rejected`: رفضت ميتا القالب، والرسالة هي سبب ميتا. والتعديل الذي لا تقبله ميتا، مثل فئة جديدة لقالب معتمد، يُرفض بالطريقة نفسها قبل أن يصل إليها.
- `409 template_name_taken`: لدى الرقم قالب بهذا الاسم بهذه اللغة.
- `409 template_status_not_allowed` أو `template_edit_limit_reached` أو `template_in_use_by_broadcast`: لا يمكن تغيير القالب الآن.

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

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

### هل أستطيع إعادة محاولة إنشاء انتهت مهلته؟

نعم. إن كان الأول قد وصل إلى ميتا، فستجيب إعادة المحاولة بـ `409 template_name_taken`، لأن الاسم صار موجوداً بتلك اللغة. اعرض القائمة لتجده. ولا يحتاج الإنشاء إلى `Idempotency-Key`.

### هل تظهر القوالب المنشأة عبر الواجهة في لوحة التحكم؟

نعم. القوالب محفوظة لدى ميتا في حساب واتساب للأعمال الخاص بالرقم، فتعرضها كلها صفحة واتساب في لوحة التحكم وWhatsApp Manager، أياً كانت طريقة إنشائها.

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

`whatsapp_templates:write` لإنشاء القوالب وتعديلها وحذفها، و`whatsapp:read` لقراءتها. ويحملهما كل مفتاح اليوم؛ راجع [التوثيق](../authentication).

### هل يستطيع مساعد ذكاء اصطناعي إنشاء القوالب؟

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