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.

Starting August 15, 2019, updated versions of the Messenger app will no longer support Nested menu. To create a more seamless experience for people on Messenger, we are transitioning from nested persistent menu to a single layer menu format, For Pages set with nested menu items they will render as a flat list. We believe this will create an even better experience for people on Messenger. Refer to 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.

Contents

Requirements

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": "https://www.originalcoastclothing.com/",
                    "webview_height_ratio": "full"
                }
            ]
        }
    ]
}

Properties

Property Type Description

locale

String

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.

composer_input_disabled

Boolean

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.

disabled_surfaces

Array

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

call_to_actions

Array<menu_item>

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

type

String

The type of menu item. Supported values are:

title

String

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

url

String

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

payload

String

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

webview_height_ratio

String

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

messenger_extensions

Boolean

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

fallback_url

String

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.

webview_share_button

String

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.