القوالب
أدِر القوالب التي يرسل بها الحساب: قوالب البريد الإلكتروني ورؤوس الرسائل النصية وقوالب DLT ورقم WhatsApp وقوالبه. تتطلب قراءتها نطاق الإرسال للقناة أو templates:manage؛ ويتطلب تعديلها مفتاح Owner أو Admin يحمل templates:manage.
تستخدم مسارات /external/v1 هذه مفاتيح API. تستخدم رموز وصول OAuth واجهة API v2؛ ووجود مثال لا يثبت أن بيئة النشر مهيأة لذلك الإصدار.
قوالب البريد الإلكتروني
قوالب البريد الإلكتروني للحساب هي قوالب مساحة عمله الافتراضية، حيث توجد رسائل 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 | الحالة |
|---|---|---|
| 400 | TEMPLATE_TOO_LARGE | حجم HTML أكبر من 65,535 بايت |
| 404 | TEMPLATE_NOT_FOUND | لا يملك الحساب قالبًا بذلك المعرّف |
| 409 | TEMPLATE_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 | الحالة |
|---|---|---|
| 400 | INVALID_TEMPLATE | الرأس لا يطابق النوع، أو يتجاوز العدد 30 متغيرًا، أو لا يسمي variableKeys كل متغير مرة واحدة |
| 403 | REGISTRY_NOT_ALLOWED | الحساب لا يسجل رسائل نصية خاصة به |
| 404 | TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND | القالب أو الرأس أو الحساب الفرعي غير موجود |
| 409 | TEMPLATE_EXISTS | سُجّل بالفعل قالب بذلك المعرّف لدى DLT |
| 409 | SENDER_IN_USE | حذف رأس تستخدمه قوالب |
| 422 | SENDER_NOT_ALLOWED | الرأس لا ينتمي إلى الحساب |
| 422 | MESSAGE_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 | الحالة |
|---|---|---|
| 409 | TEMPLATE_EXISTS | لدى الحساب قالب بهذا الاسم بهذه اللغة |
| 422 | WHATSAPP_NOT_CONNECTED | تقديم قالب للمراجعة دون رقم متصل |
| 422 | TEMPLATE_NAME_TOO_LONG | الاسم أطول مما تسمح به Meta |
| 422 | TEMPLATE_REFUSED | رفضت Meta القالب؛ رسالة رفض عامة محلية، وليست النص الخام لاستجابة Meta |
| 422 | INVALID_NUMBER | رقم المستلم ليس بالتنسيق الدولي |
| 502 | WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSED | رفضت Meta خطوة من خطوات ربط الرقم |
| 503 | WHATSAPP_UNAVAILABLE | تعذر الوصول إلى Meta أثناء إحدى خطوات الاتصال |