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

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

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

https://api.youraiconnector.com/v1

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

ملاحظة: تعتمد القوالب على قناة 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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

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()

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

{
  "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 في إرسال قالب إلى جهة اتصال). يجب أن يكون الرمز أقصر من 15 حرفًا.

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

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

cURL

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

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

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()

الاستجابة

{
  "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

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

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

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()

الاستجابة

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

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

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

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

POST /whatsapp-templates/{templateId}/submit

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

cURL

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

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

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()

الاستجابة

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

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

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

GET /whatsapp-templates/{templateId}/status

cURL

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

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

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()

الاستجابة

{
  "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}

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

cURL

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

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

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.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

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

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

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()

الاستجابة

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

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

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

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

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

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

cURL (إنشاء)

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

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

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()

الاستجابة

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

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

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

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

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

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

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

cURL

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

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

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()

الاستجابة

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

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

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

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

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

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

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

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

cURL

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

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

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()

الاستجابة

{
  "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

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

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

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()

الاستجابة

{
  "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

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

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

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()

الاستجابة

{
  "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

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

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

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()

الاستجابة

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

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

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

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

POST /whatsapp-templates/profile/picture

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

cURL

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

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

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()

الاستجابة

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

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

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

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

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

cURL

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

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

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()

الاستجابة

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

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

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

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

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

POST /campaigns/{campaignId}/template-generation

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

cURL

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

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

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)

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

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

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

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

لدى الوكلاء نسخة مطابقة لهذا الاستدعاء، POST /agents/{agentId}/template-generation، والتي تكتب المتابعات لوكيل وتنتهي أثناء الاستدعاء في الحالة المعتادة — راجع إنشاء رسائل المتابعة في واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي.

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

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

نقطة النهاية	ما تقوم به
`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 عندما تنتمي الحملة إلى حساب آخر.

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

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

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

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

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

المصادقة — الطرق الأربع لمصادقة الطلب.
الأخطاء وحدود المعدل — رموز الحالة وحد 300 طلب/دقيقة.
واجهة برمجة تطبيقات الحملات — إدارة الحملات التي يتم إرفاق القوالب بها.

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

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

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

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

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

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

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

سرد القوالب #

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

إنشاء قالب #

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

تحديث قالب #

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

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

حذف قالب #

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

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

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

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

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

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

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

ملف تعريف WhatsApp Business #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سرد القوالب

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

إنشاء قالب

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

تحديث قالب

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

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

حذف قالب

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

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

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

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

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

إرسال الدفعة

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

ملف تعريف WhatsApp Business

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

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

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

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

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

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

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

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