القوالب

أدِر القوالب التي يرسل بها الحساب: قوالب البريد الإلكتروني ورؤوس الرسائل النصية وقوالب DLT ورقم WhatsApp وقوالبه. تتطلب قراءتها نطاق الإرسال للقناة أو templates:manage؛ ويتطلب تعديلها مفتاح Owner أو Admin يحمل templates:manage.


قوالب البريد الإلكتروني

قوالب البريد الإلكتروني للحساب هي قوالب مساحة عمله الافتراضية، حيث توجد رسائل API وتعرضها لوحة التحكم. القالب المنشأ عبر API هو HTML يحتوي على عناصر نائبة {{name}} يملؤها الإرسال. ويمكن قراءة القالب المصمم في محرر لوحة التحكم واستخدامه للإرسال وحذفه، لكن لا يمكن استبداله، ليظل HTML متوافقًا مع التصميم.

الطريقةالمسارالوظيفة
GET/external/v1/templatesالقوالب من الأحدث إلى الأقدم، من دون HTML الخاص بها
GET/external/v1/templates/{id}قالب واحد مع HTML والمتغيرات التي يقبلها
POST/external/v1/templatesينشئ قالبًا من HTML: 201
PUT/external/v1/templates/{id}يستبدل قالبًا منشأ من HTML: الاسم والموضوع وHTML
DELETE/external/v1/templates/{id}يحذف قالبًا: 204؛ فلا يعود ظاهرًا في القائمة أو متاحًا للإرسال
  • اسم
    name
    النوع
    string
    وصف

    مطلوب: اسم القالب، بحد أقصى 255 حرفًا. تنطبق أيضًا قواعد Oblic القياسية للتحقق من الأسماء؛ فالالتزام بالطول وحده لا يكفي.

  • اسم
    subject
    النوع
    string
    وصف

    الموضوع الذي تستخدمه رسالة مرسلة بهذا القالب إذا لم يحدد الإرسال موضوعًا، بحد أقصى 1,023 حرفًا، مع عناصر نائبة خاصة به. يُخزّن الموضوع المحذوف أو الفارغ بقيمة null؛ وتُزال المسافات المحيطة بالموضوع غير الفارغ.

  • اسم
    html
    النوع
    string
    وصف

    مطلوب: HTML، ويُخزّن كما قُدّم، بحد أقصى 65,535 بايت UTF-8. تُهرّب قيم المتغيرات لصيغة HTML عندما يملأ الإرسال العناصر النائبة؛ وهذا لا ينقّي HTML الخاص بالقالب ولا يعزله في بيئة محمية.

إنشاء قالب

curl -X POST https://api.oblic.app/external/v1/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Order shipped",
    "subject": "Order {{order_id}} is on its way",
    "html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>"
  }'

201 تم الإنشاء

{
  "status": "success",
  "data": {
    "id": "TEM000R7ZM4Q2VXH00",
    "name": "Order shipped",
    "subject": "Order {{order_id}} is on its way",
    "kind": "html",
    "variables": ["order_id", "first_name"],
    "html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>",
    "createdAt": "2026-10-24T09:30:00Z",
    "updatedAt": "2026-10-24T09:30:00Z"
  },
  "errors": null
}
  • العنصر النائب هو {{name}}: أحرف وأرقام ASCII و_ و. و- ومسافات داخل الاسم فقط، بحد أقصى 64 حرفًا. يسرد variables العناصر الموجودة في الموضوع وHTML دون تمييز حالة الأحرف، بترتيب أول ظهور لها وتهجئته.
  • kind يساوي html للقالب المنشأ عبر API وdesigned للقالب المنشأ في محرر لوحة التحكم. إذا لم يكن للقالب موضوع، فأرسِل موضوعًا مع الطلب؛ فنوع القالب لا يغني عن التحقق من الموضوع المُعاد.
  • إشارات لوحة التحكم، مثل @unsubscribe أو @organizationName، تملؤها الحملات والأتمتة فقط لكل مستلم. ويُرفض الإرسال بقالب يحتوي على إحداها.
  • القائمة مقسمة إلى صفحات باستخدام cursor وlimit: الافتراضي 25 عنصرًا في الصفحة، من 1 إلى 100، كما يوضح تقسيم الصفحات. تعامل مع المؤشر المُعاد بوصفه قيمة معتمة.
الرفضcdالحالة
400TEMPLATE_TOO_LARGEحجم HTML أكبر من 65,535 بايت
404TEMPLATE_NOT_FOUNDلا يملك الحساب قالبًا بذلك المعرّف
409TEMPLATE_DESIGNEDاستبدال قالب صُمم في محرر لوحة التحكم

رؤوس الرسائل النصية وقوالبها

تستخدم الرسالة النصية رأس DLT وتطابق قالب محتوى DLT تابعًا لكيان DLT المهيأ لدى Cunomial. يُسجّل كلاهما أولًا في منصة DLT، ثم تُحفظ بياناتهما هنا لربطهما بطلب إرسال رسالة نصية. حفظهما هنا لا يسجلهما لدى DLT. يصف keepsRegistry وavailable في استجابة حساب الرسائل النصية صلاحية السجل المهيأ وتوافره، ولا يضمنان التسليم.

