تخطَّ إلى المحتوى
ساعيv1

القوالب

عرض بصيغة Markdown

قوالب واتساب المعتمدة: اعرف ما يحتاجه كل قالب وأنشئ قوالب جديدة.

القالب رسالة اعتمدها واتساب مسبقًا. وهو الطريقة الوحيدة لبدء محادثة أو للكتابة بعد نافذة الـ24 ساعة، لذلك تستخدمه تحديثات الطلبات والتذكيرات ورموز التحقق والحملات.

كيف يعمل: القوالباعرف ما يحتاجه القالب · أرسل قالبًا · أنشئ قالبًا · الاعتماد · احذف قالبًا

اعرف ما يحتاجه القالب#

يعرض GET /templates قوالبك، ويوضح كل قالب ما يجب تعبئته عند الإرسال:

JSON
{
  "id": "tpl_27",
  "name": "order_update",
  "language": "ar",
  "status": "approved",
  "variables": { "body": 2, "buttons": [{ "index": 0, "type": "url" }] },
  "send_example": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": "ar",
      "variables": { "body": ["value 1", "value 2"], "buttons": { "0": { "url_suffix": "value" } } }
    }
  }
}

send_example جسم جاهز لـ POST /messages: أضف to واستبدل القيم ثم أرسل. لا يمكن إرسال إلا القوالب ذات الحالة approved.

أرسل قالبًا#

JSON
{
  "to": "+966501234567",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": "ar",
    "variables": {
      "body": ["سارة", "#10482"],
      "buttons": { "0": { "url_suffix": "10482" } }
    }
  }
}
المتغيرما يعبّئه
bodyالمتغيرات {{1}} و{{2}}… في نص القالب، بالترتيب
header_textالمتغير {{1}} في ترويسة نصية
header_media_linkترويسة صورة أو فيديو أو مستند، كرابط https:// عام
buttonsحسب ترتيب الزر: url_suffix (المتغير {{1}} في زر الرابط)، وcoupon_code (زر نسخ الرمز)، وpayload (زر الرد السريع)

يُرفض العدد الخاطئ لقيم النص فورًا بالخطأ template_variables_mismatch، بدل أن يفشل لاحقًا عند واتساب.

أنشئ قالبًا#

يرسل POST /templates القالب إلى واتساب. يأخذ مكوّنات واتساب نفسها، ويحتاج كل متغير {{n}} إلى قيمة مثال:

JSON
{
  "name": "order_shipped",
  "language": "ar",
  "category": "utility",
  "components": [
    {
      "type": "BODY",
      "text": "مرحبًا {{1}}، شُحن طلبك رقم {{2}} وسيصلك خلال يومين.",
      "example": { "body_text": [["سارة", "10482"]] }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "URL", "text": "تتبّع الشحنة", "url": "https://shop.example.com/track/{{1}}", "example": ["https://shop.example.com/track/10482"] }
      ]
    }
  ]
}
  • الفئات. utility لشيء ينتظره العميل (طلب أو موعد)، وmarketing للعروض الترويجية، وauthentication للرموز لمرة واحدة وتأخذ otp بدل components.
  • ترويسات الوسائط. ارفع الملف عبر POST /media وضع معرّفه med_… في example.header_handle للترويسة: نسلّمه نحن إلى واتساب، وتستخدم الإرسالات اللاحقة هذا الملف ما لم ترسل header_media_link.
  • الفحوص أولًا. تُفحص صيغة الاسم (حروف صغيرة وأرقام و_)، وأطوال المكوّنات، وعدد الأزرار، وقائمة اللغات، وتفرّد الاسم على حساب واتساب للرقم، قبل أن يصل أي شيء إلى واتساب.

الاعتماد#

يبدأ القالب الجديد بحالة pending. عادةً يقرر واتساب خلال دقائق، وأحيانًا حتى 24 ساعة، ويصلك حدث template.status_changed:

الحالةالمعنى
approvedجاهز للإرسال
rejectedمرفوض، ويذكر rejection_reason سبب واتساب إن أعطى سببًا
pausedأوقفه واتساب مؤقتًا بعد ملاحظات سلبية
disabledأُوقف نهائيًا

قد ينقل واتساب قالبًا معتمدًا إلى فئة أخرى (مثلًا من utility إلى marketing)، فيتغير سعره. يعرض الحقل category دائمًا الفئة الحالية.

احذف قالبًا#

يحذف DELETE /templates/{id} القالب هنا وفي واتساب. يُرفض ما دامت حملة مجدولة أو جارية تستخدمه. ولا يسمح واتساب باستخدام الاسم نفسه مجددًا لمدة 30 يومًا.

نقاط الواجهة

عرض القوالب

gethttps://api.saei.automize.sa/v1/templates
  • الصلاحية: templates:read
  • يعمل في وضع الاختبار

قوالب رسائل واتساب الخاصة بك. يوضّح كل قالب ما يحتاج تعبئته (variables) ويحمل send_example جاهزًا للصق في POST /v1/messages.

