POST/api/v2/templates

إنشاء قالب

ينشئ قالباً من أي نوع مدعوم. قوالب واتساب الرسمية تُرسل إلى ميتا حسب المرسل المعتمد. الاسم إنجليزي صغير مع _. أرفق وسائط الهيدر في نفس طلب multipart، أو ارفع أولاً عبر /api/v2/templates/media ثم مرّر headerAssetId.

متى تستخدمه. عندما يريد نظامك إنشاء قوالب برمجياً ثم إرسالها بعد الاعتماد.

مثال الطلب

مثال صحيح: قالب واتساب كامل (صورة + متغيرات + أزرار)

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"order_ready_notice","category":"whatsapp","subType":"utility","language":"ar","headerType":"image","headerAssetId":"ASSET_ID_FROM_MEDIA_UPLOAD","body":"مرحباً {{1}}، طلبك رقم {{2}} جاهز للاستلام. الإجمالي {{3}} ل.س.","bodyParameters":[{"index":1,"label":"أحمد"},{"index":2,"label":"A-1042"},{"index":3,"label":"25000"}],"footer":"راسل","buttons":[{"type":"url","text":"تتبع الطلب","url":"https://example.com/orders/{{1}}","urlExample":"https://example.com/orders/A-1042"},{"type":"phone","text":"اتصل بنا","url":"+963911111111"}]}'

مثال صحيح: قالب واتساب مع مستند في طلب واحد

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"invoice_notice","category":"whatsapp","subType":"utility","language":"ar","headerType":"document","body":"فاتورتك رقم {{1}} جاهزة.","headerMedia":"<multipart binary PDF>","payload":"{\"bodyParameters\":[{\"index\":1,\"label\":\"A-1042\"}]}","note":"Content-Type: multipart/form-data"}'

مثال صحيح: قالب SMS

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"sms_otp","category":"sms","subType":"otp","content":"رمز التحقق هو {{1}}"}'

مثال خاطئ: خطأ: اسم بحروف عربية

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"تأكيد_الطلب","category":"whatsapp","body":"مرحباً"}'

الاسم يجب أن يكون إنجليزيًا صغيرًا مع شرطة سفلية.

قالب واتساب رسمي تشغيلي مع وسائط الهيدر

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"order_ready_notice","category":"whatsapp","subType":"utility","language":"ar","headerType":"image","headerAssetId":"ASSET_ID_FROM_MEDIA_UPLOAD","body":"مرحباً {{1}}، طلبك رقم {{2}} جاهز للاستلام. الإجمالي {{3}} ل.س.","bodyParameters":[{"index":1,"label":"أحمد"},{"index":2,"label":"A-1042"},{"index":3,"label":"25000"}],"footer":"راسل","buttons":[{"type":"url","text":"تتبع الطلب","url":"https://example.com/orders/{{1}}","urlExample":"https://example.com/orders/A-1042"},{"type":"phone","text":"اتصل بنا","url":"+963911111111"}]}'

JSON path: upload an image via POST /api/v2/templates/media and replace headerAssetId, or send the same fields as multipart with headerMedia. {{1}} {{2}} {{3}} in body are filled from bodyParameters labels (examples for Meta) and later from variablesIndexed when sending. URL button uses {{1}} in the path; send the suffix with template.buttonVariables. Phone button dials the number in url.

قالب واتساب تشغيلي (المتن فقط)

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"order_confirmation","category":"whatsapp","subType":"utility","language":"ar","body":"مرحباً {{1}}، طلبك رقم {{2}} تم تأكيده.","bodyParameters":[{"index":1,"label":"أحمد"},{"index":2,"label":"12345"}]}'

قالب واتساب OTP لنسخ الرمز

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"login_otp","category":"whatsapp","subType":"otp","language":"ar","otpType":"copy_code","addSecurityRecommendation":true,"codeExpirationMinutes":10,"otpButtonText":"Copy code"}'

قالب جلسة واتساب ويب

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"session_welcome","category":"whatsapp","subType":"utility","language":"ar","provider":"user_session","body":"مرحباً {{1}}، شكراً لتواصلك معنا."}'

قالب SMS

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"sms_otp","category":"sms","subType":"otp","content":"رمز التحقق هو {{1}}"}'

قالب بريد

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"welcome_email","category":"email","subType":"utility","emailSubject":"Welcome","content":"<p>Hello {{1}}</p>"}'

ربط قالب واتساب رسمي موجود

curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"eshaar_order_status","creationMode":"manual_external_id","providerTemplateId":"1234567890","subType":"utility","language":"ar","manualVariableCount":2}'

مثال الاستجابة

201 — قالب واتساب كامل (صورة + متغيرات + أزرار)

{  "success": true,  "data": {    "template": {      "id": "6800tpl123def4567890aaaa",      "name": "order_ready_notice",      "category": "whatsapp",      "subType": "utility",      "language": "ar",      "status": "pending",      "headerType": "image",      "headerValue": null,      "headerAssetId": null,      "headerPreviewUrl": null,      "allowsHeaderMediaOverride": true,      "provider": "meta",      "officialSenderId": "platform",      "officialSender": {        "id": "platform",        "scope": "platform",        "isPlatform": true,        "isDefault": true,        "label": null,        "phoneNumber": null,        "displayName": "platform"      },      "isPlatformNumber": true,      "isDefault": false,      "createdAt": "2026-09-01T10:00:00.000Z"    }  }}

201 — قالب واتساب مع مستند في طلب واحد

{  "success": true,  "data": {    "template": {      "id": "6800tpl123def4567890aaaa",      "name": "invoice_notice",      "category": "whatsapp",      "subType": "utility",      "language": "ar",      "status": "pending",      "headerType": "image",      "headerValue": null,      "headerAssetId": null,      "headerPreviewUrl": null,      "allowsHeaderMediaOverride": true,      "provider": "meta",      "officialSenderId": "platform",      "officialSender": {        "id": "platform",        "scope": "platform",        "isPlatform": true,        "isDefault": true,        "label": null,        "phoneNumber": null,        "displayName": "platform"      },      "isPlatformNumber": true,      "isDefault": false,      "createdAt": "2026-09-01T10:00:00.000Z"    }  }}

201 — قالب SMS

{  "success": true,  "data": {    "template": {      "id": "6800tplsms",      "name": "sms_otp",      "category": "sms",      "status": "active"    }  }}

400 — خطأ: اسم بحروف عربية

{  "success": false,  "code": "VALIDATION_ERROR",  "error": "Invalid template name"}

الاسم يجب أن يكون إنجليزيًا صغيرًا مع شرطة سفلية.

401 — مفتاح API مفقود أو غير صالح.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "UNAUTHORIZED",  "error": "Missing or invalid API key"}

403 — الهاتف غير موثّق أو الصلاحية غير كافية (غالباً messages:create أو api_keys:read).

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "FORBIDDEN",  "error": "Phone not verified or missing permission"}

429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "RATE_LIMITED",  "error": "Rate limit exceeded",  "retryAfterSeconds": 30}

طلب HTTP

POST /api/v2/templates

ترويسات الطلب

الترويسة	النوع	الوصف
X-API-Key	string	مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. *

جسم الطلب

الحقل	النوع	الوصف
name	string	الاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار. *
category	enum	فئة القالب: whatsapp أو sms أو message أو email. *
subType	enum	النوع الفرعي مثل utility أو otp أو marketing أو free. *
language	string	لغة قالب ميتا مثل ar أو en. تُستخدم لقوالب واتساب الرسمية.
body	string	متن قالب واتساب مع عناصر نائبة مرقمة. اربطه بـ bodyParameters عند الإنشاء وvariablesIndexed عند الإرسال.
content	string	في الإرسال الموحّد: كائن المحتوى (نص أو رمز OTP أو موضوع البريد). في القوالب: متن SMS أو الرسالة، أو HTML/نص البريد.
emailSubject	string	مطلوب عندما تكون الفئة email.
headerType	enum	نوع الهيدر: text أو image أو video أو document.
headerValue	string	قيمة الهيدر النصي عندما يكون headerType هو text.
headerAssetId	string	المعرّف من مسار رفع الوسائط. غير مطلوب إذا أُرسل headerMedia أو file أو headerMediaUrl.
footer	string	تذييل واتساب اختياري. لا يُستخدم في قوالب جلسة واتساب ويب.
buttons	json	أزرار واتساب المضبوطة على القالب.
bodyParameters	json	قيم أمثلة تُرسل إلى ميتا للعناصر النائبة المرقمة في المتن.
otpType	enum	نوع زر OTP في واتساب الرسمي: copy_code أو one_tap أو zero_tap.
addSecurityRecommendation	boolean	عند true تضيف ميتا سطر توصية الأمان القياسي لرمز OTP.
codeExpirationMinutes	integer	صلاحية رمز OTP بالدقائق (1–90) لقوالب واتساب الرسمية.
otpButtonText	string	تسمية زر نسخ رمز OTP في واتساب الرسمي.
packageName	string	اسم حزمة أندرويد لـ one-tap أو zero-tap.
signatureHash	string	بصمة توقيع تطبيق أندرويد لـ one-tap أو zero-tap.
zeroTapTermsAccepted	boolean	يجب أن تكون true عندما يكون otpType هو zero_tap.
provider	enum	فلتر أو قيمة مزوّد القالب: user_session أو meta أو internal.
templateTarget	enum	ضع user_session لإنشاء قالب جلسة واتساب ويب (نفس provider=user_session).
officialSenderId	string	معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب.
creationMode	enum	استخدم manual_external_id لربط قالب واتساب رسمي موجود مع providerTemplateId.
providerTemplateId	string	معرّف قالب واتساب الرسمي / ميتا عند الربط اليدوي.
manualVariableCount	integer	عدد متغيرات المتن عند ربط قالب رسمي موجود.