تُعرض قوالب السجل المعتمدة فقط؛ وقد تظهر القوالب المعتمدة غير النشطة أيضًا. ويتطلب الإرسال قالبًا نشطًا واجتياز بقية فحوص الإرسال الموضحة في الرسائل.

الطريقةالمسارالوظيفة
GET/external/v1/sms/accountحدود الحساب وإرسالاته هذا الشهر وأنواع الرسائل المسموح بها
GET/external/v1/sms/sendersرؤوس الحساب الخاصة، [{"senderId": …, "isDefault": …}]
PUT/external/v1/sms/senders/{senderId}يضيف رأسًا من ستة أحرف أو ستة أرقام؛ ويجعله {"isDefault": true} افتراضيًا
DELETE/external/v1/sms/senders/{senderId}يحذف رأسًا لا يستخدمه أي قالب: 204
GET/external/v1/sms/templatesقوالب الحساب ثم القوالب التي يشاركها معه الحساب الأب
POST/external/v1/sms/templatesيضيف قالبًا: 201
PUT/external/v1/sms/templates/{id}يعدّل قالبًا يُقدّم بكامل بياناته
DELETE/external/v1/sms/templates/{id}يحذف قالبًا: 204
PUT/external/v1/sms/templates/{id}/sharingيتيح الإرسال به لعدم وجود حسابات، أو لكل الحسابات الفرعية أو للمحددة منها
  • اسم
    templateId
    النوع
    string
    وصف

    مطلوب: معرّف DLT للقالب، حتى 32 رقمًا.

  • اسم
    senderId
    النوع
    string
    وصف

    مطلوب: أحد رؤوس الحساب. يستخدم القالب الترويجي رأسًا من ستة أرقام، وتستخدم القوالب الأخرى رأسًا من ستة أحرف.

  • اسم
    name
    النوع
    string
    وصف

    مطلوب: اسم تختاره، بحد أقصى 80 حرفًا.

  • اسم
    body
    النوع
    string
    وصف

    مطلوب: النص المسجل لدى DLT، بحد أقصى 2,000 حرف، وتُمثّل كل متغير بصيغة {#var#}، حتى 30 متغيرًا.

  • اسم
    variableKeys
    النوع
    string[]
    وصف

    اسم لكل متغير بالترتيب، مثل ["otp", "minutes"]. عند الحذف أو تقديم قائمة فارغة، تُستخدم الأسماء الموضعية من 1 إلى n. وعند تقديمها، يجب أن تكون الأسماء فريدة وتتكون من أحرف أو أرقام ASCII أو _، بطول من 1 إلى 30 حرفًا لكل اسم؛ ويجب أن يساوي عددها عدد المتغيرات.

  • اسم
    type
    النوع
    string
    وصف

    مطلوب: نوع DLT، وهو transactional أو service_implicit أو service_explicit أو promotional.

  • اسم
    unicode
    النوع
    boolean
    وصف

    هل يستخدم النص Unicode؛ الافتراضي false.

  • اسم
    active
    النوع
    boolean
    وصف

    هل يُسمح بإرساله؛ الافتراضي true.

إضافة قالب

curl -X POST https://api.oblic.app/external/v1/sms/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "1107161234567890123",
    "senderId": "EXMPLE",
    "name": "Sign-in code",
    "body": "Your Example code is {#var#}. It is valid for {#var#} minutes.",
    "variableKeys": ["code", "minutes"],
    "type": "service_implicit"
  }'
  • الحسابات التي يسجل Oblic الرسائل النصية لها فقط تستطيع إضافة الرؤوس والقوالب وتعديلها؛ ويُرفض أي حساب آخر بالرمز 403 REGISTRY_NOT_ALLOWED ويستخدم القوالب المُشاركة معه.
  • المشاركة تقبل {"scope": "none" | "all" | "selected", "accounts": […]}، بحد أقصى 1,000 قيمة externalId لحسابات فرعية عند استخدام selected. يجب أن ينتمي كل حساب محدد إلى الحساب الأب. لا تشارك القائمة المحددة الفارغة مع أي حساب فرعي.
  • علامة الرأس الافتراضي تُضبط في كل PUT: إذا لم يتضمن "isDefault": true فلن يكون الرأس افتراضيًا. ويؤدي جعل أحدها افتراضيًا إلى إلغاء هذه الصفة عن الرأس الافتراضي السابق للحساب.
الرفضcdالحالة
400INVALID_TEMPLATEالرأس لا يطابق النوع، أو يتجاوز العدد 30 متغيرًا، أو لا يسمي variableKeys كل متغير مرة واحدة
403REGISTRY_NOT_ALLOWEDالحساب لا يسجل رسائل نصية خاصة به
404TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUNDالقالب أو الرأس أو الحساب الفرعي غير موجود
409TEMPLATE_EXISTSسُجّل بالفعل قالب بذلك المعرّف لدى DLT
409SENDER_IN_USEحذف رأس تستخدمه قوالب
422SENDER_NOT_ALLOWEDالرأس لا ينتمي إلى الحساب
422MESSAGE_TYPE_NOT_ENABLEDنوع القالب ليس من الأنواع التي يرسلها Oblic: قائمة messageTypes للحساب، وافتراضيًا service_implicit فقط

