متغيرات القوالب
املأ نص القالب وترويسة الوسائط والأزرار لكل مستلم.
القوالب فيها أماكن متغيرة ({{1}}، {{2}}…) تملؤها لكل مستلم. ويوضح لك GET /templates بالضبط
ما يحتاجه كل قالب:
"variables": {
"header": { "type": "image", "example": null },
"body": [
{ "index": 1, "name": "customer.name", "example": "Mona" },
{ "index": 2, "name": null, "example": "EID20" }
],
"buttons": [
{ "index": 0, "type": "url", "variable": true, "example": "EID20" },
{ "index": 1, "type": "quick_reply", "variable": false, "example": null }
]
}ويحمل كل مستلم القيم:
{
"phone": "+201001234567",
"variables": {
"header": "https://cdn.example.com/eid.jpg",
"body": ["Mona", "EID20"],
"buttons": { "0": "EID20" }
}
}النص (body)
body مصفوفة مرتبة: القيمة الأولى تملأ {{1}}، والثانية {{2}}، وهكذا. أرسل عدد القيم نفسه الذي
يحتاجه القالب بالضبط. وname هو اسم المتغير في استوديو القوالب إن كان له اسم: تلميح لما يوضع مكانه.
تُرسل القيم كما تكتبها بالضبط. لا يملأ موجود شيئًا من عنده، ولا حتى اسم العميل، فما ترسله هو ما يقرؤه العميل. وتُفحص قواعد واتساب للقيمة قبل أي إرسال: ألا تكون فارغة، وألا يكون فيها سطر جديد أو Tab، وألا تزيد المسافات المتتالية على أربع، وألا تتجاوز 1,024 حرفًا.
الترويسة (header)
ترويسات النص لا تحتوي على متغيرات في موجود، لذا لا يظهر في variables.header إلا ترويسة الوسائط
(image أو video أو document). وقيمتها اختيارية:
- اتركها، فيُرسل ملف القالب نفسه كما في لوحة التحكم.
- أو أرسل رابط HTTPS عامًا لملف آخر، يحمّله واتساب عند الإرسال.
القالب ذو ترويسة النص أو بلا ترويسة لا يأخذ قيمة header.
الأزرار (buttons)
كل زر مذكور بترتيبه (index يبدأ من 0). variable: true تعني أنه يحتاج قيمة لكل مستلم، وexample
هو مثال القالب. وbuttons كائن مفاتيحه هذا الرقم، للأزرار التي فيها variable: true فقط:
| نوع الزر | القيمة |
|---|---|
url | إن كان فيه متغير: الجزء الذي يلي الرابط الثابت في القالب. |
copy_code | الكود الذي ينسخه العميل، حتى 15 حرفًا وبلا مسافات. |
quick_reply | لا شيء. ضغطة العميل تعود إليك كرد. |
phone_number | لا شيء. الزر يتصل بالرقم المكتوب في القالب. |
flow | لا شيء. الزر يفتح WhatsApp Flow الخاص بالقالب. |
قوالب لا ترسلها الواجهة
قوالب الكاروسيل، وقوالب الكتالوج والمنتجات المتعددة، والعروض محدودة الوقت ذات العد التنازلي، والقوالب
التي نقلتها ميتا إلى فئة المصادقة لا تظهر في GET /templates، وإرسال أي منها يرد بـ
422 template_not_supported (details.reason). أرسلها من لوحة التحكم.
عند نقص قيمة
القيمة الناقصة أو الفارغة تُفشل الطلب كله بـ 422 missing_variables. والقيمة لجزء غير موجود في
القالب، أو القيمة التي سيرفضها واتساب، تُفشله بـ 422 validation_failed. ويوضح details أي مستلم
(ترتيبه في recipients بدءًا من 0)، وأي جزء، وأي متغير، وما المشكلة (missing أو unexpected أو
invalid):
{
"error": {
"code": "missing_variables",
"message": "Recipient 2 is missing body variable {{2}}",
"details": { "recipient": 2, "part": "body", "index": 2, "problem": "missing" }
}
}لا يُرسل شيء عند فشل الطلب، فصحح القائمة وأرسلها مرة أخرى.