حقول الاستجابة

الحقل	النوع	الوصف
success	boolean	صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة.
data	object	البيانات الأساسية في مسارات القوائم وملخص الحساب.
data.template	object	مرجع القالب (id أو key) واللغة والمتغيرات وهيدر اختياري لهذا الإرسال.
data.template.id	string	معرّف المورد.
data.template.name	string	الاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار.
data.template.category	enum	فئة القالب: whatsapp أو sms أو message أو email.
data.template.subType	enum	النوع الفرعي مثل utility أو otp أو marketing أو free.
data.template.status	enum	حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها.
data.template.language	string	لغة قالب ميتا مثل ar أو en. تُستخدم لقوالب واتساب الرسمية.
data.template.body	string	متن قالب واتساب مع عناصر نائبة مرقمة. اربطه بـ bodyParameters عند الإنشاء وvariablesIndexed عند الإرسال.
data.template.bodyParameters	json	قيم أمثلة تُرسل إلى ميتا للعناصر النائبة المرقمة في المتن.
data.template.headerType	enum	نوع الهيدر: text أو image أو video أو document.
data.template.headerValue	string	قيمة الهيدر النصي عندما يكون headerType هو text.
data.template.headerAssetId	string	المعرّف من مسار رفع الوسائط. غير مطلوب إذا أُرسل headerMedia أو file أو headerMediaUrl.
data.template.headerPreviewUrl	string	رابط معاينة لوسائط الهيدر المخزّنة.
data.template.allowsHeaderMediaOverride	boolean	صحيح عندما يقبل هذا القالب الرسمي هيدر ملف أو رابط لكل إرسال.
data.template.footer	string	تذييل واتساب اختياري. لا يُستخدم في قوالب جلسة واتساب ويب.
data.template.buttons	json	أزرار واتساب المضبوطة على القالب.
data.template.urlButtonVariables	json	قيم لواحق أزرار الرابط في هذا القالب.
data.template.indexedPlaceholders	string-list	متغيرات المتن المرقمة، مثل {{1}}.
data.template.content	string	في الإرسال الموحّد: كائن المحتوى (نص أو رمز OTP أو موضوع البريد). في القوالب: متن SMS أو الرسالة، أو HTML/نص البريد.
data.template.parameters	json	القيم التجريبية أو المرتبطة لمتغيرات متن القالب.
data.template.provider	string	فلتر أو قيمة مزوّد القالب: user_session أو meta أو internal.
data.template.providerTemplateId	string	معرّف قالب واتساب الرسمي / ميتا عند الربط اليدوي.
data.template.manualProvider	enum	المزوّد المسجّل عند ربط هذا القالب يدوياً.
data.template.officialSenderId	string	معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب.
data.template.officialSender	object	رقم واتساب الرسمي المرتبط بهذا القالب.
data.template.officialSender.id	string	معرّف المورد.
data.template.officialSender.scope	enum	platform عند استخدام الرقم الافتراضي، وإلا مرسل محدد.
data.template.officialSender.isPlatform	boolean	صحيح عندما يستخدم القالب الرقم الافتراضي للمنصة.
data.template.officialSender.isDefault	boolean	صحيح عندما يكون هذا المرسل أو القالب هو الافتراضي للحساب.
data.template.officialSender.label	string	تسمية المرسل الجاهزة للعرض تجمع الاسم والرقم.
data.template.officialSender.phoneNumber	string	الرقم الظاهر الموثّق بصيغة E.164.
data.template.officialSender.displayName	string	الاسم الظاهر لمرسل واتساب الرسمي.
data.template.isPlatformNumber	boolean	صحيح عندما يكون القالب مرتبطاً برقم المنصة الرسمي الافتراضي.
data.template.isDefault	boolean	صحيح عندما يكون هذا المرسل أو القالب هو الافتراضي للحساب.
data.template.createdAt	string	وقت الإنشاء.
message	string	رسالة نتيجة مقروءة بعد الإنشاء أو الرفع.