رقم WhatsApp وقوالبه

تُرسل رسالة WhatsApp من رقم WhatsApp Business المتصل بالحساب، باستخدام قالب اعتمدته Meta.

الطريقةالمسارالوظيفة
POST/external/v1/whatsapp/connectionيربط الرقم أو يستبدل الرقم المتصل
GET/external/v1/whatsapp/connectionالرقم المتصل؛ والرمز 404 WHATSAPP_NOT_CONNECTED إن لم يوجد
DELETE/external/v1/whatsapp/connectionيفصل اتصاله: 204
GET/external/v1/whatsapp/templatesالقوالب مع نتيجة مراجعة Meta لكل منها
POST/external/v1/whatsapp/templatesيقدم قالبًا إلى Meta للمراجعة: 201
GET/external/v1/whatsapp/recipients/{number}ما يستطيع الحساب إرساله إلى رقم الآن

الاتصال يستخدم نتيجة Embedded Signup المنفذ بتطبيق Meta الخاص بـ Oblic: code وphoneNumberId وwabaId، واختياريًا businessId، ورمز pin المكوّن من ستة أرقام المستخدم لتسجيل الرقم. تكون قيمة status في الاستجابة INTEGRATED بعد تأكيد جميع خطوات الاتصال؛ ويبقى الاتصال الذي توقف جزئيًا PENDING. أعد المحاولة بمدخلات تسجيل صالحة؛ لا يُضمن عمل رمز مستخدم أو منتهي الصلاحية مرة أخرى. إذا رفضت Meta خطوة، تكون الاستجابة 502 مع رمزها، مثل WHATSAPP_REGISTER_REFUSED، دون إعادة محتوى استجابة Meta الخام.

  • اسم
    name
    النوع
    string
    وصف

    مطلوب: أحرف ASCII صغيرة وأرقام و_، مثل order_shipped. يجب ألا يتجاوز الاسم الموسّع الذي يضم الحساب واللغة لدى Oblic مقدار 100 حرف؛ ويُرفض تجاوزه قبل استدعاء Meta. استخدم name المُعاد عند الإرسال، ولا تفترض أن الاسم القصير المدخل هو الاسم المخزن لدى Meta.

  • اسم
    language
    النوع
    string
    وصف

    لغة القالب: حرفا ASCII صغيران، واختياريًا _ ثم حرفا ASCII كبيران، مثل en أو hi أو en_US؛ وتكون en عند الحذف. يمكن للاسم نفسه أن يملك قالبًا بكل لغة؛ ويؤدي تكرار الاسم واللغة معًا إلى تعارض.

  • اسم
    category
    النوع
    string
    وصف

    مطلوب: MARKETING أو UTILITY أو AUTHENTICATION.

  • اسم
    components
    النوع
    object[]
    وصف

    مطلوب: رأس القالب ونصه وتذييله وأزراره بصيغة Meta، مع أمثلة لمتغيراتها.

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

curl -X POST https://api.oblic.app/external/v1/whatsapp/templates \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "order_shipped",
    "language": "en",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} has shipped.",
        "example": { "body_text": [["Asha", "1042"]] }
      }
    ]
  }'
  • قيمة status للقالب هي حالة مراجعة Meta المخزنة، مثل PENDING أو APPROVED أو REJECTED؛ وقد لا توجد rejectionReason. يعني 201 أنه قُدّم للمراجعة، لا أنه اعتُمد. لا يمكن إرسال إلا قوالب APPROVED. لا يوجد وعد بموعد اكتمال المراجعة.
  • المستلم يعيد number وoptedOut ووقت الإلغاء وطريقته (optedOutAt وoptOutSource) وlastInboundAt وsessionOpenUntil: نافذة 24 ساعة منذ آخر رسالة واردة من الشخص. يخص optedOut التسويق، لا كل الرسائل. عند غياب سجل وارد، تكون lastInboundAt وsessionOpenUntil بقيمة null. لا يضمن الطابع الزمني للجلسة وحده قبول الإرسال؛ فما زالت بقية فحوص الإرسال مطلوبة.
الرفضcdالحالة
409TEMPLATE_EXISTSلدى الحساب قالب بهذا الاسم بهذه اللغة
422WHATSAPP_NOT_CONNECTEDتقديم قالب للمراجعة دون رقم متصل
422TEMPLATE_NAME_TOO_LONGالاسم أطول مما تسمح به Meta
422TEMPLATE_REFUSEDرفضت Meta القالب؛ رسالة رفض عامة محلية، وليست النص الخام لاستجابة Meta
422INVALID_NUMBERرقم المستلم ليس بالتنسيق الدولي
502WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSEDرفضت Meta خطوة من خطوات ربط الرقم
503WHATSAPP_UNAVAILABLEتعذر الوصول إلى Meta أثناء إحدى خطوات الاتصال
هل كانت هذه الصفحة مفيدة؟