إنشاء القوالب وإدارتها

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

يمكن إنشاء القوالب باستخدام API إدارة الأعمال أو حساب مدير واتساب للأعمال. يتم تحديد عدد القوالب التي يمكن أن يمتلكها حساب واتساب للأعمال حسب النشاط التجاري الأصل. إذا لم يتم التحقق من النشاط التجاري الأصل، فسيتم تقييد كل حساب من حسابات واتساب للأعمال عند 250 قالبًا. مع ذلك، إذا تم التحقق من النشاط التجاري الأصل وكان أحد حسابات واتساب للأعمال على الأقل لديه رقم هاتف نشاط تجاري مع اسم عرض تمت الموافقة عليه، فيمكن أن يحصل كل حساب من حسابات واتساب للأعمال على ما يصل إلى 6,000 قالب.

قبل البدء

ستحتاج إلى ما يلي:

• رمز وصول مستخدم النظام المرتبط بالنشاط التجاري
• الإذن whatsapp_business_management
• معرف حساب واتساب للأعمال للنشاط التجاري
• اسم مستخدم أصول الوسائط لأي مستند أو صورة أو ملف فيديو يتم استخدامه في قالب الوسائط. للحصول على اسم مستخدم أصول الوسائط، يجب تحميل أصول الوسائط باستخدام API التحميل القابل للاستئناف.

التقييدات

• يتم تقييد حقل اسم قالب الرسالة عند 512 حرفًا.
• يتم تقييد حقل محتوى قالب الرسالة عند 1024 حرفًا.
• يمكن تعديل القالب فقط عندما يكون بالحالة معتمد أو مرفوض أو متوقف مؤقتًا. يمكن تعديل القالب مرة واحدة يوميًا، وما يصل إلى 10 مرات شهريًا.
• لا يمكن لحسابات واتساب للأعمال سوى إنشاء 100 قالب رسالة في الساعة.
• لا يمكن عرض القوالب المكونة من 4 أزرار أو أكثر، أو زر الرد السريع وزر واحد أو أكثر من نوع آخر، لعملاء واتساب للكمبيوتر. ستتم مطالبة مستخدمي واتساب الذين يتلقون إحدى رسائل القوالب هذه بعرض الرسالة على الهاتف بدلاً من ذلك.

التطويع المحلي

يمكنك إضافة قالب رسالة بلغة محددة عند إنشاء القالب. ويتم احتساب هذه القوالب ضمن التقييد. حافظ على الاتساق عند توفير الترجمات. راجع مقالة مركز المساعدة لماذا تظهر لي أخطاء "عدم توفر البنية" في عملية الاستدعاء التي أجريها؟ لمزيد من المعلومات.

إنشاء القوالب

أرسل طلب POST إلى نقطة النهاية حساب واتساب للأعمال > قوالب الرسائل لإنشاء القالب.

بنية الطلب

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

نص المنشور

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

خصائص النص

فئات القالب

يجب تصنيف القوالب بإحدى الفئات التالية. تلعب الفئات دورًا في التسعير وسيتم التحقق من صلاحية الفئة التي تحددها في وقت إنشاء القالب.

• AUTHENTICATION
• MARKETING
• UTILITY

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

مكونات القالب

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

عند إنشاء قالب، حدّد المكونات من خلال تعيين مصفوفة كائنات المكون على الخاصية components في نص الطلب.

على سبيل المثال، فيما يلي مصفوفة تحتوي على مكون نص أساسي بمتغيرين وعينات قيم، ومكون زر رقم الهاتف ومكون زر عنوان URL:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

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

لاحظ أن القوالب التي تم تصنيفها كـ AUTHENTICATION تتمتع بمتطلبات مكونات فريدة. راجع قوالب المصادقة.

التحقق من القالب

عند إرسال طلب إنشاء قالب، يتم التحقق من الفئة فورًا باستخدام إرشادات تصنيف القالب.

• إذا وافقنا على الفئة التي حددتها، فسننشئ القالب وسنقوم بتعيين status على PENDING. ثم يخضع القالب إلى عملية مراجعة القالب.
• إذا لم نوافق على ما تم تحديده، فسننشئ القالب ولكن سنقوم بتعيين status على REJECTED وتشغيل حدث webhook تحديث حالة قالب الرسالة مع تعيين reason على INCORRECT_CATEGORY. نوصي باتباع حدث webhook هذا لتحديد القوالب المرفوضة أو طلب الحقل rejected_reason في القوالب التي تم إنشاؤها مؤخرًا، والتي ستكون لها القيمة TAG_CONTENT_MISMATCH.

في كلتا الحالتين، يتم إرجاع الحالة الأولية للقالب كجزء من استجابة API.

إذا تم تعيين حالة القالب على REJECTED كجزء من عملية التحقق من الفئة، فسيكون لديك خيارات متعددة:

• تعديل مكونات القالب حتى تمتثل للإرشادات.
• تعديل فئة القالب حتى تمتثل للإرشادات.
• إنشاء قالب جديد.

التصنيف التلقائي

