Olete Facebook Messengeris käivitanud boti, see vastab sõnumitele, kuid midagi on puudu. Kasutaja avab vestluse ja näeb tühja akent. Pole menüüd, vihjeid ega „Alusta" nuppu. Esimene puudutus ja vaikus. Inimesed lihtsalt ei saa aru, mida teie bot teha suudab.

Kolm komponenti muudavad näotu boti arusaadavaks liideseks: püsiv menüü kiirtegevustega, „Alusta" nupp esmakontaktiks ja tervitustekst, mis tervitab kasutajat nimepidi. Varem seadistati seda kõike aegunud thread_settings parameetri kaudu. Nüüd on Meta viinud juhtimise üle ühtsele Messenger Profile API-le ja vanad cURL päringud 2017. aasta õpetustest lihtsalt ei tööta.

Selles juhendis käsitleme praegust lähenemist püsiva menüü, „Alusta" nupu ja tervituse seadistamiseks Messenger Profile API kaudu. Koos töötavate cURL näidete ja PHP POSTBACK töötlejaga, mis eristab menüüelementide klikke.

💡 Kiirülevaade:

• Seadista püsiv menüü persistent_menu kaudu Messenger Profile API-s: kuni 20 elementi, lokaliseerimine, sisestusvälja keelamine
• Lisa „Alusta" nupp get_started parameetri kaudu: esimesel puudutusel tagastab Facebook kasutaja PSID
• Seadista tervitustekst greeting kaudu: {{user_first_name}} mallid töötavad endiselt 2026. aastal
• Kirjuta PHP POSTBACK töötleja: payload alusel tuvastab, millist menüüelementi kasutaja klõpsas
• Arvesta piirangutega: 10 Profile API päringut 10 minuti jooksul lehe kohta, menüü vahemälu uueneb kuni 24 tundi

Mis muutus: Thread Settings → Messenger Profile API

Enne 2020. aastat seadistati menüüd, „Alusta" nuppu ja tervitust eraldi POST päringutega /me/thread_settings lõpp-punkti. Seadistuse tüüp määrati päringu kehas setting_type kaudu: call_to_actions menüü jaoks, greeting tervituse jaoks. 2026. aastal see lähenemine ei tööta, lõpp-punkt on dokumentatsioonist eemaldatud.

Nüüd määratakse kõik boti omadused Messenger Profile API kaudu, ühtse lõpp-punkti kaudu:

1
POST https://graph.facebook.com/v22.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN

Päringu keha on JSON objekt vajalike omadustega: persistent_menu menüü jaoks, get_started „Alusta" nupu jaoks, greeting tervituse jaoks, ice_breakers ja whitelisted_domains. Neid saab edastada koos või eraldi. Profiil kirjutatakse üle, ära edasta omadust, kui sa ei soovi seda muuta.

Ametlik dokumentatsioon: Persistent Menu on Meta for Developers. API versioon uueneb iga kuue kuu tagant, kontrolli kehtivat versiooni muudatuste logist.

Menüü toimimise nõuded, kehtivad 2026. aasta juuni seisuga:

• Facebooki leht on avaldatud, bot on rakenduse seadetes lülitatud „avalikku" režiimi
• Rakendusel on pages_messaging õigus
• Kasutaja kasutab Messengeri versiooni 106 või uuemat
• „Alusta" nupp on seadistatud (ilma selleta menüüd ei kuvata)
• Sul on lehe administraatori roll

1. Püsiv menüü (persistent_menu)

Menüü asub sisestusväljast vasakul, kasutaja klõpsab „hamburgeri" ikoonil ja näeb tegevuste loendit. See on ülataseme navigatsioon: „Abi", „Kataloog", „Tugi". Kuni 20 elementi, kuid Meta soovitab parema kasutuskogemuse huvides piirduda viiega.

Iga element on objekt, millel on type (postback või web_url), title (kuni 30 tähemärki) ja kas payload või url. Emotikonid pealkirjades töötavad, kopeeri need saidilt getemoji.com.

Menüü seadistamine. Saada POST päring Messenger Profile API-le:

1
curl -X POST -H "Content-Type: application/json" -d '{
2
  "persistent_menu": [
3
    {
4
      "locale": "default",
5
      "composer_input_disabled": false,
6
      "call_to_actions": [
7
        {
8
          "type": "postback",
9
          "title": "🆘 Help",
10
          "payload": "HELP_PAYLOAD"
11
        },
12
        {
13
          "type": "postback",
14
          "title": "📰 News",
15
          "payload": "LATEST_POSTS_PAYLOAD"
16
        },
17
        {
18
          "type": "web_url",
19
          "title": "🌐 Website",
20
          "url": "https://yoursite.com/",
21
          "webview_height_ratio": "full"
22
        }
23
      ]
24
    }
25
  ]
26
}' "https://graph.facebook.com/v22.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

Edukas vastus: {"result": "success"}. Menüü ei ilmu kohe, kliendipoolne vahemälu uueneb kuni 24 tundi. Testimisel kustuta vestlus ja alusta uuesti, et muudatusi kohe näha.

Menüü eemaldamine. DELETE päring koos fields parameetriga:

1
curl -X DELETE "https://graph.facebook.com/v22.0/me/messenger_profile?fields=persistent_menu&access_token=PAGE_ACCESS_TOKEN"

Sisestusvälja keelamine. Kui bot töötab ainult menüü ja nuppude kaudu, määra "composer_input_disabled": true. Sisestusväli kaob, kasutaja suhtleb eranditult menüüelementide ja postback-nuppude kaudu. Kasulik KKK-bottide ja kataloogide puhul.

Lokaliseerimine. Lisa objektid locale võtmega iga keele jaoks. Objekt väärtusega "locale": "default" on kohustuslik, see toimib varuvariandina:

1
{
2
  "persistent_menu": [
3
    {
4
      "locale": "default",
5
      "call_to_actions": [...]
6
    },
7
    {
8
      "locale": "ru_RU",
9
      "call_to_actions": [...]
10
    }
11
  ]
12
}

Kohandatud menüü. /me/custom_user_settings lõpp-punkti kaudu saad menüü konkreetse kasutaja jaoks PSID alusel üle kirjutada. Piirang: 10 päringut kasutaja kohta 10 minuti jooksul. Pärast kohandatud menüü eemaldamist taastatakse lehe menüü.

2. POSTBACK käsitlemine PHP-s

Kui kasutaja klõpsab menüüelemendil, millel on type: "postback", saadab Facebook sinu veebihaagile messaging_postbacks sündmuse. Päringu kehas on postback objekt koos payload väljaga, mille määrasid menüüd seadistades.

PHP töötleja loeb sissetuleva JSON-i php://input kaudu, eraldab payload ja määrab switch abil, milline toiming käivitada. Allpool on praegune kood aastaks 2026 koos v22.0 lõpp-punktiga:

1
<?php
2
// Read incoming request from Facebook
3
$input = json_decode(file_get_contents('php://input'), true);
4
 
5
// Extract recipient and sender data
6
$page_id = $input['entry'][0]['id'];
7
$sender = $input['entry'][0]['messaging'][0]['sender']['id'];
8
 
9
// Determine whether message or postback
10
$message = $input['entry'][0]['messaging'][0]['message']['text'] ?? '';
11
$postback = $input['entry'][0]['messaging'][0]['postback']['payload'] ?? '';
12
 
13
if ($message || $postback) {
14
 
15
    if ($message) {
16
        $reply = 'Message received: ' . $message;
17
    } else {
18
        switch ($postback) {
19
            case 'HELP_PAYLOAD':
20
                $reply = 'You clicked the "Help" button. How can I help?';
21
                break;
22
 
23
            case 'LATEST_POSTS_PAYLOAD':
24
                $reply = 'Here are fresh posts from this week.';
25
                break;
26
 
27
            default:
28
                $reply = 'Action not recognized. Try again.';
29
        }
30
    }
31
 
32
    // Form response
33
    $responseJSON = json_encode([
34
        'recipient' => ['id' => $sender],
35
        'message' => ['text' => $reply],
36
    ]);
37
 
38
    $access_token = 'YOUR_PAGE_ACCESS_TOKEN';
39
    $url = 'https://graph.facebook.com/v22.0/me/messages?access_token=' . $access_token;
40
 
41
    // Send via cURL
42
    $ch = curl_init($url);
43
    curl_setopt($ch, CURLOPT_POST, 1);
44
    curl_setopt($ch, CURLOPT_POSTFIELDS, $responseJSON);
45
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
46
    $result = curl_exec($ch);
47
    curl_close($ch);
48
}

