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

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

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

العناوين

العناوين هي مكونات اختيارية تظهر في أعلى رسائل القوالب. تدعم العناوين النصوص والوسائط (الصور ومقاطع الفيديو والمستندات) والمواقع.

تقتصر جميع القوالب على مكون عنوان واحد

العناوين النصية

يمكنك اختيار إضافة نص العنوان إلى قالب الرسالة لديك. يقبل نص الرسالة في مكون العنوان المعلمات الخاصة بالتكوين البرمجي.

يمكن تكوين معلمات النص بأحد التنسيقين:

• موضعي - يمكنك إدخال مصفوفة من المعلمات التي تتوافق مع المواضع الرقمية في النص الأساسي مع أمثلة

  • على سبيل المثال: “Hello John, your account balance is {{1}}” | [ “$1,000” ]
• مسمّى - يمكنك إدخال كائنات JSON التي تحتوي على اسم معلمة وأمثلة

  • على سبيل المثال: { "param_name": "account_balance", "example": "$1,000" }

بنية المكون

أضف كائن مكون العنوان هذا إلى مصفوفة كائن ”components”[] عند استدعاء نقطة النهاية POST /message_templates. استبدل خصائص العنصر النائب أدناه باستخدام جدول الخصائص.

تعرف على المزيد حول إرسال القوالب النصية هنا

{ "type": "HEADER", "format": "TEXT", "text": "", "example": { "header_text": [ // You must provide one of the inputs below when the  string contains parameters   ] } } 

الخصائص

[{
 "param_name": "sale_start_date",
 "example": "December 1st"
}]
          

مثال على المعلمة الموضعية

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our new sale starts {{1}}!",
  "example": {
    "header_text": [
      "December 1st"
    ]
  }
}

مثال على المعلمة المسماة

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our new sale starts {{sale_start_date}}!",
  "example": {
    "header_text_named_params": [
      {
        "param_name": "sale_start_date",
        "example": "December 1st"
      }
    ]
  }
}

عناوين الوسائط

يمكن أن تكون عناوين الوسائط عبارة عن صورة أو فيديو أو مستندًا مثل PDF. يجب تحميل جميع الوسائط باستخدام API التحميل القابل للاستئناف. البنية المُستخدمة لتعريف عنوان وسائط هي نفسها المستخدمة مع جميع أنواع الوسائط.

البنية

{
  "type": "HEADER",
  "format": "",
  "example": {
    "header_handle": [
      ""
    ]
  }
}

الخصائص

المثال

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": [
      "4::aW..."
    ]
  }
}

عناوين المواقع

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

يمكن استخدام عناوين المواقع فقط في القوالب المصنفة كـ UTILITY أو MARKETING. المواقع الفورية غير مدعومة.

البنية

{
  "type": "HEADER",
  "format": "LOCATION"
}

الخصائص

لا يمكن تخصيص قيم الخاصية.

المثال

{
  "type": "HEADER",
  "format": "LOCATION"
}

النص

يمثل مكون النص، النص الأساسي لقالب الرسالة وهو عبارة عن مكون قالب نصي فقط. مطلوب لكل القوالب.

يقبل نص الرسالة في مكون النص الأساسي المعلمات الخاصة بالتكوين البرمجي.

يمكن تكوين معلمات النص بأحد التنسيقين:

• موضعي - يمكنك إدخال مصفوفة من المعلمات الموضعية الرقمية التي تتوافق مع المواضع الرقمية في النص الأساسي مع أمثلة

  • على سبيل المثال: “Hello {{1}}, your account balance is {{2}}” | [ “John”, “$1,000” ]
• مسمّى - يمكنك إدخال كائنات JSON التي تحتوي على اسم معلمة وأمثلة

  • على سبيل المثال: { "param_name": "order_id", "example": "335628"}

تقتصر جميع القوالب على مكون نص أساسي واحد.

بنية المكون

أضف كائن مكون النص الأساسي هذا إلى مصفوفة كائن ”components”[] عند استدعاء نقطة النهاية POST /message_templates. استبدل خصائص العنصر النائب أدناه باستخدام جدول الخصائص.

تعرف على المزيد حول إرسال القوالب النصية هنا

