# واجهة برمجة تطبيقات قوالب WhatsApp

قوالب رسائل WhatsApp هي رسائل مكتوبة مسبقاً تمت الموافقة عليها للإرسال خارج نافذة المحادثة العادية التي تبلغ 24 ساعة — على سبيل المثال، رسالة ترحيب، أو تذكير بموعد، أو رسالة لإعادة التفاعل. تتيح لك واجهة برمجة التطبيقات هذه سرد القوالب وإنشائها وتعديلها وإرسالها للمراجعة والتحقق منها وحذفها وإرسالها برمجياً.

جميع المسارات أدناه نسبية إلى عنوان URL الأساسي لواجهة برمجة التطبيقات:

```
https://api.youraiconnector.com/v1
```

يجب مصادقة كل طلب. راجع [المصادقة](authentication.md) لمعرفة الطرق الأربع المقبولة. تستخدم الأمثلة الموجودة في هذه الصفحة ترويسة `X-API-Key` (ونموذجاً واحداً لمعامل الاستعلام لـ cURL).

::: note
**ملاحظة:** تعتمد القوالب على قناة WhatsApp Business API، لذا يتطلب هذا الجزء من واجهة برمجة التطبيقات كلاً من الوصول إلى واجهة برمجة التطبيقات وخطة تتضمن قنوات WhatsApp. وبدونها، يتم رفض الطلبات مع `403`.
:::


---

## العمل مع الحسابات الفرعية (الوكالات)


---

## حالات الموافقة

نظراً لأنه يجب مراجعة الرسائل المرسلة خارج محادثة مفتوحة من قبل WhatsApp أولاً، فإن كل قالب يحمل `status` موافقة:

| الحالة | المعنى |
|---|---|
| `draft` | تم إنشاؤه أو حفظه ولكن لم يتم إرساله للمراجعة بعد. لا يزال بإمكانك تعديله. |
| `received` | تم تقديمه وقبوله في قائمة انتظار المراجعة. |
| `pending` | قيد المراجعة. |
| `approved` | تمت الموافقة عليه للإرسال. |
| `rejected` | تم رفضه. يشرح حقل `rejection_reason` السبب؛ قم بإصلاحه، ثم أعد تقديمه. |

لا يمكن تعديل أو (إعادة) تقديم سوى القوالب ذات الحالة `draft` و `rejected`. بمجرد أن يصبح القالب `approved`، يتم قفله — قم بإنشاء قالب جديد إذا كنت بحاجة إلى إجراء تغييرات.

> **الموافقة التلقائية:** بعض القنوات لا تتطلب خطوة مراجعة خارجية. يتم تخزين القوالب التي تم إنشاؤها أو تقديمها لحملة على مثل هذه القناة كـ `approved` على الفور، بدون معرف محتوى (`sid`).

---

## القوالب في الحسابات المتصلة بـ Meta

تعمل نقاط النهاية هذه بنفس الطريقة بغض النظر عن اتصال WhatsApp الذي يعمل عليه حسابك، ولكن ما يحدث خلف الكواليس يختلف:

- في **اتصال WhatsApp المُدار**، يتم تسجيل القوالب لدى مزود المراسلة وتكون `sid` هي معرف المحتوى الخاص بالمزود (`HXXXXXXXX…`).
- في الحساب الذي يعمل رقمه على **حسابه الخاص في WhatsApp Business** (أي من خياري اتصال Meta)، يتم إنشاء القوالب ومراجعتها **في حساب WhatsApp Business ذلك** وتكون `sid` هي معرف القالب الخاص بـ Meta — وهو سلسلة رقمية مثل `"3394843740694756"`. لا تزال `status` تستخدم القيم الموجودة في الجدول أعلاه، ولا تزال `rejection_reason` تحمل شرح Meta.

توجد نقطتا نهاية إضافيتان لهذا الغرض: واحدة للاستعلام عن نوع الاتصال الذي تستخدمه، وأخرى لمطابقة قائمة قوالبك مع حساب WhatsApp Business الخاص بك. يتم استيراد القوالب الموجودة بالفعل في حساب WhatsApp Business إلى مكتبتك عن طريق المزامنة، لذا فإن `GET /whatsapp-templates` بعدها ستدرجها مثل أي قالب آخر.