يمكنك تضمين الخاصية allow_category_change في الطلب لكي نقوم تلقائيًا بتعيين الفئة استنادًا إلى محتويات القالب وإرشادات تصنيف القالب. بإمكان ذلك منع تعيين حالة القالب على الفور على REJECTED بسبب سوء التصنيف.

لاحظ أنه يمكن فقط تمكين التصنيف التلقائي عند إنشاء قالب.

مراجعة القالب

تخضع القوالب ذات الحالة PENDING إلى مراجعة القالب. تتم مراجعة محتويات كل قالب تم تعديله أو إنشاؤه مؤخرًا للتأكد من امتثاله لإرشادات وسياسات المحتوى. استنادًا إلى نتائج هذه المراجعة، سنعمل تلقائيًا على تغيير الحالة إلى APPROVED أو REJECTED، والتي تعمل على تشغيل حدث webhook تحديث حالة قالب الرسالة.

حالة القالب

استنادًا إلى نتائج التحقق من الفئة ومراجعة القالب، نعمل على تعيين status أو تغييرها للقالب إلى إحدى القيم التالية:

• APPROVED — اجتاز القالب مراجعة القالب وتمت الموافقة عليه، ويمكن الآن إرساله في رسائل القالب.
• PENDING — اجتاز القالب التحقق من الفئة ويخضع لمراجعة القالب.
• REJECTED — فشل القالب في اجتياز التحقق من الفئة أو مراجعة القالب. يمكنك طلب الحقل rejected_reason في القالب للحصول على السبب.

راجع مرجع نقطة النهاية قالب رسالة واتساب لمعرفة كل الحقول والحالات المحتملة.

الاستجابة

عند نجاح العملية، تستجيب API بمعرف وحالة وفئة القالب الذي تم إنشاؤه مؤخرًا. توجد ثلاث نتائج محتملة:

• وافقنا الفئة التي حددتها ويخضع القالب الآن لمراجعة القالب (status تكون PENDING).
• لم نوافق على الفئة التي حددتها (status تكون REJECTED)
• تمت الموافقة على القالب تلقائيًا (status تكون APPROVED). هذا غير ممكن إلا لقوالب المصادقة التي تتضمن أزرار كلمة السر لمرة واحدة.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

خصائص الاستجابة

مثال على الطلب

فيما يلي مثال على طلب إنشاء قالب عرض ترويجي موسمي يتكون من المكونات التالية:

• عنوان نصي
• نص أساسي
• تذييل
• زرا الرد السريع

للحصول على أمثلة إضافية، راجع أمثلة الطلبات.

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

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

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

إرسال القوالب

استخدم API السحابة أو API داخل المواقع لإرسال قالب في رسالة قالب.

فترة الصلاحية (TTL): التخصيص والإعدادات الافتراضية والقيم الدنيا/القصوى والتوافق

إذا تعذر عليك تسليم الرسالة إلى مستخدم واتساب، فسنعيد محاولة التسليم لفترة من الزمن تُسمى فترة الصلاحية (TTL) أو فترو صلاحية الرسالة.

يمكنك تخصيص فترة الصلاحية (TTL) الافتراضية لقوالب المصادقة والمساعدة والتسويق.

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

جدول الإعدادات الافتراضية والقيم القصوى/الدنيا والتوافق

كيفية تخصيص فترة الصلاحية للقالب

لتعيين فترة صلاحية مخصصة في قالب مصادقة أو مساعدة أو تسويق، يجب تضمين قيمة الخاصية message_send_ttl_seconds وتعيينها في استدعاء POST /<PHONE_NUMBER_ID>/messages.

يمكن تخصيص فترة الصلاحية بزيادات قدرها ثانية واحدة.

قيم خاصية message_send_ttl_seconds الصالحة

• قوالب المصادقة: من 30 إلى 900 ثانية (من 30 ثانية إلى 15 دقيقة)
• قوالب المساعدة: من 30 إلى 43200 ثانية (من 30 ثانية إلى 12 ساعة)
• قوالب التسويق: من 43200 إلى 2592000 (من 12 ساعة إلى 30 يومًا)

بالنسبة لقوالب المصادقة والمساعدة، يمكنك تعيين قيمة الخاصية message_send_ttl_seconds على -1، ما سيؤدي إلى تعيين فترة صلاحية افتراضية مدتها 30 يومًا.

عند تجاوز فترة الصلاحية: يتم تجاهل الرسائل

سيتم تجاهل الرسائل التي يتعذر تسليمها ضمن فترة الصلاحية الافتراضية أو المخصصة.

إذا لم تستلم حدث webhook للرسالة التي تم تسليمها قبل تجاوز فترة الصلاحية، فافترض أنه قد تم تجاهل الرسالة.

إذا أرسلت رسالة وتعذر تسليمها، فقد يكون هناك تأخير بسيط قبل استلامك لحدث webhook، لذا يمكنك توفير فترة مؤقتة إضافية قبل افتراض أن الرسالة قد تم تجاهلها.

