The Persistent Menu

This documents shows you how to programmatically add the Persistent Menu to your Instagram messaging experience.

How It Works

The Persistent Menu allows you to create and send a menu of the main features of your business, such as hours of operation, store locations, and products, is always visible in a person's Messenger conversation with your business.

When a person clicks an item in the menu, a postback webhook notification is sent to your server, with information about what item was select and by whom, and the standard messaging window opens. You have 24 hours to respond to the person after the CTA.

Limitations

  • A menu is not updated in real time
    • Existing conversations will not see an updated menu unless a person refreshes their inbox; new conversations will see updated menus. Be sure your app can handle deprecated menu items.
  • The composer_input_disabled parameter is not available
  • The webview_height_ratio parameter is not available
  • You can not customize a menu based on the recipient's Page-scoped ID (PSID)

Requirements

For the persistent menu to appear, the following criteria must be satisfied:

Supported Buttons

The persistent menu is composed of an array of buttons. The following button types are supported in the persistent menu:

Setting the Persistent Menu

To set the persistent menu, send a POST request to the Messenger Profile API to set the persistent_menu property.

To view recent changes to the persistent menu within the Instagram app, go to the messages inbox and swipe down to refresh.

curl -X POST -H "Content-Type: application/json" -d 
'{
    "persistent_menu": [
        {
            "locale": "default",
            "call_to_actions": [
                {
                    "type": "postback",
                    "title": "Talk to an agent",
                    "payload": "CARE_HELP"
                },
                {access_token=<ACCESS_TOKEN>
                    "type": "postback",
                    "title": "Outfit suggestions",
                    "payload": "CURATION"
                },
                {
                    "type": "web_url",
                    "title": "Shop now",
                    "url": "https://www.originalcoastclothing.com/"
                 
                }
            ]
        }
    ]
}' "https://graph.facebook.com/v12.0/me/messenger_profile?platform=instagram&access_token=<ACCESS_TOKEN>"

Localization

You may provide default and localized button text for the persistent menu that will be displayed based on a person's locale.

To do this, specify separate objects in the persistent_menu array for each locale by setting the locale property to a supported locale:

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

Request Examples

GET

curl -X GET "https://graph.facebook.com/v12.0/me/messenger_profile?fields=persistent_menu&platform=instagram"

Result

{
    "data": [
      {
        "persistent_menu": [
            {
              "locale": "default",
              "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/"
                    
                  }
              ]
            }
        ]
      }
  ]
}

DELETE

curl -X DELETE "https://graph.facebook.com/v12.0/me/messenger_profile?fields=["persistent_menu"]&platform=instagram"

Best Practices

Just like with buttons, menu items can produce a webview or postback.

Use the menu as entry points for your Page's main features.

Be descriptive: your menu lets people know what your Page's features are. It instantly lets users know how they can interact with your Page.

Be selective: limit menu items to 5 for best user experience.

Don't expect the menu to contain user-specific data. The menu can be localized, but will not contain user-specific data.

Don't put a "Menu" button in the menu that sends the user a message containing a menu. Just put that content directly in the menu — that's what it's for!

Don't put generic actions like "Restart" in the menu.

Don't use prime menu real estate for secondary, "colophon" style info like about, terms of service, privacy policy, or powered by. These take focus away from accentuating the core features of your Page.

Developer Support