### التحقق من الاتصال الذي تعمل عليه القوالب

`GET /whatsapp-templates/provider`

| الحقل | الوصف |
|---|---|
| `provider` | `twilio` عندما يتم تسجيل القوالب لدى مزود المراسلة المُدار، و `meta` عندما تكون موجودة في حساب WhatsApp Business الخاص بك. |
| `lane` | اتصال Meta المستخدم — `meta_cloud_api` (تطبيق Meta الخاص بك) أو `meta_embedded` (متصل عبر تطبيق Meta الخاص بنا). `null` في حالة الاتصال المُدار. |
| `waba_id` | حساب WhatsApp Business الذي تم إنشاء القوالب فيه، أو `null`. |
| `templates_enabled` | `false` عندما لا يكتمل اتصال Meta بعد (لا يوجد حساب WhatsApp Business أو رمز وصول مخزن). سيفشل إنشاء القوالب أو إرسالها مع `400` حتى يكتمل الاتصال. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}
```

### مزامنة القوالب من Meta

يعمل هذا على تحديث حالة الموافقة لكل قالب موجود في حساب WhatsApp Business الخاص بك، ويستورد أي قالب موجود هناك ولكنه ليس في مكتبتك بعد. من الآمن استدعاؤه بقدر ما تريد. في الاتصال المُدار، لا يوجد شيء للمزامنة، لذا لا يقوم الاستدعاء بأي إجراء سوى الإبلاغ عن عدد القوالب التي لديك.

`POST /whatsapp-templates/meta-sync`

| الحقل | الوصف |
|---|---|
| `imported` | القوالب التي تم العثور عليها في حساب WhatsApp Business والتي تمت إضافتها إلى مكتبتك بواسطة هذا الاستدعاء. |
| `updated` | القوالب الموجودة التي تغيرت حالتها أو تفاصيلها. |
| `total` | القوالب الموجودة في مكتبتك بعد المزامنة. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}
```

### التواصل مع Meta مباشرة (متقدم)

إذا كنت بحاجة إلى شيء لا توفره نقاط النهاية أعلاه — مثل رؤوس القوالب، أو التذييلات، أو الأزرار، أو قالب تم إنشاؤه يدويًا بالكامل — فإن `/v1/meta-templates` تمرر طلبك مباشرة إلى واجهة برمجة تطبيقات القوالب الخاصة بـ Meta، دون تخزين أي شيء في مكتبة القوالب الخاصة بك. يعمل هذا فقط على الحسابات التي يعمل رقمها على حساب WhatsApp Business الخاص بها؛ في الاتصال المُدار، يُرجع كل استدعاء `400` يطلب منك ربط تطبيق Meta أولاً.

| نقطة النهاية | وظيفتها |
|---|---|
| `GET /meta-templates` | تسرد القوالب الموجودة في حساب WhatsApp Business الخاص بك مع أحدث حالتها. أضف `?name=` للتصفية حسب اسم قالب محدد. تُرجع `{ "success": true, "templates": [...] }`. |
| `POST /meta-templates` | تنشئ قالباً وترسله لمراجعة Meta في خطوة واحدة. تتطلب `name`، و `language`، و `body` (أو مصفوفة `components` كاملة بدلاً من `body`). اختياري: `variables` (مصفوفة من السلاسل)، و `category` (`MARKETING`، أو `UTILITY`، أو `AUTHENTICATION`)، و `header`، و `footer`، و `buttons`. تُرجع `201` مع `{ "success": true, "template": {...} }`. |
| `DELETE /meta-templates/{name}` | تحذف القالب باسمه في Meta — **بكل لغاته**. أضف `?hsm_id=` مع معرف قالب Meta لإزالة لغة واحدة فقط. تُرجع `{ "success": true, "name": "..." }`. |

القالب الذي ترفضه Meta يُرجع `400` مع شرح Meta الخاص في `error`.

---

## سرد القوالب

إرجاع جميع القوالب الموجودة في حسابك، مع ملخص خفيف لكل منها.

`GET /whatsapp-templates`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}
```

---

## الحصول على قالب

يعيد التفاصيل الكاملة لقالب واحد، بما في ذلك متغيراته وحالته والطوابع الزمنية الخاصة به.

`GET /whatsapp-templates/{templateId}`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}
```