Mis muutus. API versioon URL-is tõsteti v2.7 pealt v22.0 peale. Käsitsi JSON-sõne kokkupanemise asemel kasutatakse json_encode(), väiksem võimalus pääsumärgendamisega eksida. Lisatud on default plokk switch-is tundmatu payloadi jaoks. ?? (null-ühildamise) konstruktsioon on puhtam kui vana isset() koos kolmikoperaatoritega.

Kuhu paigutada. Kood läheb faili, millele Facebooki rakenduse veebihaagi URL osutab. Tavaliselt on see webhook.php saidi juurkataloogis. Veendu, et sama URL-i GET meetod käsitleb veebihaagi verifitseerimist hub_challenge kaudu.

Oluline. Hoia pääsutõendit keskkonnamuutujates või seadistuses, mitte koodis. Kohaliku arenduse jaoks kasuta .env faili, kus on PAGE_ACCESS_TOKEN=....

3. Alusta nupp (get_started)

Nupp ilmub tervitusekraanile lehega esmakontaktis. Pärast klõpsu saadab Facebook messaging_postbacks sündmuse sinu määratud payloadiga. Vastuseks saad kasutajat nimepidi tervitada või kuvada nuppudega menüüd.

Ilma seadistatud „Alusta" nuputa püsivat menüüd ei kuvata, see on platvormi kohustuslik nõue.

Seadistamine:

1
curl -X POST -H "Content-Type: application/json" -d '{
2
  "get_started": {
3
    "payload": "GET_STARTED_PAYLOAD"
4
  }
5
}' "https://graph.facebook.com/v22.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

Payload on suvaline kuni 1000 märgi pikkune sõne. PHP töötlejas lisa switch-i case 'GET_STARTED_PAYLOAD' ja tagasta isikustatud tervitus.

Eemaldamine:

1
curl -X DELETE "https://graph.facebook.com/v22.0/me/messenger_profile?fields=get_started&access_token=PAGE_ACCESS_TOKEN"

4. Tervitustekst (greeting)

Tervitusteksti näidatakse tühjas vestluses enne esimest sõnumit. Toetab malle {{user_first_name}} {{user_last_name}} ja {{user_full_name}}. Nimepidi isikustamine suurendab kaasatust, kasutaja näeb, et bott pöördub just tema poole.

Seadistamine:

1
curl -X POST -H "Content-Type: application/json" -d '{
2
  "greeting": [
3
    {
4
      "locale": "default",
5
      "text": "Hi, {{user_first_name}}! I am a helper bot. Ask a question or open the menu on the left."
6
    }
7
  ]
8
}' "https://graph.facebook.com/v22.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

Tervitustekst toetab ka lokaliseerimist, lisa objektid locale võtmega.

Eemaldamine:

1
curl -X DELETE "https://graph.facebook.com/v22.0/me/messenger_profile?fields=greeting&access_token=PAGE_ACCESS_TOKEN"

5. Ice Breakers: levinud küsimused enne esimest sõnumit

Ice Breakers on suhteliselt uus Messenger Platformi funktsioon. Need on valmisküsimustega nupud, mis ilmuvad enne, kui kasutaja on midagi kirjutanud. Klõpsamine saadab teksti kasutaja nimel ja käivitab dialoogi.

Mugav sisseelamiseks: tühja akna asemel näeb inimene küsimusi nagu „Mida sa oskad?", „Kus on minu tellimus?", „Võta klienditoega ühendust" ja alustab dialoogi ühe puudutusega.

Seadistamine:

1
curl -X POST -H "Content-Type: application/json" -d '{
2
  "ice_breakers": [
3
    {
4
      "question": "What can you do?",
5
      "payload": "ICE_CAPABILITIES"
6
    },
7
    {
8
      "question": "Where is my order?",
9
      "payload": "ICE_ORDER_STATUS"
10
    }
11
  ]
12
}' "https://graph.facebook.com/v22.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

Kuni 4 küsimust, maksimaalselt 80 märki küsimuse kohta. Payloadi käsitletakse samas PHP töötlejas switch abil.

⁉️🤔 Korduma kippuvad küsimused