معاملات الاستعلام

  • limitintegerاختياري

    عدد العناصر المطلوبة، من 1 إلى 100.

  • cursorstringاختياري

    قيمة next_cursor من الصفحة السابقة.

  • statusstringاختياري

    إحدى القيمapprovedpendingrejectedpauseddisableddraft

  • categorystringاختياري

    إحدى القيمmarketingutilityauthentication

  • languagestringاختياري

    رمز لغة، مثل ar أو en_US.

  • namestringاختياري

    اسم القالب بالضبط.

حقول الاستجابة200
  • object"list"مطلوب
  • dataarray<Template>مطلوب
    الحقول الفرعية (12)
    • idstringمطلوب
    • object"template"مطلوب
    • namestringمطلوب
    • languagestring | nullمطلوب
    • categorystring | nullاختياري

      إحدى القيمmarketingutilityauthenticationnull

    • statusstringمطلوب

      لا يمكن إرسال إلا القوالب ذات الحالة approved.

    • rejection_reasonstring | nullاختياري
    • componentsarrayمطلوب

      HEADER وBODY وFOOTER وBUTTONS كما يحفظها واتساب تمامًا.

    • variablesobjectمطلوب

      ما يجب تعبئته عند الإرسال: header (نوع الترويسة التي تحتاج قيمة)، وbody (عدد المتغيرات {{n}})، وbuttons (الأزرار التي تحتاج قيمة).

      الحقول الفرعية (3)
      • headerstringاختياري
      • bodyintegerاختياري
      • buttonsarray<object>اختياري
        الحقول الفرعية (2)
        • indexintegerاختياري
        • typestringاختياري
    • send_exampleobjectمطلوب

      جسم طلب POST /v1/messages لهذا القالب بقيم تجريبية. أضف to وقيمك.

    • created_atstring | nullاختياري
    • updated_atstring | nullاختياري
  • has_morebooleanمطلوب
  • next_cursorstring | nullمطلوب
الأخطاء المحتملة2
جرّبها
curl -X GET https://api.saei.automize.sa/v1/templates \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

صفحة من القوالب.