القالب غير الموجود في حسابك يعيد `404` مع `{ "success": false, "error": "Template not found" }`.

---

## إنشاء قالب

ينشئ قالباً لرسالة ترحيب الحملة ويقدمه للموافقة عليه في خطوة واحدة.

`POST /whatsapp-templates`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `campaign_id` | نعم | الحملة التي ينتمي إليها القالب. |
| `name` | نعم | اسم للقالب. |
| `language` | نعم | رمز اللغة، على سبيل المثال `en`، `es`، `de`، `pt_BR`، `zh_CN`. |
| `body` | نعم | نص الرسالة، بحد أقصى 1024 حرفاً. |
| `variables` | لا | قائمة مرتبة بأسماء المتغيرات المستخدمة في المتن. |

يمكن كتابة عناصر نائبة للمتغيرات كـ `{{first_name}}` أو `{first_name}` أو `[first_name]` — يتم توحيدها جميعاً إلى صيغة الأقواس المزدوجة.

تعتمد النتيجة على قنوات الحملة:

- **حملة WhatsApp Business API:** يتم إرسال المحتوى لمراجعة WhatsApp. تحمل الاستجابة `campaign_status` (`received` أو `pending`) و `template_sid`.
- **قناة بدون خطوة مراجعة خارجية:** يتم تخزين القالب واعتماده تلقائياً (`campaign_status: "approved"`، `template_sid: null`).
- **لا توجد قناة WhatsApp في الحملة:** لا يتم إنشاء أي شيء وتكون `campaign_status` هي `not_applicable`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**الاستجابة** (تم التقديم للمراجعة)

```json
{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

---

## إنشاء قالب مستقل

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

`POST /whatsapp-templates/docs`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `name` | نعم | اسم للقالب. |
| `language` | نعم | رمز اللغة، على سبيل المثال `en`، `es`، `de`، `pt_BR`، `zh_CN`. |
| `body` | نعم | نص الرسالة، بحد أقصى 1024 حرفاً. |
| `variables` | لا | قائمة مرتبة بأسماء المتغيرات المستخدمة في النص. |
| `status` | لا | `draft` (افتراضي) يخزنه دون إرسال؛ `submitted` يضعه في قائمة الانتظار لمراجعة WhatsApp مباشرة. |
| `type` | لا | `general` (افتراضي) أو `smart_followup`. |
| `category` | لا | `marketing`، `utility`، `authentication`، أو `authentication-international`. |
| `campaign_id` | لا | يربط القالب بإحدى حملاتك. |

> **قوالب المصادقة (رمز لمرة واحدة).** لا تقبل واتساب قوالب المصادقة ذات النص الحر: نص الرسالة مُعد مسبقًا بواسطة واتساب ويجب أن يحتوي القالب على زر "نسخ الرمز". عند إنشاء قالب باستخدام `category: "authentication"`، نقوم بإرساله بهذا الشكل الثابت نيابةً عنك. يتم الاحتفاظ بـ `body` كمعاينة معروضة في التطبيق، ولكن النص الذي يتلقاه جهة الاتصال الخاصة بك هو صياغة واتساب الخاصة (الرمز، وتذكير أمني، وملاحظة انتهاء الصلاحية لمدة 10 دقائق). قم بتعريف متغير واحد بالضبط، على سبيل المثال `["code"]`، وقم بتمرير الرمز عند الإرسال (راجع حقل `variables` في [إرسال قالب إلى جهة اتصال](#send-a-template-to-a-contact)). يجب أن يكون الرمز أقصر من 15 حرفًا.

> **أي خيار إنشاء يجب أن أستخدم؟** استخدم هذا الخيار عندما تريد قالباً يمكنك تحريره وإرساله بنفسك. استخدم `POST /whatsapp-templates` (أعلاه) عندما تريد تعيين الرسالة الافتتاحية لحملة ما — فهذا الخيار يتطلب `campaign_id` ويكتب مباشرة في الحملة.

يتم إرسال القالب الذي تم إنشاؤه كـ `submitted` لمراجعة WhatsApp في الخلفية، لذا تحقق من نقطة نهاية الحالة (status endpoint) لمعرفة النتيجة بدلاً من توقعها في الاستجابة.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}
```