أفضل الممارسات حول قوالب التسويق

زر إلغاء الاشتراك في التسويق

نوصي بإضافة زر الرد السريع إلى قوالب تم تصنيفها كـ MARKETING التي تعمل على تسهيل إلغاء اشتراك العملاء من الرسائل التسويقية. هذا يعطي للعملاء خيار إلغاء اشتراك الرسائل التسويقية دون الحاجة إلى حظر النشاط التجاري. نتيجة لذلك، قد تتمكن من زيادة معدل الرسائل بشكل أسرع. يُرجى الرجوع إلى هذه المقالة لمزيد من التفاصيل حول مزايا إضافة زر إلغاء اشتراك إلى قوالب التسويق.

الحصول على القوالب

أرسل طلب GET إلى نقطة النهاية حساب واتساب للأعمال > قوالب الرسالة للحصول على قائمة القوالب المملوكة لحساب واتساب للأعمال.

بنية الطلب

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

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

مثال على الطلب

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

مثال على الطلب (القوالب المرفوضة)

يمكنك إرجاع فقط القوالب بقيم الحقل المحددة من خلال تضمين الحقل والقيمة المرغوبة في الطلب. على سبيل المثال، قم بتضمين status=REJECTED للحصول فقط على القوالب المرفوضة.

curl 'https://graph.facebook.com/v21.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

استرداد مساحة اسم القالب

يلزم توفير مساحة اسم قالب الرسالة لإرسال الرسائل باستخدام قوالب الرسائل.

للحصول على مساحة الاسم لقالب ما، أرسل طلب GET إلى نقطة النهاية /{whatsapp-business-account-ID} وقم بتضمين الحقل message_template_namespace.

مثال على الطلب

curl -i -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

في حالة نجاح العملية، يتم إرجاع كائن بلغة JSON يتضمن معرف حساب واتساب للأعمال ومساحة الاسم:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

تعديل القوالب

أرسل طلب POST إلى نقطة النهاية قالب رسالة واتساب لتعديل القالب. يمكنك أيضًا تعديل القالب يدويًا باستخدام لوحة مدير واتساب > أدوات الحساب > لوحة قوالب الرسائل.

التقييدات

• لا يمكن تعديل القوالب إلا بالحالة APPROVED أو REJECTED أو PAUSED.
• لا يمكنك تعديل إلا category أو components للقالب.
• يتعذر عليك تعديل category في قالب تمت الموافقة عليه.
• يمكن تعديل القوالب التي تمت الموافقة عليها حتى 10 مرات في فترة مدتها 30 يومًا أو مرة واحدة في فترة مدتها 24 ساعة. يمكن تعديل القوالب المرفوضة أو الموقوفة مؤقتًا لعدد غير محدود من المرات.
• بعد تعديل القالب الذي تمت الموافقة عليه أو الموقوف مؤقتًا، ستتم الموافقة عليه تلقائيًا إلا إذا فشل في عملية مراجعة القوالب.

بنية الطلب

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

نص المنشور

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

الخصائص

مثال على الطلب (تعديل المكونات)

مثال على طلب النص الأساسي للقالب الذي يحتوي على محتوى تسويق وأداة مساعدة بحيث يتضمن محتوى تسويقي فقط.

curl 'https://graph.facebook.com/v21.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

مثال على الطلب (تعديل الفئة فقط)

مثال على طلب تغيير فئة القالب من UTILITY إلى MARKETING.

curl 'https://graph.facebook.com/v21.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

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

مثال على الطلب عند النجاح.

{
  "success": true
}

حذف القوالب

استخدم نقطة نهاية حساب واتساب للأعمال > قوالب الرسائل لحذف القالب حسب الاسم أو حسب المعرف.

ملاحظات

• إذا حذفت قالب تم إرساله في رسالة قالب ولكن لم يتم تسليمه بعد (على سبيل المثال، لأن هاتف العميل مغلق)، فسيتم تعيين حالة القالب إلى PENDING_DELETION وسنحاول تسليم الرسالة لمدة 30 يومًا. بعد هذه المدة ستتلقى الخطأ "البنية غير متوفرة" ولن يتلقى العميل الرسالة.
• لا يمكن استخدام أسماء القالب المُعتمد الذي تم حذفه مرة أخرى لمدة 30 يومًا.

الحذف حسب الاسم

يعمل حذف القالب حسب الاسم على حذف كل القوالب التي تطابق ذلك الاسم (أي أنه سيتم حذف القوالب ذات الاسم نفسه ولكن بلغات مختلفة).

بنية الطلب

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

مثال على الطلب

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "success": true
}

الحذف حسب المعرف

لحذف القالب حسب المعرف، قم بتضمين معرف القالب مع الاسم في الطلب؛ لن يتم حذف إلا القالب بمعرف القالب المطابق.

بنية الطلب

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

مثال على الطلب

curl -X DELETE 'https://graph.facebook.com/v21.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

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

{
  "success": true
}

معرفة المزيد

الخطوات التالية

• بدء استخدام API السحابة لإرسال الرسائل