Miks menüü ei ilmu, kuigi päring tagastas edukuse?

Peamised põhjused: „Alusta" nupp on seadistamata, leht pole avaldatud, rakendus on arendusrežiimis, kasutaja kasutab vana Messengeri versiooni või Facebooki mobiilibrauserit. Menüü puhverdatakse lokaalselt, kliendipoolne uuendus võtab aega kuni 24 tundi. Testimiseks kustutage vestlus botiga ja alustage uuesti. Kui menüü pole ikka nähtav, kontrollige kõiki punkte: leht avaldatud, bott avalik, pages_messaging õigus saadud, „Alusta" nupp seadistatud.

Kas saab luua pesastatud menüüd?

Jah, menüüelemendi sees oleva call_to_actions parameetri kaudu. Pesastamine toetab ühte taset, alammenüü avaneb vanemelemendile klõpsates. Vorming sarnaneb peamenüüga: massiiv objektidest, millel on type, title ja payload/url. Pesastatud menüüga vanemelement ei saa olla web_url, ainult postback. Maksimaalne sügavus on üks tase. See on platvormi piirang, millest ei saa mööda minna.

Kuidas erineb kasutajataseme menüü lehe taseme omast?

Lehe taseme menüü on üks kõigile lehe kasutajatele. Kasutajataseme menüü /me/custom_user_settings kaudu võimaldab näidata erinevaid elemente erinevatele inimestele: uued kasutajad saavad „Mida ma teha saan", naasvad kasutajad „Tellimuste ajalugu". Kasutajataseme menüü uueneb reaalajas, lehe taseme oma kuni 24-tunnise viivitusega. Piirang: 10 päringut kasutaja kohta 10 minuti jooksul. Pärast kohandatud menüü eemaldamist taastub lehe menüü automaatselt.

Kuidas kontrollida, et veebihaak võtab POSTBACKi vastu?

Lülitage Facebooki rakenduse seadetes sisse silumisrežiim ja klõpsake botiga vesteldes menüüelementi. Logidesse ilmub kirje väljaga postback.payload. Teise võimalusena lisage töötleja algusesse error_log(print_r($input, true)) ja kontrollige serveri logisid. Kohalikuks arenduseks kasutage ngroki: see suunab avaliku HTTPS URLi kehtiva sertifikaadiga teie localhosti.

Kas koodi tuleb uuendada, kui API versioon muutub?

Jah, kaks korda aastas. Meta annab iga kuue kuu tagant välja uue API versiooni ja keelab vanad 2 aastat pärast asendusversiooni väljalaset. Jälgige Messenger Platformi muudatuste logi. Koodis asendage lihtsalt URLis versiooninumber, väljakutse loogika muutub harva. Plaaniline aegumine: v19.0, jaanuar 2026, v20.0, mai 2026, v21.0, oktoober 2026. Versioon v22.0 on aktiivne kuni maini 2027. Määrake koodis muutuja $api_version.

Mida botiga pärast seadistamist teha: kontrollnimekiri

Menüü, nupp ja tervitus on vundament, mitte lõpp. Kui põhimehaanika töötab, muudavad kolm sammu boti visiitkaardist kasulikuks tööriistaks:

• Ühendage analüütika. Facebook Messenger Insights näitab avamisi, saadetud ja vastuvõetud sõnumeid, aktiivseid dialooge. Ilma nende andmeteta ei tea te, milliseid menüüelemente tegelikult kasutatakse.

• Seadistage varuvastus. Kui kasutaja kirjutab teksti, mida stsenaarium ette ei näe, peaks bott vastama sisukalt, mitte vaikima. Lisage töötlejale vaikeharu pakkumisega avada menüü või võtta ühendust inimesega.

• Uuendage menüüd hooajaliselt. Kampaaniad, uued tooted, pühade allahindlused, muutke menüüelemente aasta läbi. Messenger Profile API kaudu tehakse seda ühe POST-päringuga.

Kui bott töötleb tellimusi või kogub kontakte, seadistage domeen väljal whitelisted_domains WebView korrektseks toimimiseks Messengeri sees. Ja ärge unustage kiiruspiiranguid: 10 Profile API päringut 10 minuti kohta lehe kohta. Järjestage pakettmenüü uuendused tuhandetele kasutajatele viivitustega.