يؤدي فقدان `name` أو `language` أو `body`، أو استخدام لغة غير مدعومة، أو `status` غير `draft` أو `submitted`، أو `type` أو `category` غير معروف، أو نص يتجاوز 1024 حرفاً إلى إرجاع `400` مع `error` توضيحي. يؤدي إدخال `campaign_id` ليس من حملاتك إلى إرجاع `404`.

---

## تحديث قالب

يعدل قالباً لم تتم الموافقة عليه بعد. يمكن فقط تعديل القوالب التي تحمل الحالة `draft` أو `rejected`. قدم أي مزيج من `name` و `body` و `language` و `variables` — سيتم تغيير الحقول التي ترسلها فقط.

`PUT /whatsapp-templates/{templateId}`

> لا تؤدي عملية التعديل إلى إعادة إرسال القالب للمراجعة. استخدم نقطة نهاية الإرسال (submit endpoint) بعد ذلك.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "template_id": "template_abc123"
}
```

تؤدي محاولة تعديل قالب تم اعتماده بالفعل `approved` (أو غير قابل للتعديل لأسباب أخرى)، أو إرسال حقول فارغة، أو إرسال قيمة غير صالحة إلى إرجاع `400` مع `error` توضيحي.

---

## إرسال قالب للموافقة

يُرسل قالب `draft` أو `rejected` للمراجعة. يتم اعتماد القوالب الموجودة على قناة لا تتطلب مراجعة خارجية على الفور؛ أما جميع القوالب الأخرى فيتم إرسالها إلى WhatsApp ويتم تخزين `status` المُعاد (عادةً ما يكون `received` أو `pending`) على القالب.

`POST /whatsapp-templates/{templateId}/submit`

> يجب أن تُعلن **قوالب المتابعة** عن متغيراتها المطلوبة وتستخدمها قبل إمكانية إرسالها: عنصر نائب للاسم الأول، بالإضافة إلى عنصر نائب للسياق الشخصي للمتابعات الذكية.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

---

## التحقق من حالة الموافقة

نقطة نهاية خفيفة لاستطلاع الحالة الحالية للقالب. تُقرأ الحالة من السجل المخزن، والذي يتم تحديثه دورياً في الخلفية، لذا قد يستغرق ظهور الموافقة أو الرفض الأخير بعض الوقت.

`GET /whatsapp-templates/{templateId}/status`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}
```

---

## حذف قالب

يزيل سجل القالب من حسابك.

`DELETE /whatsapp-templates/{templateId}`

::: warning
**هام:** في حالة الاتصال المُدار، تتم إزالة السجل المخزن فقط — أما المحتوى الذي وافقت عليه WhatsApp بالفعل فقد يظل مسجلاً لدى مزود المراسلة. أما في الحساب الذي يعمل على حساب WhatsApp Business خاص به، فيتم حذف القالب من ذلك الحساب أيضاً. وفي كلتا الحالتين، إذا كانت هناك حملة لا تزال تستخدم هذا القالب، فقم بتوجيه تلك الحملة إلى قالب آخر **قبل** الحذف، وإلا فإن عمليات الإرسال التي تعتمد عليه ستفشل.
:::


