قوالب الخدمة

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

تُحتسب رسائل الخدمة كما تُحتسب رسائل التحقق، وتخضع للضوابط نفسها — التحقق من الرصيد، ومهلة إعادة الإرسال لكل رقم، ومفتاح منع التكرار.

إرسال رسائل الخدمة

الخطوات

أنشئ قالب خدمة من قسم "قوالب الخدمة" في لوحة التحكم، محدّدًا الترويسة والمحتوى وأي متغيّرات مثل {{1}}.
انتظر موافقة واتساب على القالب — يمكنك متابعة الحالة في جدول القوالب.
بمجرد أن تصبح الحالة Approved، استدعِ Endpoint أدناه باستخدام معرّف القالب وقيم متغيّراته.

Endpoint

Endpoint:

POSThttps://api.lightotp.com/SendUtilityMessage

البند	القيمة
الطريقة (Method)	`POST`
المسار (Path)	`/SendUtilityMessage`
Content-Type	`application/json`
المصادقة	`Header X-Api-Key`
حالة النجاح	`200 OK`

المصادقة

يجب أن يتضمّن كل طلب مفتاح API الخاص بك في ترويسة X-Api-Key. يمكنك إنشاء مفاتيح API وإدارتها من قسم "مفاتيح API" في لوحة التحكم.

حافظ على سرية مفتاح API. لا تكشفه أبدًا في الشيفرة التي تعمل على المتصفح أو في المستودعات العامة — تعامل معه كأنه كلمة مرور.

Headers

Header	إلزامية	الوصف
`X-Api-Key`	نعم	مفتاح API الخاص بك.
`Content-Type`	نعم	يجب أن يكون application/json.
`Accept-Language`	لا	لغة رسائل الأخطاء (en أو ar).

Body

مثال على الـ Body:

{
  "templateId": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2",
  "toPhoneE164": "+966551234567",
  "headerParameter": "Ahmad",
  "bodyParameters": ["#4021", "March 5"],
  "idempotencyKey": "a3f1c2e4-9b27-4d6a-8e5f-1c2b3d4e5f60"
}

الحقل	النوع	إلزامي	الوصف
`templateId`	`string (uuid)`	نعم	معرّف قالب الخدمة المعتمد الخاص بك.
`toPhoneE164`	`string`	نعم	رقم هاتف المستلم بصيغة E.164، مثل +966551234567.
`headerParameter`	`string`	شرطي	مطلوب فقط عندما تحتوي ترويسة القالب على متغيّر؛ وإلا فاحذفه.
`bodyParameters`	`string[]`	شرطي	قيمة واحدة لكل متغيّر في المحتوى، بالترتيب. يجب أن تطابق عدد المتغيّرات في محتوى القالب.
`idempotencyKey`	`string (uuid)`	لا	مفتاح فريد لإعادة المحاولة بأمان دون إرسال الرسالة مرتين.

المتغيّرات والمعاملات

قد تحتوي القوالب على متغيّرات مرقّمة مثل {{1}} و{{2}}. تُدخل قيمها عند الإرسال:

يملأ headerParameter المتغيّر الوحيد الذي قد تحتويه الترويسة. أرسله فقط عندما تحتوي الترويسة على متغيّر فعليًا، وإلا فسيُرفض الطلب.
bodyParameters مصفوفة مرتّبة: العنصر الأول يحل محل {{1}}، والثاني يحل محل {{2}}، وهكذا. يجب أن يطابق طولها عدد متغيّرات المحتوى تمامًا.

استجابة النجاح — 200 OK

200 OK

{
  "id": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2",
  "messageStatus": "Sent"
}

الحقل	النوع	الوصف
`id`	`string (uuid)`	معرّف الرسالة المنشأة. استخدمه للتحقق من حالة التسليم.
`messageStatus`	`string`	الحالة الأولية للرسالة.

حالة الرسالة

الحالة	المعنى
`Pending`	مقبولة وفي قائمة انتظار الإرسال.
`Sent`	تم تسليمها إلى واتساب.
`Delivered`	تم توصيلها إلى جهاز المستلم.
`Read`	فتحها المستلم.
`Failed`	تعذّر توصيلها.

الأخطاء

تُعاد الأخطاء مع رمز حالة HTTP المطابق ورمز خطأ قابل للقراءة آليًا في جسم الاستجابة.

شكل الخطأ

{
  "errorMessage": "BodyParameterCountMismatch"
}

رموز الأخطاء

الرمز	HTTP	المعنى
`ApiKeyIsRequired`	`400`	ترويسة X-Api-Key مفقودة.
`ApiKeyNotFound`	`404`	لا يوجد مفتاح API يطابق القيمة المُدخلة.
`ApiKeyExpired`	`400`	انتهت صلاحية مفتاح API.
`TemplateIdIsRequired`	`400`	لم يتم تقديم templateId.
`DestinationPhoneNumberIsRequired`	`400`	لم يتم تقديم toPhoneE164.
`TemplateNotFound`	`404`	لا يوجد قالب يطابق templateId المُدخل.
`ThisTemplateIsForAnotherClient`	`400`	القالب لا يخص حسابك.
`TemplateIsNotUtility`	`400`	القالب ليس قالب خدمة.
`TemplateIsRejected`	`400`	تم رفض القالب من قِبل واتساب ولا يمكن استخدامه.
`TemplateIsNotApproved`	`400`	لم تتم الموافقة على القالب بعد (قيد المراجعة أو موقوف أو معطّل).
`HeaderParameterIsRequired`	`400`	تحتوي ترويسة القالب على متغيّر لكن لم يتم تقديم headerParameter.
`HeaderParameterNotAllowed`	`400`	تم تقديم headerParameter لكن ترويسة القالب لا تحتوي على متغيّر.
`BodyParameterCountMismatch`	`400`	عدد bodyParameters لا يطابق متغيّرات القالب.
`InsufficientBalance`	`400`	لا يملك اشتراكك رصيدًا كافيًا لإرسال الرسالة.
`SenderNumberNotFound`	`404`	لا يوجد رقم مُرسِل مُخصّص لحسابك. تواصل مع دعم LightOTP لتخصيص رقم مُرسِل لك.
`رسالة المهلة`	`400`	حاولت مراسلة الرقم نفسه مجددًا بسرعة كبيرة؛ انتظر انتهاء المهلة.

الفوترة والرصيد

تستهلك رسائل الخدمة الرصيد تمامًا مثل رسائل التحقق:

تكلّف كل رسالة نقاطًا بحسب تسعير بلد الوجهة.
لا تُحتسب رسوم على عمليات الإرسال الفاشلة.
يُوسم اشتراكك بأنه منتهٍ عند وصول رصيده إلى الصفر.
يُرسَل بريد تحذيري عند انخفاض رصيدك.

مثال (cURL)

cURL

curl -X POST "https://api.lightotp.com/SendUtilityMessage" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept-Language: en" \
  -d '{
    "templateId": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2",
    "toPhoneE164": "+966551234567",
    "headerParameter": "Ahmad",
    "bodyParameters": ["#4021", "March 5"],
    "idempotencyKey": "a3f1c2e4-9b27-4d6a-8e5f-1c2b3d4e5f60"
  }'