رموز الحالة

الحالة	الوصف
201	تم الإنشاء.
400	طلب غير صالح، أو خطأ تحقق، أو المورد لا يمكن استخدامه في هذه الحالة.
401	مفتاح API مفقود أو غير صالح.
403	الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء.
409	تعارض، مثل إعادة استخدام مفتاح Idempotency بجسم مختلف، أو جلسة غير جاهزة.
429	تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى.
503	المزوّد غير متاح أو انتهت مهلة الاتصال.

جرّب الطلب

مفتاح الـ API

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

المثال

المتغيرات

رقم المرسلofficialSenderId

معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب.

name*

الاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار.

category*

فئة القالب: whatsapp أو sms أو message أو email.

subType*

النوع الفرعي مثل utility أو otp أو marketing أو free.

language

لغة قالب ميتا مثل ar أو en. تُستخدم لقوالب واتساب الرسمية.

body

متن قالب واتساب مع عناصر نائبة مرقمة. اربطه بـ bodyParameters عند الإنشاء وvariablesIndexed عند الإرسال.

content

في الإرسال الموحّد: كائن المحتوى (نص أو رمز OTP أو موضوع البريد). في القوالب: متن SMS أو الرسالة، أو HTML/نص البريد.

emailSubject

مطلوب عندما تكون الفئة email.

headerType

نوع الهيدر: text أو image أو video أو document.

headerValue

قيمة الهيدر النصي عندما يكون headerType هو text.

headerAssetId

المعرّف من مسار رفع الوسائط. غير مطلوب إذا أُرسل headerMedia أو file أو headerMediaUrl.

footer

تذييل واتساب اختياري. لا يُستخدم في قوالب جلسة واتساب ويب.

buttons

أزرار واتساب المضبوطة على القالب.

bodyParameters

قيم أمثلة تُرسل إلى ميتا للعناصر النائبة المرقمة في المتن.

otpType

نوع زر OTP في واتساب الرسمي: copy_code أو one_tap أو zero_tap.

addSecurityRecommendation

عند true تضيف ميتا سطر توصية الأمان القياسي لرمز OTP.

codeExpirationMinutes

صلاحية رمز OTP بالدقائق (1–90) لقوالب واتساب الرسمية.

otpButtonText

تسمية زر نسخ رمز OTP في واتساب الرسمي.

packageName

اسم حزمة أندرويد لـ one-tap أو zero-tap.

signatureHash

بصمة توقيع تطبيق أندرويد لـ one-tap أو zero-tap.

zeroTapTermsAccepted

يجب أن تكون true عندما يكون otpType هو zero_tap.

provider

فلتر أو قيمة مزوّد القالب: user_session أو meta أو internal.

templateTarget

ضع user_session لإنشاء قالب جلسة واتساب ويب (نفس provider=user_session).

creationMode

استخدم manual_external_id لربط قالب واتساب رسمي موجود مع providerTemplateId.

providerTemplateId

معرّف قالب واتساب الرسمي / ميتا عند الربط اليدوي.

manualVariableCount

عدد متغيرات المتن عند ربط قالب رسمي موجود.

الطلب

{  "name": "order_ready_notice",  "category": "whatsapp",  "subType": "utility",  "language": "ar",  "headerType": "image",  "headerAssetId": "ASSET_ID_FROM_MEDIA_UPLOAD",  "body": "مرحباً {{1}}، طلبك رقم {{2}} جاهز للاستلام. الإجمالي {{3}} ل.س.",  "bodyParameters": [    {      "index": 1,      "label": "أحمد"    },    {      "index": 2,      "label": "A-1042"    },    {      "index": 3,      "label": "25000"    }  ],  "footer": "راسل",  "buttons": [    {      "type": "url",      "text": "تتبع الطلب",      "url": "https://example.com/orders/{{1}}",      "urlExample": "https://example.com/orders/A-1042"    },    {      "type": "phone",      "text": "اتصل بنا",      "url": "+963911111111"    }  ]}

الاستجابة

نفّذ طلباً لعرض الاستجابة.