**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}
```

---

## إرسال قالب إلى جهة اتصال

يرسل قالباً معتمداً إلى جهة اتصال، حتى في حال عدم وجود محادثة مفتوحة — وهذا يؤدي إلى إعادة فتح جلسة الدردشة. يمكنك استهداف جهة الاتصال بواسطة `contactId` أو بواسطة `phoneNumber`، واختيار القالب بواسطة `whatsappTemplateId` أو بواسطة `templateName`.

`POST /whatsapp-templates/send`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `contactId` | واحد من هذين الاثنين | معرف جهة الاتصال. |
| `phoneNumber` | واحد من هذين الاثنين | رقم هاتف جهة الاتصال (مع رمز الدولة، بدون مسافات). يتم البحث عنه أو إنشاؤه إذا لزم الأمر. |
| `whatsappTemplateId` | واحد من هذين الاثنين | معرف القالب. |
| `templateName` | واحد من هذين الاثنين | اسم القالب، كما هو معروض في التطبيق. |
| `firstName` | لا | يُستخدم لملء بيانات جهة اتصال تم إنشاؤها حديثًا. |
| `lastName` | لا | يُستخدم لملء بيانات جهة اتصال تم إنشاؤها حديثًا. |
| `email` | لا | يُستخدم لملء بيانات جهة اتصال تم إنشاؤها حديثًا. |
| `variables` | لا | قيم صريحة لمتغيرات القالب، مُصنفة حسب اسم المتغير، على سبيل المثال `{ "code": "482913" }`. القيمة المُعطاة هنا تتفوق على حقول جهة الاتصال لهذا المتغير؛ المتغيرات التي تتركها فارغة يتم ملؤها من جهة الاتصال كما هو موضح أدناه. هذه هي الطريقة التي تمرر بها رمزًا لمرة واحدة إلى قالب مصادقة. |

يدعم نص القالب استبدال المتغيرات المتقدم:

- **المتغيرات الأساسية:** `{{first_name}}`، `{{email}}`، `{{company}}`
- **القيم الافتراضية:** `{{first_name|there}}` تعرض `there` إذا كان الحقل فارغاً
- **التحويلات:** `{{company|uppercase}}`، `{{name|lowercase}}`، `{{name|capitalize}}`
- **مدمج:** `{{company|Your Company|uppercase}}`

> **الرصيد:** يستهلك إرسال القالب رصيداً. تعتمد التكلفة الدقيقة على بلد المستلم وفئة القالب.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}
```

يؤدي الطلب الذي يفتقر إلى معرف جهة الاتصال ومعرفي القالب إلى إرجاع `400`. إذا كان حسابك يفتقر إلى بيانات اعتماد المراسلة اللازمة للإرسال، تكون الاستجابة `403`.

---

## إنشاء أو تحديث قالب نشط لحملة

زوج ثانٍ من نقاط النهاية لقالب افتتاح الحملة، محدد النطاق حسب المسار بدلاً من `campaign_id` في النص الأساسي. هذه هي النقاط التي يجب استخدامها لحملة نشطة بالفعل: على عكس [إنشاء قالب](#create-a-template) أعلاه، فإن التحديث هنا يعيد أيضاً إرسال مسودات المتابعة الخاصة بالحملة للمراجعة، بحيث يظل قالب الافتتاح ومتابعاته متزامنين.

`POST /whatsapp-templates/campaign/{campaignId}` ينشئ قالب افتتاح الحملة. `PUT /whatsapp-templates/campaign/{campaignId}` يقوم بتعديله — يجب أن تحتوي الحملة بالفعل على قالب، وإلا فسيتم إرجاع `400`.

| الحقل | مطلوب | الوصف |
|---|---|---|
| `name` | نعم | اسم للقالب. |
| `language` | نعم | رمز اللغة، على سبيل المثال `en`، `es`، `de`، `pt_BR`، `zh_CN`. |
| `body` | نعم | نص الرسالة، بحد أقصى 1024 حرفاً. |
| `variables` | نعم | قائمة مرتبة بأسماء المتغيرات المستخدمة في النص الأساسي. مرر مصفوفة فارغة إذا كان القالب لا يستخدم أياً منها. |

**cURL** (إنشاء)

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}
```

للتحرير، قم بتبديل الطريقة إلى `PUT` واستخدم نفس الحقول — هذا يعيد إرسال قالب الافتتاح (ومسودات المتابعة للحملة، في حملة WhatsApp API) للمراجعة.

الحملة التي لا تنتمي إلى حسابك تُرجع `404`؛ الحملة التي تنتمي إلى حساب آخر لست مخولاً له تُرجع `403`. تحرير حملة ليس لها قالب موجود يُرجع `400`.

---

## إرسال قالب إلى جهة اتصال موجودة

بديل أبسط ومحدد النطاق حسب المسار لـ [إرسال قالب إلى جهة اتصال](#send-a-template-to-a-contact) أعلاه: يجب أن يكون كل من القالب وجهة الاتصال موجودين بالفعل — لا يتم البحث عن أي شيء بالاسم أو إنشاؤه أثناء التنفيذ.

`POST /whatsapp-templates/{templateId}/send-to-contact`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `contactId` | نعم | معرف جهة الاتصال. يجب أن ينتمي إلى حسابك. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}
```

