固定菜单

此文档介绍如何以编程方式，在您的消息体验中添加固定菜单。

运作方式 通过固定菜单，您可以创建和发送包含商家主要特点（例如营业时间、店铺位置以及产品）的菜单，而且该菜单将始终显示在用户与您商家的 Messenger 对话中。 当用户点击菜单项时，系统会向您的服务器发送 postback Webhooks 通知。Webhooks 通知包含所选菜单项和该用户的信息。此菜单项选择操作会开启标准消息时间范围。您有 24 小时时间回复该用户。

要求

如要显示固定菜单，必须满足以下条件：

• 用户在 iOS 或 Android 上运行的必须是 Messenger v106 或更高版本。
• Messenger 智能助手所订阅的 Facebook 公共主页必须已发布。
• 必须在应用设置中将 Messenger 智能助手设置为“公开”。
• Messenger 智能助手必须获得 pages_messaging 权限。
• 必须为 Messenger 智能助手设置“开始”按钮。

支持的按钮

固定菜单由一组按钮组成。固定菜单支持以下类型的按钮：

• web_url：指定菜单项是网址按钮。
• postback：指定菜单项是回传按钮。

设置固定菜单

如要设置固定菜单，请发送 POST 请求到 Messenger 个人主页 API，以设置智能助手 Messenger 个人主页的 persistent_menu 属性。

为替代已停用的嵌套层级菜单，对于图谱 API v8.0 及更高的版本，我们支持在 call_to_actions 数组中最多设置 20 个按钮。

{
    "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/v19.0/me/custom_user_settings?access_token=<PAGE_ACCESS_TOKEN>"

GET 请求示例

此请求将检索当前的用户层级和公共主页层级设置。如果没有用户层级的设置，系统只会返回公共主页层级的设置。

curl -X GET "https://graph.facebook.com/v19.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/v19.0/me/custom_user_settings?psid=<PSID>&params=[%22persistent_menu%22]&access_token=<PAGE_ACCESS_TOKEN>'

禁用固定菜单

有时您可能需要在聊天插件中禁用智能助手的固定菜单。如要执行此操作，您需在设置固定菜单时添加 "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"]：

Messenger 个人主页 API 负载示例

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

最佳实践

和按钮一样，菜单项可生成网页视图或回传。请注意，固定菜单不支持二级菜单。