القائمة الثابتة

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

طريقة العمل تسمح لك القائمة الثابتة بإنشاء قائمة بالميزات الرئيسية للنشاط التجارية وإرسالها، مثل ساعات العمل ومواقع المتاجر والمنتجات وتظل مرئية في محادثة الشخص على Messenger مع النشاط التجاري. عندما ينقر الشخص على عنصر في القائمة، يتم إرسال إشعار webhook postback لتقديمه. يحتوي إشعار webhook على معلومات حول العنصر الذي تم تحديده والشخص الذي أجراه. يفتح إجراء تحديد العنصر هذا نافذة المراسلة. لديك 24 ساعة للرد على الشخص.

المتطلبات

لإظهار القائمة الثابتة، يجب استيفاء العناصر التالية:

• يجب أن يستخدم الشخص الإصدار 106 أو إصدارًا أحدث من Messenger على نظام iOS أو Android.
• يجب نشر صفحة فيسبوك التي يشترك فيها البرنامج التلقائي في Messenger.
• يجب تعيين البرنامج التلقائي في Messenger إلى الحالة "العامة" في إعدادات التطبيق.
• يجب أن يتوفر لدى البرنامج التلقائي في Messenger الإذن pages_messaging.
• يجب تعيين زر بدء الاستخدام في البرنامج التلقائي في Messenger.

الأزرار المدعومة

تتكون القائمة الثابتة من مصفوفة من الأزرار. ويتم دعم أنواع الأزرار التالية في القائمة الثابتة:

• web_url: يحدد العنصر على أنه زر عنوان URL.
• postback: يحدد العنصر على أنه زر رد جاهز.

تعيين القائمة الثابتة

لتعيين القائمة الثابتة، أرسل طلب POST إلى API الملف الشخصي على Messenger لتعيين الخاصية persistent_menu في الملف الشخصي لبرنامجك التلقائي في Messenger.

كبديل لقائمة المستوى المتداخل التي تم إيقاف استخدامها، نسمح باستخدام 20 زرًا كحد أقصى في المصفوفة call_to_actions لواجهة Graph API بالإصدار 8.0 والإصدارات الأحدث.

{
    "persistent_menu": [
        {
            "locale": "default",
            "composer_input_disabled": false,
            "call_to_actions": [
                {
                    "type": "postback",
                    "title": "Talk to an agent",
                    "payload": "CARE_HELP"
                },
                {
                    "type": "postback",
                    "title": "Outfit suggestions",
                    "payload": "CURATION"
                },
                {
                    "type": "web_url",
                    "title": "Shop now",
                    "url": "https://www.originalcoastclothing.com/",
                    "webview_height_ratio": "full"
                }
            ]
        }
    ]
}

القائمة الثابتة المتداخلة

تعطيل أداة الإنشاء

يمكنك تعطيل أداة الإنشاء لجعل القائمة الثابتة هي الطريقة الوحيدة أمام أي شخص للتفاعل مع البرنامج التلقائي في Messenger. ويُعد هذا الأمر مفيدًا إذا كان برنامجك التلقائي لديه غرض محدد للغاية أو مجموعة من الخيارات.

لإجراء ذلك، يمكنك تعيين "composer_input_disabled":true عند إنشاء القائمة الثابتة.

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

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

للقيام بذلك، حدد كائنًا منفصلاً في المصفوفة persistent_menu لكل إعداد محلي. لتحديد الإعداد المحلي لكل كائن، يمكنك تعيين الخاصية locale على إعداد محلي مدعوم:

{
  "locale":"default",
  "call_to_actions":[...]
},
{
  "locale: "zh_CN",
  "call_to_actions":[...]
}

القائمة على مستوى المستخدم

يمكنك تجاوز القائمة الثابتة على مستوى الصفحة باستخدام إعداد على مستوى المستخدم. ويتيح ذلك لتطبيقك التحكم الديناميكي في:

• النقر على أزرار الإجراء في القائمة المخصصة للمستخدم.
• إمكانية رؤية أداة الإنشاء بالنسبة للمستخدم.

لتمكين الإعداد على مستوى المستخدم أو تعطيله، يتم استخدام نقطة نهاية مختلفة تُسمى custom_user_settings. وتدعم نقطة النهاية هذه استدعاءات POST وGET وDELETE.

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

ملاحظة: يتم تحديث القائمة الثابتة على مستوى المستخدم في الوقت الفعلي، بينما قد يستغرق تحديث القائمة الثابتة على مستوى الصفحة ما يصل إلى 24 ساعة.

يتم تقييد معدلات استدعاء الإعدادات على مستوى المستخدم إلى 10 استدعاءات لكل مستخدم في كل 10 دقائق.

مثال على طلب POST

سيؤدي ذلك إلى تجاوز الإعدادات الحالية على مستوى الصفحة لهذا المستخدم.

curl -X POST -H "Content-Type: application/json" -d '{
  "psid": "<PSID>",
  "persistent_menu": [
        {
            "locale": "default",
            "composer_input_disabled": false,
            "call_to_actions": [
                {
                    "type": "postback",
                    "title": "Talk to an agent",
                    "payload": "CARE_HELP"
                },
                {
                    "type": "postback",
                    "title": "Outfit suggestions",
                    "payload": "CURATION"
                },
                {
                    "type": "web_url",
                    "title": "Shop now",
                    "url": "https://www.originalcoastclothing.com/",
                    "webview_height_ratio": "full"
                }
            ]
        }
    ]
}' "https://graph.facebook.com/v21.0/me/custom_user_settings?access_token=<PAGE_ACCESS_TOKEN>"

مثال على طلب GET

سيؤدي ذلك إلى استرداد الإعدادات الحالية على مستوى المستخدم والصفحة. وإذا لم تتوفر إعدادات على مستوى المستخدم، فسيتم إرجاع الإعدادات على مستوى الصفحة فقط.

curl -X GET "https://graph.facebook.com/v21.0/me/custom_user_settings?psid=<PSID>&access_token=<PAGE_ACCESS_TOKEN>"

النتيجة

{
    "data": [
      {
        "user_level_persistent_menu": [
            {
              "locale": "default",
              "composer_input_disabled": false,
              "call_to_actions": [
                  {
                      "type": "postback",
                      "title": "Talk to an agent",
                      "payload": "CARE_HELP"
                  },
                  {
                      "type": "postback",
                      "title": "Outfit suggestions",
                      "payload": "CURATION"
                  },
                  {
                      "type": "web_url",
                      "title": "Shop now",
                      "url": "https://www.originalcoastclothing.com/",
                      "webview_height_ratio": "full"
                  }
              ]
            }
        ],
        "page_level_persistent_menu": [
          Original Page Menu...
        ]  
      }
  ]
}

مثال على طلب DELETE

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

curl -X DELETE 'https://graph.facebook.com/v21.0/me/custom_user_settings?psid=<PSID>&params=[%22persistent_menu%22]&access_token=<PAGE_ACCESS_TOKEN>'

تعطيل القائمة الثابتة

قد تتوفر بعض الحالات التي يكون من الأفضل فيها تعطيل القائمة الثابتة لبرنامجك التلقائي في المكون الإضافي للدردشة. ولإجراء ذلك، أضف "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"] عند تعيين قائمتك الثابتة:

مثال على حمولة البيانات في API الملف الشخصي في Messenger

{
  "persistent_menu":[
    {
      "locale":"default",
      "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"],
      "composer_input_disabled": false,      
      "call_to_actions":[
        {
          "title":"My Account",
          "type":"postback",
          "payload":"PAYBILL_PAYLOAD"
        }
      ]
    }
  ]
}

أفضل الممارسات

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