persistent_menu Reference

Messenger Profile API

persistent_menu is a property of the Messenger Profile API. For information on retrieving, setting, updating, and deleting persistent_menu, see the Messenger Profile API Reference.

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.

Contents

Requirements

You 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":[
    {
      "locale":"default",
      "composer_input_disabled": true,
      "call_to_actions":[
        {
          "title":"My Account",
          "type":"nested",
          "call_to_actions":[
            {
              "title":"Pay Bill",
              "type":"postback",
              "payload":"PAYBILL_PAYLOAD"
            },
            {
              "title":"History",
              "type":"postback",
              "payload":"HISTORY_PAYLOAD"
            },
            {
              "title":"Contact Info",
              "type":"postback",
              "payload":"CONTACT_INFO_PAYLOAD"
            }
          ]
        },
        {
          "type":"web_url",
          "title":"Latest News",
          "url":"http://petershats.parseapp.com/hat-news",
          "webview_height_ratio":"full"
        }
      ]
    },
    {
      "locale":"zh_CN",
      "composer_input_disabled":false,
      "call_to_actions":[
        {
          "title":"Pay Bill",
          "type":"postback",
          "payload":"PAYBILL_PAYLOAD"
        }
      ]    
    }
  ]
}

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.

call_to_actions

Array<menu_item>

An array of top-level menu items for the persistent menu. A maximum of 3 items is allowed. A maximum of two nested menus are supported.


Required if "composer_input_disabled": true.

Property Type Description

type

String

The type of menu item. Supported values are:

  • web_url: Specifes the item is a URL button.
  • postback: Specifies the item is a postback button.
  • nested: Specifies the item opens a nested menu.

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.

call_to_actions

Array<menu_item>

Nested menu_item that will be expanded in next level. A maximum of 5 items is allowed. Required if type is nested. A persistent menu may have a maximum of two nested menus.

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).