{ "type": "body", "text": "", "example": { "body_text": [ [ // You must provide one of the inputs below when the  string contains parameters   ] ] } } 

الخصائص

[{
 "param_name": "order_id",
 "example": "335628"
},
{
 "param_name": "customer_name",
 "example": "Shiva"
}]
          

مثال على المعلمة الموضعية

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
  "example": {
    "header_text": [
      "the end of August","25OFF","25%"
    ]
  }
}

مثال على المعلمة المسماة

{
  "type": "BODY",
  "text": "Your {{order_id}}, is ready {{customer_name}}.",
  "example": {
    "header_text_named_params": [
      {
        "param_name": "order_id",
        "example": "335628"
      },
      {
        "param_name": "customer_name",
        "example": "Shiva"
      }
    ]
  }
}

التذييل

التذييلات هي مكونات اختيارية نصية فقط تظهر بعد مكون النص الرئيسي مباشرةً. تقتصر القوالب على مكون تذييل واحد.

البنية

{
  "type": "FOOTER",
  "text": ""
}

الخصائص

المثال

{
  "type": "FOOTER",
  "text": "Use the buttons below to manage your marketing subscriptions"
}

الأزرار

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

يتم تعريف الأزرار ضمن كائن مكون أزرار واحد، وتتواجد ضمن مصفوفة buttons واحدة. على سبيل المثال، يستخدم هذا القالب زر رقم هاتف وزر عنوان URL:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "PHONE_NUMBER",
      "text": "Call",
      "phone_number": "15550051310"
    },
    {
      "type": "URL",
      "text": "Shop Now",
      "url": "https://www.luckyshrub.com/shop/"
    }
  ]
}

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

أزرار نسخ الرمز

تقوم أزرار نسخ الرمز بنسخ سلسلة نصية (يتم تحديدها عند إرسال القالب في رسالة قالب) إلى حافظة الجهاز عند الضغط عليها بواسطة مستخدم التطبيق. يجب ألا يزيد عدد أزرار نسخ الرمز في القالب عن زر واحد.

البنية

{
  "type": "COPY_CODE",
  "example": ""
}

الخصائص

المثال

{
  "type": "COPY_CODE",
  "example": "250FF"
}

أزرار الدفق

أزرار الدفق مخصصة لإرسال رسائل الدفق كقوالب.

يمكن إنشاء التدفقات بسرعة في المساحة التجريبية وإرفاقها كقيمة بلغة JSON أو يمكن تحديد معرف دفق موجود.

البنية

{
  "type": "FLOW",
  "text": "",
  "flow_id": "",
  "flow_name": "",
  "flow_json": "", 
  "flow_action": "",
  "navigate_screen": "",
  "icon": ""
}

الخصائص

المثال

{
  "type": "FLOW",
  "text": "Sign up",
  "icon": "PROMOTION",
  "flow_json" : {
    "version": "6.0",
    "screens": [
        {
            "id": "WELCOME_SCREEN",
            "layout": {
                "type": "SingleColumnLayout",
                "children": [
                    {
                        "type": "TextHeading",
                        "text": "Hello World"
                    },
                    {
                        "type": "TextBody",
                        "text": "Let's start building things!"
                    },
                    {
                        "type": "Footer",
                        "label": "Complete",
                        "on-click-action": {
                            "name": "complete",
                            "payload": {}
                        }
                    }
                ]
            },
            "title": "Welcome",
            "terminal": true,
            "success": true,
            "data": {}
        }
    ]
  }
}

أزرار الرسائل متعددة المنتجات

أزرار الرسائل متعددة المنتجات (MPM) هي أزرار خاصة غير قابلة للتخصيص، وعند الضغط عليها، تعرض ما يصل إلى 30 منتجًا من كتالوج التجارة الإلكترونية لديك، حيث تكون المنتجات منظمة فيما يصل إلى 10 أقسام، ضمن رسالة واحدة. راجع قوالب رسائل المنتجات المتعددة.

أزرار كلمة المرور لمرة واحدة

أزرار كلمة المرور لمرة واحدة (OTP) هي نوع خاص من مكون زر URL المستخدم مع قوالب المصادقة. راجع قوالب المصادقة.

أزرار رقم الهاتف

تتصل أرقام أزرار الهاتف برقم هاتف النشاط التجاري المحدد عندما يضغط عليها مستخدم التطبيق. يجب ألا يزيد عدد أزرار رقم الهاتف عن زر واحد.

البنية

{
  "type": "PHONE_NUMBER",
  "text": "",
  "phone_number": ""
}

الخصائص

المثال

{
  "type": "PHONE_NUMBER",
  "text": "Call",
  "phone_number": "15550051310"
}