> **الرصيد:** الإرسال يستهلك رصيداً، ويتم تسعيره بنفس طريقة نقطة النهاية أعلاه. `contactId` المفقود أو غير الموجود في حسابك يُرجع `403`؛ `templateId` غير الموجود يُرجع `404`.

---

## إرسال قالب بالجملة

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

### تقدير التكلفة أولاً

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

`POST /whatsapp-templates/{templateId}/estimate-bulk-cost`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `contactIds` | نعم | جهات الاتصال المراد تسعيرها، بحد أقصى 500 لكل طلب. يتم احتساب التكرارات مرة واحدة فقط. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}
```

تحسب `skippedContacts` المعرفات المفقودة، أو التي لا تخصك، أو التي لا تحتوي على رقم هاتف — التقدير يغطي الباقي فقط، لذا فإن القيمة غير الصفرية تعني أن الإرسال الفعلي سيصل إلى عدد أقل من جهات الاتصال التي حددتها.

### إرسال الدفعة

يرسل القالب إلى كل جهة اتصال في القائمة، مع حل أي متغيرات ذكية لكل جهة اتصال وخصم الرصيد لكل عملية إرسال.

`POST /whatsapp-templates/{templateId}/bulk-send`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `contactIds` | نعم | جهات الاتصال المراد الإرسال إليها، بحد أقصى 5000 لكل طلب. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}
```

يتم تخطي جهة الاتصال التي تفشل (غير موجودة، أو ليست في حسابك، أو حدث خطأ في الإرسال) واحتسابها في `failed` بدلاً من إيقاف الدفعة. يؤدي وجود `contactIds` فارغ، أو أكثر من 5000 معرف في عملية إرسال (500 في التقدير)، أو فقدان `templateId` إلى إرجاع `400`.

---

## إعادة محاولة إرسال رسالة فاشلة

نقطتا نهاية لإعادة إرسال رسالة فشلت، دون إنشاء سجل رسالة جديد أو خصم رصيد مرة أخرى.

تعيد `POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template` محاولة إرسال رسالة قالب فاشلة تحديداً — فهي تعيد حل محتوى القالب من الحملة إذا لم تكن الرسالة الفاشلة تحمله بالفعل. لا يمكن إعادة محاولة سوى الرسائل التي تحمل الحالة `failed` والنوع `template` بهذه الطريقة.

تعد `POST /whatsapp-templates/messages/{contactId}/{messageId}/retry` محايدة للقناة وتعمل مع أي رسالة فاشلة غير متعلقة بقالب (على سبيل المثال WhatsApp Web)، حيث يتم توجيهها إلى مسار الإرسال الصحيح بناءً على قناة الرسالة. وهي تقبل الحالة `failed` أو `failed_connection` أو `limit_exceeded` أو `queued_retry`.

لا تتطلب أي من نقطتي النهاية نص طلب.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": "Message retry initiated successfully"
}
```

بالنسبة للإصدار المحايد للقناة، استبدل المسار بـ `.../msg_abc789/retry`. الرسالة التي لا تكون حالتها مؤهلة لإعادة المحاولة، أو (في نقطة نهاية القالب) التي ليست رسالة قالب، تُرجع `400`. جهة الاتصال أو الرسالة المفقودة تُرجع `404`.

---

## ملف تعريف WhatsApp Business

إدارة ملف تعريف WhatsApp Business (حول، العنوان، الوصف، البريد الإلكتروني، المواقع الإلكترونية، فئة النشاط التجاري، والشعار) الذي يظهر لجهات الاتصال على WhatsApp. يعمل هذا على كل من الاتصال المُدار والحساب الذي يشغل حساب WhatsApp Business الخاص به.

### حفظ ملف التعريف

`PUT /whatsapp-templates/profile`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `phoneNumber` | نعم | رقم WhatsApp الذي ينتمي إليه ملف التعريف هذا. يجب أن يكون متصلاً بحسابك. |
| `about` | لا | نص "حول" قصير يظهر في ملف التعريف. |
| `address` | لا | عنوان النشاط التجاري. |
| `description` | لا | وصف أطول للنشاط التجاري. |
| `email` | لا | البريد الإلكتروني لجهة الاتصال الذي يظهر في ملف التعريف. |
| `websites` | لا | مصفوفة من روابط المواقع الإلكترونية. يجب أن يكون كل منها رابطاً صالحاً. |
| `vertical` | لا | فئة النشاط التجاري، على سبيل المثال `Retail` أو `Professional Services`. |
| `profilePictureHandle` | لا | المعرف (handle) الذي تم إرجاعه بواسطة نقطة نهاية تحميل الصورة أدناه، لتعيين صورة ملف التعريف. |

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}
```

