# عرض قوالب واتساب

> اعرض قوالب رسائل رقم واتساب، مع حالة كل منها وما يجب أن يملأه الإرسال، عبر GET /v1/agents/{agentId}/connections/{connectionId}/whatsapp-templates، قبل إرسال أحدها عبر الواجهة البرمجية العامة لمجيب.

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

## كيف أعرض قوالب رقم ما؟

اعثر أولاً على قناة الرقم: اعرض قنوات الوكيل عبر `GET /v1/agents/{agentId}/connections` وخذ `id` القناة التي قيمة `platform` فيها `whatsapp` (راجع [القنوات والمتابعات](../agents/channels-and-follow-ups)). ثم استدعِ:

```bash
curl https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/connections/YOUR_CONNECTION_ID/whatsapp-templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

تحصل على عنصر لكل نسخة لغة من كل قالب، مرتّبة حسب الاسم ثم اللغة. وكل الحقول في [مرجع عرض قوالب رقم واتساب](../api-reference/list-whats-app-templates).

## أي القوالب أستطيع إرسالها؟

تلك التي `status` فيها `approved` فقط. والقوالب في كل حالة أخرى، مثل `pending` و`rejected` و`paused` و`disabled`، تظهر في القائمة أيضاً، لترى لماذا لا يخرج أحدها؛ ويحمل القالب المرفوض سبب ميتا في `rejected_reason`. وكل نسخة لغة عنصر مستقل بحالة خاصة به، فقد يكون القالب معتمداً بلغة وما يزال قيد المراجعة بلغة أخرى.

ولا يمنعك مجيب من إرسال قالب غير معتمد: يُقبل الإرسال ثم يفشل لدى ميتا. لذا تحقّق من الحالة هنا أولاً.

## كيف أحوّل قالباً من القائمة إلى إرسال؟

انقل ما تقوله القائمة إلى [`POST /v1/whatsapp/templates`](./send-template):

- `name` و`language` يصبحان `template.name` و`template.language`.
- `body.parameters` هي مفاتيح `template.parameters`، و`header.parameters` في رأس نصّي هي مفاتيح `template.header_parameters`. ويحتاج كل مفتاح إلى قيمة.
- الرأس من نوع صورة أو فيديو أو مستند يقبل `template.header_media_url` اختيارياً.
- كل زر له `send_field` يصبح عنصراً في `template.buttons`: الـ `index` الخاص به، وقيمته في الحقل الذي يسمّيه `send_field`. ويمكنك ألّا ترسل الزر الذي قيمة `required` فيه `false`.

مثلاً، قالب في جسمه متغيّران مرقّمان، وزره الأول رابط URL فيه متغيّر:

```bash
curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":       "order_shipped",
      "language":   "en_US",
      "parameters": { "1": "Sara", "2": "EG-A12345" },
      "buttons":    [ { "index": 0, "url_suffix": "orders/A12345" } ]
    }
  }'
```

`from` هو رقم واتساب بصيغة `+` تليها أرقام فقط، مثل `+15557654321`. ويحمل `handle` في القناة الرقم كما تعرضه ميتا، وقد يحتوي على مسافات أو شرطات (`+20 100 219 4693`): أبقِ `+` والأرقام فقط، وإلا فسيُعيد الإرسال `422 invalid_from_phone`.

## متغيّرات مرقّمة أم مسمّاة؟

يخبرك `parameter_format` بذلك. القالب `positional` فيه متغيّرات مرقّمة مثل `{{1}}`: أرسل المفاتيح `"1"` و`"2"` وهكذا، بالترتيب الذي تسردها به `body.parameters`. والقالب `named` فيه متغيّرات مثل `{{customer_name}}`: أرسل تلك الأسماء مفاتيح. وقيمته `null` حين لا يحتوي الرأس ولا الجسم على أي متغيّر.

## كم مرة يجب أن أعرض القوالب؟

احتفظ بالقائمة بدلاً من قراءتها قبل كل إرسال، واقرأها مجدداً بعد أن تتغيّر قوالبك. ولأن كل استدعاء يقرأ من ميتا، فلنقطة النهاية هذه حد معدّل أقل خاص بها، يحمي حصة ميتا التي يعتمد عليها إرسالك؛ راجع [حدود المعدّل](../rate-limits).

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

- `404 not_found`: القناة ليست من قنوات الوكيل، أو ليست رقم واتساب.
- `409 connection_inactive`: الرقم مفصول. أعد ربطه من لوحة التحكم.
- `409 connection_needs_reconnection`: لم تعد ميتا تقبل صلاحية الوصول للرقم (أُلغيت أو انتهت، أو غادر الرقم حساب واتساب للأعمال الخاص به). أعد ربطه من لوحة التحكم؛ إعادة المحاولة لن تفيد.
- `503 meta_unavailable`: لم تُعِد ميتا القوالب (انقطاع، أو انتهاء المهلة، أو حد المعدّل لدى ميتا نفسها). أعد المحاولة بتراجع متصاعد.
- `429 rate_limit_exceeded`: انتظر المدة التي يذكرها `Retry-After`.

راجع [الأخطاء](../errors) للغلاف وكل الرموز.

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

### لماذا لا يظهر قالب في القائمة؟

القالب المحذوف لدى ميتا لا يظهر. أما القالب الجديد فيظهر بمجرد إرساله للمراجعة، بالحالة `pending`. والرقم الذي لديه مكتبة قوالب كبيرة جداً يعرض حتى الحد المذكور في صفحة المرجع.

### هل أستطيع إنشاء القوالب أو تعديلها عبر الواجهة البرمجية؟

ليس بعد. أنشئها وعدّلها من لوحة التحكم؛ راجع [قوالب واتساب](/docs/channels/whatsapp-templates).

### هل يمكن إرسال كل قالب معتمد عبر الواجهة البرمجية؟

أغلبها. أما القوالب ذات رأس الموقع الجغرافي، والقوالب الدوّارة (carousel)، وعروض الوقت المحدود، فلا يمكن ملؤها عبر الواجهة البرمجية بعد.

### هل يشمل استدعاء واحد كل أرقام واتساب لديّ؟

لا. كل استدعاء يعرض قوالب رقم واحد، فاستدعِه مرة لكل قناة واتساب.

### ما النطاق الذي يحتاجه؟

`whatsapp:read`، ويحمله كل مفتاح اليوم؛ راجع [التوثيق](../authentication).