Das beständige Menü

In diesem Dokument erfährst du, wie du das beständige Menü programmgesteuert zu deinem Messaging-Erlebnis hinzufügst.

So funktioniert’s Mit dem beständigen Menü kannst du ein Menü mit den Hauptfunktionen für dein Unternehmen erstellen und senden. Das können z. B. die Geschäftszeiten, die Speicherorte und Produkte sein. Das Menü wird dann dauerhaft in der Messenger-Unterhaltung einer Person mit deinem Unternehmen angezeigt. Wenn eine Person auf ein Element im Menü klickt, wird an deinen Server eine postback-Webhook-Benachrichtigung gesendet. Die Webhook-Benachrichtigung beinhaltet Informationen dazu, welches Element ausgewählt wurde und von wem es aus ausgewählt wurde. Diese Element-Auswahlaktion öffnet das Standard-Nachrichtenfenster. Du hast 24 Stunden Zeit, dieser Person zu antworten.

Anforderungen

Folgendes muss zutreffen, damit das beständige Menü erscheint:

• Der*die Nutzer*in muss Messenger v106 oder höher auf iOS oder Android verwenden.
• Die Facebook-Seite, die der Messenger-Bot abonniert, muss veröffentlicht sein.
• Der Messenger-Bot muss in den App-Einstellungen auf „Öffentlich“ gesetzt sein.
• Der Messenger-Bot muss die pages_messaging-Berechtigung aufweisen.
• Der „Los geht‘s“-Button muss für den Messenger-Bot festgelegt sein.

Unterstützte Buttons

Das beständige Menü besteht aus einem Array von Buttons. Die folgenden Button-Arten werden im beständigen Menü unterstützt:

• web_url: Gibt an, ob das Element ein URL-Button ist.
• postback: Gibt an, ob das Element ein Postback-Button ist.

Einrichten des beständigen Menüs

Um das beständige Menü einzurichten, sende eine POST-Anfrage an die Messenger Profile API, um die persistent_menu-Eigenschaft des Messenger-Profils deines Bots festzulegen.

Um die veralteten verschachtelten Menüebenen zu ersetzen, lassen wir bis zu 20 Buttons im call_to_actions-Array für Graph API Version 8.0 und höher zu.

{
    "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"
                }
            ]
        }
    ]
}

Verschachteltes beständiges Menü

Deaktivieren des Eingabefeldes

Du kannst das Eingabefeld deaktivieren, damit das beständige Menü die einzige Möglichkeit zur Interaktion mit deinem Messenger-Bot ist. Das bietet sich vor allem dann an, wenn dein Bot einen ganz bestimmten Zweck oder bestimmte Optionen hat.

Lege dazu "composer_input_disabled":true beim Erstellen des beständigen Menüs fest.

Lokalisierung

Du kannst standardmäßigen und lokalisierten Button-Text für das beständige Menü angeben, der je nach der Ländereinstellung einer Person angezeigt wird.

Gib dazu ein separates Objekt im persistent_menu-Array für jede Sprache an. Um die Sprache für jedes Objekt anzugeben, setze die locale-Eigenschaft auf eine unterstützte Sprache:

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

Menü auf Nutzerebene

Du kannst das beständige Menü auf Seitenebene mit einer Einstellung auf Nutzerebene außer Kraft setzen. Dann kann deine App die folgenden Elemente dynamisch steuern:

• Die Click-to-Action-Buttons im Menü für Nutzer*innen.
• Die Sichtbarkeit des Eingabefelds für Nutzer*innen.

Zum Aktivieren oder Deaktivieren der Einstellung auf Nutzerebene wird ein eigener Endpunkt namens custom_user_settings verwendet. Dieser Endpunkt unterstützt POST-, GET- und DELETE-Aufrufe.

Dieselben Konfigurationen, die für das beständige Menü auf Seitenebene verfügbar sind, gelten auch auf Nutzerebene. Der Hauptunterschied besteht darin, dass du mit einem psid-Parameter den*die Nutzer*in angeben musst, für welche*n diese Spezialeinstellung gilt.

HINWEIS: Die Aktualisierung des beständigen Menüs auf Nutzerebene erfolgt in Echtzeit. Die Aktualisierung des beständigen Menüs auf Seitenebene kann jedoch bis zu 24 Stunden dauern.

Für Einstellungen auf Nutzerebene gilt eine Ratenbegrenzung von 10 Aufrufen pro Nutzer*in pro 10 Minuten.

Beispiel für POST-Anfrage

Damit setzt du die aktuellen Einstellungen auf Seitenebene für diese*n Nutzer*in außer Kraft.

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

Beispiel für GET-Anfrage

Damit rufst du die aktuellen Einstellungen auf Nutzer- und Seitenebene ab. Wenn es keine Einstellungen auf Nutzerebene gibt, werden nur diejenigen der Seitenebene zurückgegeben.

curl -X GET "https://graph.facebook.com/v21.0/me/custom_user_settings?psid=<PSID>&access_token=<PAGE_ACCESS_TOKEN>"

Ergebnis

{
    "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...
        ]  
      }
  ]
}

Beispiel für DELETE-Anfrage

Damit entfernst du die Einstellungen auf Nutzerebene, während das Menü auf Seitenebene, falls vorhanden, bestehen bleibt.

curl -X DELETE 'https://graph.facebook.com/v21.0/me/custom_user_settings?psid=<PSID>&params=[%22persistent_menu%22]&access_token=<PAGE_ACCESS_TOKEN>'

Deaktivieren des beständigen Menüs

In manchen Fällen ist es von Vorteil, das beständige Menü für deinen Bot im Chat-Plugin zu deaktivieren. Füge dazu beim Einrichten deines beständigen Menüs "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"] hinzu:

Beispiel für Messenger Profile API-Payload

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

Best Practices

Menüelemente können genauso wie Buttons zu einer Webansicht oder einem Postback führen. Beachte, dass keine untergeordneten Menüs unterstützt werden.