أزرار الرد السريع

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

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

أمثلة على المجموعات الصالحة:

• رد سريع، رد سريع
• رد سريع، رد سريع، عنوان URL، هاتف
• عنوان URL، هاتف، رد سريع، رد سريع

أمثلة على المجموعات غير الصالحة:

• رد سريع، عنوان URL، رد سريع
• عنوان URL، رد سريع، عنوان URL

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

البنية

{
  "type": "QUICK_REPLY",
  "text": ""
}

الخصائص

المثال

{
  "type": "QUICK_REPLY",
  "text": "Unsubscribe from Promos"
}

أزرار رسائل المنتج الواحد

أزرار رسائل المنتج الواحد (SPM) هي عبارة عن أزرار خاصة غير قابلة للتخصيص يمكن تعيينها لمنتج محدد في كتالوج المنتجات لديك. عندما يتم الضغط عليها، تقوم بتحميل تفاصيل المنتج، الذي يتم سحبه من الكتالوج لديك. يمكن للمستخدمين بعد ذلك إضافة المنتج إلى عربة التسوق وتقديم طلب. راجع قوالب رسائل المنتج الواحد وقوالب العنصر الدوّار لبطاقة المنتج.

أزرار عنوان URL

تقوم أزرار عنوان URL بتحميل عنوان URL المحدد في متصفح الويب الافتراضي للجهاز عندما يضغط عليها مستخدم التطبيق. تقتصر القوالب على زرين لعنوان URL.

البنية

{
  "type": "URL",
  "text": "",
  "url": "",

  # Required if  contains a variable
  "example": [
    ""
  ]
}

الخصائص

المثال

{
  "type": "URL",
  "text": "Shop Now",
  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
  "example": [
    "summer2023"
  ]
}

عرض لفترة محدودة

مكونات العرض لفترة محدودة هي مكونات خاصة تستخدم لإنشاء قوالب العرض المتوفرة لفترة محدودة.

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

الترويج الموسمي

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

• عنوان نص يتضمن متغيرة وعينة من القيمة
• نص رئيسي يتضمن متغيرات وعينة من القيم
• تذييل نصي
• زرا الرد السريع

curl -L 'https://graph.facebook.com/v23.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"
        }
      ]
    }
  ]
}'

تأكيد الطلب

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

• عنوان مستند بقيمة عينة
• نص رئيسي يتضمن متغيرات وعينة من القيم
• زر رقم هاتف
• زر عنوان URL

curl -L 'https://graph.facebook.com/v16.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "4::YX..."
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Thank you for your order, {{1}}! Your order number is {{2}}. Tap the PDF linked above to view your receipt. 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"
        }
      ]
    }
  ]
}'

تحديث تسليم الطلبات

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

• عنوان موقع
• نص رئيسي يتضمن متغيرات وعينة من القيم
• تذييل
• زر رد سريع

curl 'https://graph.facebook.com/v23.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "order_delivery_update",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "LOCATION"
    },
    {
      "type": "BODY",
      "text": "Good news {{1}}! Your order #{{2}} is on its way to the location above. Thank you for your order!",
      "example": {
        "body_text": [
          [
            "Mark",
            "566701"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "To stop receiving delivery updates, tap the button below."
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Stop Delivery Updates"
        }
      ]
    }
  ]
}'

حدث Webhook تحديث المكون

اشترك في حقل حدث webhook بشأن message_template_components_update لاستلام إشعار بالتغييرات التي تطرأ على مكونات القالب، مثل تغيير العنوان أو النص أو إضافة زر.

شكل استجابة Webhook

"message_template_id": ,
"message_template_name": ,
"message_template_language": ,
"message_template_title": ,
"message_template_element": ,
"message_template_footer": ,
"message_template_buttons": [
  {
    "message_template_button_type": ,
    "message_template_button_text": ,
    "message_template_button_url": ,
    "message_template_button_phone_number": 
  }
]

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

"message_template_id": 1234567890,
"message_template_name": “promo_summer_sale_11_en”,
"message_template_language": “en_US”,
"message_template_title": “header”,
"message_template_element": “body”,
"message_template_footer": “footer”,
"message_template_buttons": [
  {
    "message_template_button_type": URL,
    "message_template_button_text": “click me”,
    "message_template_button_url": “https://www.example.com”,
    "message_template_button_phone_number": “+1(123)4565678”
  }
]

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