يؤدي فقدان `phoneNumber`، أو رابط موقع إلكتروني غير صالح، أو `phoneNumber` غير متصل بحسابك إلى إرجاع `400` أو `404`.

### تحميل صورة ملف التعريف

يقوم بتنزيل صورة من رابط توفره وتحميلها إلى WhatsApp، مع إرجاع معرف (handle). مرر هذا المعرف كـ `profilePictureHandle` في طلب حفظ ملف التعريف أعلاه لتعيينها كصورة — تقوم نقطة النهاية هذه بتحميل الصورة فقط، ولا تقوم بتعيينها بنفسها.

`POST /whatsapp-templates/profile/picture`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `phoneNumber` | نعم | رقم WhatsApp الذي ينتمي إليه ملف التعريف هذا. |
| `fileUrl` | نعم | رابط متاح للجمهور للصورة المراد تحميلها. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": "1234567890123456"
}
```

`data` هو معرف الصورة التي تم تحميلها. يؤدي فقدان `phoneNumber` أو `fileUrl`، أو `phoneNumber` بدون رمز وصول WhatsApp في الملف، إلى إرجاع `400`؛ بينما يؤدي وجود `fileUrl` غير قابل للوصول أو غير صالح إلى إرجاع خطأ يوضح سبب فشل التنزيل.

---

## التحقق من حالة المرسل

يقوم باستطلاع (وتحديث) حالة الإرسال المباشرة لرقم WhatsApp متصل مع مزود المراسلة. مفيد للتأكد من أن الرقم قادر فعلياً على الإرسال قبل الاعتماد عليه.

`GET /whatsapp-templates/sender-status/{phoneNumber}`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**الاستجابة**

```json
{
  "success": true,
  "data": "ONLINE"
}
```

`data` هي واحدة من `ONLINE` (يرسل بشكل طبيعي)، أو `PENDING` (لا يزال قيد التحقق)، أو `DELETED` (لم يعد المزود يتعرف على هذا المرسل — أعد توصيل الرقم). يؤدي وجود `phoneNumber` بدون معلومات WhatsApp Business في الملف إلى إرجاع `404`.

---

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

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

### بدء مهمة إنشاء

`POST /campaigns/{campaignId}/template-generation`

| الحقل | مطلوب | الوصف |
|---|---|---|
| `type` | لا | `all` (الافتراضي) يكتب مجموعة المتابعة الكاملة. `cold_only` يكتب فقط الرسائل لجهات الاتصال التي لم ترد مطلقاً. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()
```

**الاستجابة** (`202`)

```json
{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }
```

يعود الاستدعاء بمجرد وضع المهمة في قائمة الانتظار. اقرأ الحملة (`GET /campaigns/{campaignId}`، راجع [واجهة برمجة تطبيقات الحملات](campaigns.md)) وراقب كائن `template_generation_status` الخاص بها حتى تنتهي:

| الحقل | الوصف |
|---|---|
| `status` | `processing` أثناء تشغيل المهمة، ثم `completed` أو `failed`. |
| `progress` | من 0 إلى 100. |
| `current_template`, `total_templates` | عدد القوالب التي تمت كتابتها حتى الآن، من إجمالي عدد القوالب التي ستكتبها المهمة — 11 لحملة صادرة أو مدمجة، و9 بخلاف ذلك. |
| `error` | سبب توقف مهمة `failed`، على سبيل المثال عدم كفاية الأرصدة. |
| `started_at`, `completed_at` | متى بدأت المهمة وانتهت. |