{
  "object": "list",
  "data": [
    {
      "id": "tpl_27",
      "object": "template",
      "name": "string",
      "language": "string",
      "category": "marketing",
      "status": "string",
      "rejection_reason": "string",
      "components": [],
      "variables": {
        "header": "string",
        "body": 0,
        "buttons": [
          {
            "index": null,
            "type": null
          }
        ]
      },
      "send_example": {},
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

إنشاء قالب

posthttps://api.saei.automize.sa/v1/templates
  • الصلاحية: templates:write
  • لمفاتيح التشغيل فقط
  • يقبل Idempotency-Key

يرسل قالبًا جديدًا إلى واتساب لاعتماده. يعود بحالة pending، وعادةً يقرر واتساب خلال دقائق (وأحيانًا حتى 24 ساعة)، ويصلك حدث template.status_changed عند القرار.

components هي مكوّنات واتساب نفسها: HEADER وBODY (إلزامي) وFOOTER وBUTTONS. يحتاج كل متغير {{n}} إلى قيمة example، وإلا رفض واتساب القالب. تُجرى فحوص منشئ القوالب أولًا (الأطوال، عدد الأزرار، قائمة اللغات، تفرّد الاسم لكل حساب واتساب)، فتعود معظم الأخطاء فورًا كـ parameter_invalid.

لترويسة صورة أو فيديو أو مستند، ارفع الملف عبر POST /v1/media وضع معرّفه med_… في example.header_handle: نسلّمه نحن إلى واتساب، ويُرسل القالب بهذا الملف افتراضيًا.

قوالب التحقق (OTP) تأخذ otp بدل components، وتحتاج باقة تشمل التحقق عبر OTP ونشاطًا تجاريًا موثّقًا من Meta.

الترويسات

  • Idempotency-Keystringاختياري

    أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

  • namestringمطلوب

    حروف إنجليزية صغيرة وأرقام وشرطة سفلية، مثل order_shipped.

  • languagestringمطلوب
  • categorystringمطلوب

    إحدى القيمmarketingutilityauthentication

  • number_idstringاختياري

    أي رقم يحتفظ حساب واتساب الخاص به بالقالب. الافتراضي: رقمك الافتراضي.

  • componentsarrayاختياري

    مكوّنات قالب واتساب (HEADER وBODY وFOOTER وBUTTONS)، ولكل متغير {{n}} قيمة example.

  • otpobjectاختياري

    لفئة authentication: button_text (مثل "نسخ الرمز")، واختياريًا code_expiration_minutes وshow_security_recommendation.

حقول الاستجابة201
  • idstringمطلوب
  • object"template"مطلوب
  • namestringمطلوب
  • languagestring | nullمطلوب
  • categorystring | nullاختياري

    إحدى القيمmarketingutilityauthenticationnull

  • statusstringمطلوب

    لا يمكن إرسال إلا القوالب ذات الحالة approved.

  • rejection_reasonstring | nullاختياري
  • componentsarrayمطلوب

    HEADER وBODY وFOOTER وBUTTONS كما يحفظها واتساب تمامًا.

  • variablesobjectمطلوب

    ما يجب تعبئته عند الإرسال: header (نوع الترويسة التي تحتاج قيمة)، وbody (عدد المتغيرات {{n}})، وbuttons (الأزرار التي تحتاج قيمة).

    الحقول الفرعية (3)
    • headerstringاختياري
    • bodyintegerاختياري
    • buttonsarray<object>اختياري
      الحقول الفرعية (2)
      • indexintegerاختياري
      • typestringاختياري
  • send_exampleobjectمطلوب

    جسم طلب POST /v1/messages لهذا القالب بقيم تجريبية. أضف to وقيمك.

  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة9
جرّبها
مثال
curl -X POST https://api.saei.automize.sa/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "order_shipped",
  "language": "ar",
  "category": "utility",
  "components": [
    {
      "type": "BODY",
      "text": "مرحبًا {{1}}، شُحن طلبك رقم {{2}} وسيصلك خلال يومين.",
      "example": {
        "body_text": [
          [
            "سارة",
            "10482"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "تتبّع الشحنة",
          "url": "https://shop.example.com/track/{{1}}",
          "example": [
            "https://shop.example.com/track/10482"
          ]
        }
      ]
    }
  ]
}'
الاستجابة

أُرسل إلى واتساب، والحالة `pending`.

{
  "id": "tpl_27",
  "object": "template",
  "name": "string",
  "language": "string",
  "category": "marketing",
  "status": "string",
  "rejection_reason": "string",
  "components": [],
  "variables": {
    "header": "string",
    "body": 0,
    "buttons": [
      {
        "index": 0,
        "type": "string"
      }
    ]
  },
  "send_example": {},
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

جلب قالب

gethttps://api.saei.automize.sa/v1/templates/{id}
  • الصلاحية: templates:read
  • يعمل في وضع الاختبار

قالب واحد ومكوّناته كما اعتمدها واتساب، وسبب الرفض من واتساب للقالب المرفوض إن ذكره.

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

حقول الاستجابة200
  • idstringمطلوب
  • object"template"مطلوب
  • namestringمطلوب
  • languagestring | nullمطلوب
  • categorystring | nullاختياري

    إحدى القيمmarketingutilityauthenticationnull

  • statusstringمطلوب

    لا يمكن إرسال إلا القوالب ذات الحالة approved.

  • rejection_reasonstring | nullاختياري
  • componentsarrayمطلوب

    HEADER وBODY وFOOTER وBUTTONS كما يحفظها واتساب تمامًا.

  • variablesobjectمطلوب

    ما يجب تعبئته عند الإرسال: header (نوع الترويسة التي تحتاج قيمة)، وbody (عدد المتغيرات {{n}})، وbuttons (الأزرار التي تحتاج قيمة).

    الحقول الفرعية (3)
    • headerstringاختياري
    • bodyintegerاختياري
    • buttonsarray<object>اختياري
      الحقول الفرعية (2)
      • indexintegerاختياري
      • typestringاختياري
  • send_exampleobjectمطلوب

    جسم طلب POST /v1/messages لهذا القالب بقيم تجريبية. أضف to وقيمك.

  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة2
جرّبها
curl -X GET https://api.saei.automize.sa/v1/templates/tpl_27 \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

القالب.

{
  "id": "tpl_27",
  "object": "template",
  "name": "order_update",
  "language": "ar",
  "category": "utility",
  "status": "approved",
  "rejection_reason": null,
  "components": [
    {
      "type": "BODY",
      "text": "مرحبًا {{1}}، طلبك {{2}} في الطريق."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "تتبّع الطلب",
          "url": "https://shop.example.com/track/{{1}}"
        }
      ]
    }
  ],
  "variables": {
    "body": 2,
    "buttons": [
      {
        "index": 0,
        "type": "url"
      }
    ]
  },
  "send_example": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": "ar",
      "variables": {
        "body": [
          "value 1",
          "value 2"
        ],
        "buttons": [
          {
            "url_suffix": "value"
          }
        ]
      }
    }
  },
  "created_at": "2026-08-01T10:00:00Z",
  "updated_at": "2026-08-02T07:30:00Z"
}

حذف قالب

deletehttps://api.saei.automize.sa/v1/templates/{id}
  • الصلاحية: templates:write
  • لمفاتيح التشغيل فقط

يحذف القالب هنا وفي واتساب. يُرفض بـ resource_in_use ما دامت حملة مجدولة أو جارية تستخدمه. لا يسمح واتساب بإعادة استخدام الاسم نفسه لمدة 30 يومًا.

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

حقول الاستجابة200
  • idstringمطلوب
  • objectstringمطلوب
  • deletedtrueمطلوب
الأخطاء المحتملة4
جرّبها
curl -X DELETE https://api.saei.automize.sa/v1/templates/tpl_27 \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

تم الحذف.

{
  "id": "tpl_27",
  "object": "template",
  "deleted": true
}