persistent_menu Reference

New feature

On December 04, 2019 we made improvements to the persistent menu to support dynamic changes at the user level to further personalize the conversational experience. See User level menu

During F8 2019, we announced our plans to launch a lighter, better and simpler Messenger designed to build closer connections between people and businesses.

As of August 15, 2019, updated versions of the Messenger app for iOS will no longer support nested persistent menus. For Messenger on iOS we are transitioning from nested persistent menus to single-layer persistent menus. Pages that contain nested menu items will be rendered as flat lists. We believe this will create an even better experience for people on Messenger. for iOS. Refer to our June 10, 2019 Announcement.

The persistent menu can be set for your bot to help people discover and more easily access your functionality throughout the conversation.

The Persistent Menu is always available to the user. This menu should contain top-level actions that users can enact at any point. Having a persistent menu easily communicates the basic capabilities of your bot for first-time and returning users. The menu will automatically appear in a thread if the person has been away for a certain period of time and returns. This settings are part of the Messenger Profile API Reference

The persistent manu can also be set and changed at the user level. For more information on it see user level menu.



To use the persistent menu, you must do the following:

  • Set a get started button.
  • Have the 'Administrator' role for the page associated with the bot.

persistent_menu Format

Persistent Menu Example

    "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": "",
                    "webview_height_ratio": "full"


Property Type Description



An array of objects that define the persistent menu for different locales. The menu with a locale property that matches the person's locale will be displayed.

At least one object in the persistent_menu array must specify "locale": "default". This is the menu we will fall back to if no object has a locale property that matches the users locale.

See the list of supported locales.



Disables the Messenger composer field if set to true. This means your bot can only be interacted with via the persistent menu, postbacks, buttons, and webviews.

Defaults to false.



Array of interface names to disable the persistent menu in. Currently only customer_chat_plugin is supported.



An array of top-level menu items for the persistent menu. A maximum of 3 items is allowed.

Required if "composer_input_disabled": true.

Property Type Description



The type of menu item. Supported values are:



Title to display on the menu item. 30 character limit.



URL to open when the button is tapped. Required if type is web_url.



Data that will be sent back to your webhook as a messaging_postbacks event. Required if type is postback. 1000 character limit.



Optional. Height of the webview. Valid values include compact, tall, full.



Optional. Must be true if the item type is web_url and the Messenger Extensions SDK will be used in the webview.



Optional. URL to open in the webview for clients that do not support the Messenger Extensions SDK. If this is not defined, the url will be used as the fallback. It may only be specified if "messenger_extensions": true.



Optional. Set to hide to disable sharing in the webview (for sensitive info).

Rate Limit

Calls to the Messenger Profile API are limited to 10 API calls per 10 minute interval. This rate limit is enforced per Page.

Note that calls to the user level menu are limited to 10 API calls per user per 10 minute interval. This rate limit is enforced per Page.