تصل القوالب التي تم إنشاؤها إلى الحملة مثل أي قوالب أخرى، لذا فهي تظهر في [قائمة القوالب](#list-templates) وتخضع لموافقة WhatsApp قبل إمكانية إرسالها. تعني `400` أن `type` كان شيئاً آخر غير `all` أو `cold_only`؛ وتعني `404` أن الحملة غير موجودة أو تنتمي إلى حساب آخر.

لدى الوكلاء نسخة مطابقة لهذا الاستدعاء، `POST /agents/{agentId}/template-generation`، والتي تكتب المتابعات لوكيل وتنتهي أثناء الاستدعاء في الحالة المعتادة — راجع [إنشاء رسائل المتابعة](agents.md#generate-follow-up-messages) في واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي.

### نقاط نهاية الإنشاء القديمة

تقوم ثلاث نقاط نهاية سابقة بنفس العمل ويتم الاحتفاظ بها لضمان استمرار عمل عمليات التكامل الحالية. يجب أن يستخدم الكود الجديد نقطة نهاية المهمة المذكورة أعلاه.

| نقطة النهاية | ما تقوم به |
|---|---|
| `POST /whatsapp-templates/campaign/{campaignId}/generate-async` | تبدأ إنشاء المتابعة للحملة في الخلفية وتعيد `202` مع `{ "success": true, "data": { "result": "success", "message": "..." } }`. يتم خصم الأرصدة مقدماً (يتم تخطي ذلك في الحساب الذي يوفر مفتاح الذكاء الاصطناعي الخاص به) ويقوم `template_generation_status` الخاص بالحملة بالإبلاغ عن التقدم تماماً كما هو موضح أعلاه. |
| `POST /whatsapp-templates/campaign/{campaignId}/generate-followups` | تنشئ جميع قوالب المتابعة التسعة أثناء الاستدعاء — لحملة تم إنشاؤها قبل وجود المتابعات التلقائية، أو حملة تحتاج إلى إعادة كتابتها — وتعيد `200` مع `templatesGenerated` داخل `data`. |
| `POST /whatsapp-templates/agent/{agentId}/generate-followups` | نفس الإنشاء المتزامن الذي يتم معالجته بواسطة الوكيل. تضيف الاستجابة `agent_id` و`campaign_id` و`target`: `"campaign"` عندما تمت كتابة القوالب على حملة الوكيل، و`"agent"` (مع `campaign_id: null`) عندما لا يكون لدى الوكيل حملة وتم تخزينها على الوكيل نفسه. الوكيل المفقود أو الأجنبي هو `404`. |

تتطلب جميع النقاط الثلاث تفعيل المتابعات التلقائية على الحساب ووجود أرصدة كافية — تحدد `400` ما هو مفقود — ويعيد الزوج الموجه للحملة `403` عندما تنتمي الحملة إلى حساب آخر.

---

## أخطاء واجهة برمجة تطبيقات القوالب

تُرجع نقاط نهاية القوالب غلاف الخطأ القياسي:

```json
{
  "success": false,
  "error": "Template not found"
}
```

عادةً ما يعني ظهور `404` في نقاط النهاية هذه أن المورد لم يتم العثور عليه — إما لأنه غير موجود أو لأنه ينتمي إلى حساب آخر. تُرجع بعض نقاط النهاية (الإنشاء/التحديث على مستوى الحملة، والإرسال إلى جهة اتصال موجودة) `403` بدلاً من ذلك عندما تنتمي الحملة أو جهة الاتصال لشخص آخر بدلاً من عدم وجودها على الإطلاق. تتضمن بعض نقاط النهاية أيضاً حقل `error_code` يعكس حالة HTTP. الرموز المشتركة التي يمكن أن تُرجعها أي نقطة نهاية — `400`، و`401`، و`403` (خطتك لا تتضمن الوصول إلى واجهة برمجة التطبيقات)، و`429` (حد المعدل)، و`500` — مدرجة مع إرشادات إعادة المحاولة في [الأخطاء والترقيم](errors-and-pagination.md).

---

## الخطوات التالية

- [المصادقة](authentication.md) — الطرق الأربع لمصادقة الطلب.
- [الأخطاء وحدود المعدل](errors-and-pagination.md) — رموز الحالة وحد 300 طلب/دقيقة.
- [واجهة برمجة تطبيقات الحملات](campaigns.md) — إدارة الحملات التي يتم إرفاق القوالب بها.