بيانات مساحة العمل

القوالب

القالب محتوى رسالة قابل لإعادة الاستعمال بمتغيرات مسماة. يُعرَّف مرة واحدة بصيغة المنصة نفسها، ويبقى مستقلا عن المزوّد — فالقالب نفسه ينجو من الانتقال من قناة إلى أخرى.

النقاط

GET/v1/templatesPOST/v1/templatesGET/v1/templates/{templateId}PATCH/v1/templates/{templateId}DELETE/v1/templates/{templateId}POST/v1/templates/{templateId}/previewPOST/v1/templates/{templateId}/test-send

القراءة تحتاج صلاحية الإدارة

كل مسارات القوالب، بما فيها مسارات القراءة، تتطلب templates.manage. لا توجد صلاحية قراءة منفصلة، فالمفتاح الذي يسرد القوالب فقط يحتاج صلاحية الإدارة.

القالب

يُعرَّف القالب بالـ slug واللغة معا — فالـ slug نفسه بلغتين قالبان اثنان.

الحقل	النوع	مطلوب	الوصف
slug	string	مطلوب	بصيغة lower_snake_case، مثل order_confirmation. ولا يتغيّر بعد الإنشاء.
language	string	مطلوب	رمز لغة مثل ar أو en-GB. ولا يتغيّر بعد الإنشاء.
body	string	مطلوب	نص الرسالة، وفيه متغيرات {{...}}.
name	string	اختياري	تسمية بشرية. الافتراضي هو الـ slug.
category	"authentication" \| "utility" \| "marketing"	اختياري	الافتراضي utility. وتعلو على فئة أي إرسال يستعمل هذا القالب.
header	object	اختياري	رأس اختياري: نص أو موضع وسائط. ورأس النص يتطلب نصه.
footer	string	اختياري	تذييل اختياري.
buttons	object[]	اختياري	ردود سريعة وأزرار روابط وأزرار أرقام هاتف.
examples	object<string, string>	اختياري	قيم نموذجية للمتغيرات، تستعملها المعاينة والمراجعة.
status	"draft" \| "local_active"	اختياري	ابدأ مسودة، أو local_active ليصير قابلا للإرسال فورا.

curl

curl -X POST https://whats.azzamkh.sa/api/v1/templates \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "order_confirmation",
    "language": "ar",
    "category": "utility",
    "body": "مرحبا {{name}}، تم تأكيد طلبك رقم {{order_id}}.",
    "footer": "شكرا لك",
    "status": "local_active",
    "examples": { "name": "سارة", "order_id": "A-10428" }
  }'

# 201 Created — "variables" is DERIVED from the content, never sent.
# {
#   "id": "tpl_...",
#   "slug": "order_confirmation",
#   "status": "local_active",
#   "version": 1,
#   "variables": [
#     { "name": "name", "example": "سارة" },
#     { "name": "order_id", "example": "A-10428" }
#   ],
#   "delivery": { "local": true, "meta": false },
#   "bindings": []
# }

طبقتا تحقق، والثانية أضيق

مخطط الطلب يقبل حجما سخيا؛ ثم يفرض مدقّق المحتوى حدود المنصة المضبوطة — نصا أقصر وأزرارا أقل ومتغيرات أقل. والنص الذي يجتاز الفحص الأول ويسقط في الثاني يعطي 422 يسمّي الحقل، فتحقق من الأرقام الأضيق.

المتغيرات

docs.pages.templates.variables.body

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

عاين قبل أن ترسل

نقطة المعاينة تصيّر القالب وتبلّغ بالمتغيرات الناقصة وبما أرسلته ولم يُستعمل. وهي لا تخفق أبدا على قيمة ناقصة — أما الإرسال الحقيقي فيخفق بـ TEMPLATE_VARIABLE_MISSING. راجع إرسال الرسائل.

curl

curl -X POST https://whats.azzamkh.sa/api/v1/templates/tpl_.../preview \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "name": "سارة" } }'

# 200 OK — preview REPORTS what is missing; it does not fail.
# {
#   "id": "tpl_...",
#   "text": "مرحبا سارة، تم تأكيد طلبك رقم {{order_id}}.",
#   "variables": ["name", "order_id"],
#   "missing": ["order_id"],
#   "unused": []
# }

الحالة

الحالة تحدد إمكان إرسال القالب. وثلاث من التسع لا تُرسل.

الحالة	قابل للإرسال	الوصف
draft	لا	قيد الكتابة. غير قابل للإرسال.
local_active	نعم	فعّال على مزوّدي المنصة. وهي حالة العمل المعتادة اليوم.
submitted	نعم	أُرسل لمراجعة Meta. محجوزة — التقديم غير مبني.
pending	نعم	بانتظار مراجعة Meta. محجوزة.
approved	نعم	معتمد من Meta. محجوزة.
rejected	نعم	رفضته Meta. ويبقى قابلا للإرسال محليا.
paused	لا	موقوف مؤقتا. غير قابل للإرسال.
disabled	لا	متقاعد. غير قابل للإرسال. والأرشفة تضبطه على هذه الحالة.
outdated	نعم	تغيّر المحتوى بعد إنشاء ارتباط بـ Meta. ويبقى قابلا للإرسال محليا.

حذف قالب يؤرشفه — تصير حالته disabled وتبقى الرسائل التي استعملته مقروءة. وإعادة إنشاء الـ slug واللغة نفسيهما بعدها تُحيي القالب المؤرشف بدل أن تتعارض معه.

قوالب Meta

التقديم إلى Meta غير متاح بعد

لا توجد نقطة submit-to-meta ولا نقطة sync؛ وطلب أيّهما يعطي 404 لا 501. وحقل bindings موجود في كل استجابة وهو فارغ دائما، ولذلك تكون delivery.meta دائما false.

وكل ما عدا ذلك مبني لأجله. فتغيير المحتوى يرفع version ويكتب لقطة غير قابلة للتعديل، فيمكن مطابقة قالب بنسخة معتمدة من Meta لاحقا دون فقدان ما أُرسل فعلا.

المرشّحات

المعامل	الوصف
q	بحث غير حساس للحالة في الـ slug والاسم والنص.
status	الترشيح بالحالة.
category	الترشيح بالفئة.
language	مطابقة تامة لرمز اللغة.
limit, after	تقسيم بالـ cursor. ولاحظ أن ترتيب هذه القائمة تصاعدي، خلافا للرسائل والمحادثات.

قيمة المرشّح المجهولة تُتجاهل هنا

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