Skip to content

Kaikki WordPressistä, web-kehityksestä — ja paljon muuta

🤖 Pysyvän valikon ja painikkeiden määrittäminen Facebook Messenger -botille
VerkkokehitysOhjelmat ja palvelut
6 min1,241 sanaa

🤖 Pysyvän valikon ja painikkeiden määrittäminen Facebook Messenger -botille

Olet julkaissut botin Facebook Messengerissä, se vastaa viesteihin, mutta jotain puuttuu. Käyttäjä avaa keskustelun ja näkee tyhjän ikkunan. Ei valikkoa, ei vihjeitä, ei "Aloita"-painiketta. Ensimmäinen kosketus, ja hiljaisuus. Ihmiset eivät yksinkertaisesti ymmärrä, mitä bottisi osaa tehdä.

Kolme osatekijää muuttaa kasvottoman botin ymmärrettäväksi käyttöliittymäksi: pysyvä valikko pika-toiminnoilla, "Aloita"-painike ensikontaktiin ja tervehdysteksti, joka toivottaa käyttäjän tervetulleeksi nimellä. Aiemmin kaikki tämä määritettiin vanhentuneen thread_settings-parametrin kautta. Nyt Meta on siirtänyt hallinnan yhtenäiseen Messenger Profile API:in, eivätkä vanhat cURL-kutsut vuoden 2017 tutoriaaleista yksinkertaisesti toimi.

Tässä oppaassa käydään läpi nykyinen tapa määrittää pysyvä valikko, Aloita-painike ja tervehdys Messenger Profile API:n kautta. Mukana toimivat cURL-esimerkit ja PHP POSTBACK -käsittelijä, joka erottaa valikon kohteiden klikkaukset toisistaan.

💡 Pikakatsaus:

  • Määritä pysyvä valikko persistent_menu-kentällä Messenger Profile API:ssa: enintään 20 kohdetta, lokalisointi, kirjoituskentän poistaminen käytöstä
  • Lisää "Aloita"-painike get_started-parametrilla: ensikosketuksella Facebook palauttaa käyttäjän PSID-tunnisteen
  • Aseta tervehdysteksti greeting-kentällä: {{user_first_name}}-mallineet toimivat yhä vuonna 2026
  • Kirjoita PHP POSTBACK -käsittelijä: payload-kenttään perustuva ehtorakenne erottaa, mitä valikon kohtaa käyttäjä klikkasi
  • Huomioi rajoitukset: 10 Profile API -kutsua 10 minuutissa sivua kohden, valikon välimuistin päivittyminen voi kestää jopa 24 tuntia

Mikä muuttui: Thread Settings → Messenger Profile API

Ennen vuotta 2020 valikko, "Aloita"-painike ja tervehdys määritettiin erillisillä POST-pyynnöillä /me/thread_settings-päätepisteeseen. Asetuksen tyyppi määritettiin pyynnön rungossa setting_type-kentällä: call_to_actions valikolle, greeting tervehdykselle. Vuonna 2026 tämä lähestymistapa ei toimi, päätepiste on poistettu dokumentaatiosta.

Nyt kaikki botin ominaisuudet asetetaan Messenger Profile API:n kautta, joka on yhtenäinen päätepiste:

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

Pyynnön runko on JSON-objekti, joka sisältää tarvittavat ominaisuudet: persistent_menu valikolle, get_started "Aloita"-painikkeelle, greeting tervehdykselle, ice_breakers ja whitelisted_domains. Voit lähettää ne yhdessä tai erikseen. Profiili ylikirjoitetaan, joten älä lähetä ominaisuutta, jota et halua muuttaa.

Virallinen dokumentaatio: Persistent Menu Meta for Developers -sivustolla. API-versio päivittyy puolen vuoden välein, tarkista ajantasainen versio muutoslokista.

Valikon toimintaedellytykset, voimassa kesäkuussa 2026:

  • Facebook-sivu on julkaistu, botti on vaihdettu "julkiseen" tilaan sovellusasetuksissa
  • Sovelluksella on pages_messaging-käyttöoikeus
  • Käyttäjällä on Messenger-versio 106 tai uudempi
  • "Aloita"-painike on määritetty (ilman sitä valikko ei näy)
  • Sinulla on sivun ylläpitäjän rooli
Ohjelmakoodi näyttöruudulla

1. Pysyvä valikko (persistent_menu)

Valikko roikkuu syöttökentän vasemmalla puolella, käyttäjä klikkaa "hampurilaiskuvaketta" ja näkee listan toimintoja. Tämä on ylätason navigaatio: "Ohje", "Tuoteluettelo", "Asiakastuki". Enintään 20 kohdetta, mutta Meta suosittelee rajaamaan viiteen paremman käyttökokemuksen vuoksi.

Jokainen kohde on objekti, jossa on type (postback tai web_url), title (enintään 30 merkkiä) ja joko payload tai url. Emojit otsikoissa toimivat, kopioi ne esimerkiksi osoitteesta getemoji.com.

Valikon määrittäminen. Lähetä POST-pyyntö Messenger Profile API:in:

1curl -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"

Onnistunut vastaus: {"result": "success"}. Valikko ei ilmesty heti, asiakaspuolen välimuistin päivittyminen kestää jopa 24 tuntia. Testatessa poista keskustelu ja aloita alusta nähdäksesi muutokset välittömästi.

Valikon poistaminen. DELETE-pyyntö fields-parametrilla:

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

Kirjoituskentän poistaminen käytöstä. Jos botti toimii vain valikon ja painikkeiden kautta, aseta "composer_input_disabled": true. Syöttökenttä katoaa, ja käyttäjä on vuorovaikutuksessa yksinomaan valikkokohteiden ja postback-painikkeiden avulla. Hyödyllinen UKK-boteille ja tuoteluetteloille.

Lokalisointi. Lisää objektit locale-avaimella jokaiselle kielelle. Objekti, jossa on "locale": "default", on pakollinen ja toimii varavaihtoehtona:

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}

Mukautettu valikko. /me/custom_user_settings-päätepisteen kautta voit ohittaa valikon tietylle käyttäjälle PSID-tunnisteen perusteella. Rajoitus: 10 kutsua käyttäjää kohden 10 minuutissa. Mukautetun valikon poistamisen jälkeen sivun oletusvalikko palautuu.

2. POSTBACK-käsittely PHP:llä

Kun käyttäjä napsauttaa valikkokohtaa, jossa on type: "postback", Facebook lähettää messaging_postbacks-tapahtuman webhookiisi. Pyynnön rungossa on postback-objekti, jossa on payload-kenttä, jonka asetit valikkoa määrittäessäsi.

PHP-käsittelijä lukee saapuvan JSON:n php://input-virrasta, poimii payload-arvon ja määrittää switch-rakenteella, mikä toiminto suoritetaan. Alla nykyinen koodi vuodelle 2026 v22.0-päätepisteellä:

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 
13if ($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}

Mikä muuttui. API-versio URL:ssa nostettiin v2.7:stä v22.0:aan. Manuaalisen JSON-merkkijonon kokoamisen sijaan käytetään json_encode()-funktiota, jolloin escapauksen rikkoutumisen riski on pienempi. switch-rakenteeseen lisättiin default-lohko tunnistamatonta payloadia varten. ?? (null coalescing) -rakenne on siistimpi kuin vanha isset() ternäärioperaattoreiden kanssa.

Mihin sijoitetaan. Koodi tulee tiedostoon, johon Facebook-sovelluksen webhook-URL osoittaa. Yleensä tämä on webhook.php sivuston juuressa. Varmista, että saman URL:n GET-metodi hoitaa webhook-varmennuksen hub_challenge-parametrin kautta.

Tärkeää. Säilytä access token ympäristömuuttujissa tai konfiguraatiossa, älä koodissa. Paikallisessa kehityksessä käytä .env-tiedostoa, jossa on PAGE_ACCESS_TOKEN=....

3. Aloituspainike (get_started)

Painike näkyy tervetuloruudulla, kun käyttäjä kohtaa sivun ensimmäistä kertaa. Klikkauksen jälkeen Facebook lähettää messaging_postbacks-tapahtuman määrittämälläsi payloadilla. Vastauksena voit tervehtiä käyttäjää nimeltä tai näyttää painikevalikon.

Ilman määritettyä "Aloitus"-painiketta pysyvä valikko ei näy, tämä on alustan pakollinen vaatimus.

Käyttöönotto:

1curl -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 mielivaltainen, enintään 1000 merkin pituinen merkkijono. PHP-käsittelijässä lisää case 'GET_STARTED_PAYLOAD' switch-rakenteeseen ja palauta personoitu tervehdys.

Poisto:

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

4. Tervehdysteksti (greeting)

Tervehdys näkyy tyhjässä chatissa ennen ensimmäistä viestiä. Tukee mallineita {{user_first_name}} {{user_last_name}} ja {{user_full_name}}. Personointi nimellä lisää sitoutumista, käyttäjä näkee, että botti puhuttelee juuri häntä.

Käyttöönotto:

1curl -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"

Tervehdysteksti tukee myös lokalisointia, lisää objekteja locale-avaimella.

Poisto:

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

5. Ice Breakers: yleisiä kysymyksiä ennen ensimmäistä viestiä

Ice Breakers on suhteellisen uusi Messenger Platform -ominaisuus. Ne ovat valmiilla kysymyksillä varustettuja painikkeita, jotka näkyvät ennen kuin käyttäjä on kirjoittanut mitään. Klikkaaminen lähettää tekstin käyttäjän puolesta ja käynnistää keskustelun.

Kätevä alkuun pääsemisessä: tyhjän ikkunan sijaan henkilö näkee vaihtoehdot kuten "Mitä osaat tehdä?", "Missä tilaukseni on?", "Ota yhteyttä tukeen" ja aloittaa keskustelun yhdellä kosketuksella.

Käyttöönotto:

1curl -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"

Enintään 4 kysymystä, korkeintaan 80 merkkiä kysymystä kohden. Payload käsitellään samassa PHP-käsittelijässä switch-rakenteen kautta.

⁉️🤔 Usein kysytyt kysymykset

Miksi valikko ei tule näkyviin, vaikka pyyntö palautti onnistumisen?

Pääsyyt: "Aloita"-painiketta ei ole määritetty, sivua ei ole julkaistu, sovellus on kehitystilassa, käyttäjä käyttää vanhaa Messenger-versiota tai Facebookin mobiiliselainta. Valikko tallentuu välimuistiin paikallisesti, ja asiakaspuolen päivitys voi kestää jopa 24 tuntia. Testausta varten poista keskustelu botin kanssa ja aloita alusta. Jos valikko ei vieläkään näy, tarkista kaikki kohdat: sivu on julkaistu, botti on julkinen, pages_messaging-oikeus on saatu, "Aloita"-painike on määritetty.

Voiko sisäkkäisen valikon luoda?

Kyllä, call_to_actions-parametrin kautta valikkokohdan sisällä. Sisäkkäisyys tukee yhtä tasoa, ja alavalikko avautuu, kun pääkohdetta klikataan. Muoto on samanlainen kuin päävalikossa: taulukko olioita, joissa on type, title ja payload/url. Pääkohde, jossa on sisäkkäinen valikko, ei voi olla web_url, ainoastaan postback. Suurin sallittu syvyys on yksi taso. Tämä on alustan rajoitus, eikä sitä voi kiertää.

Miten käyttäjätason valikko eroaa sivutason valikosta?

Sivutason valikko on yksi kaikille sivun käyttäjille. Käyttäjätason valikko /me/custom_user_settings-rajapinnan kautta mahdollistaa eri kohteiden näyttämisen eri ihmisille: uudet käyttäjät saavat "Mitä osaan tehdä", palaavat käyttäjät saavat "Tilaushistoria". Käyttäjätason valikko päivittyy reaaliajassa, sivutason valikko jopa 24 tunnin viiveellä. Raja: 10 kutsua per käyttäjä per 10 minuuttia. Mukautetun valikon poistamisen jälkeen sivun valikko palautuu automaattisesti.

Miten tarkistan, vastaanottaako webhook POSTBACKin?

Ota virheenkorjaustila käyttöön Facebook-sovelluksen asetuksissa ja klikkaa valikkokohtaa keskustelussa botin kanssa. Lokeihin ilmestyy merkintä, jossa on postback.payload-kenttä. Vaihtoehtoisesti lisää error_log(print_r($input, true)) käsittelijän alkuun ja tarkista palvelimen lokit. Paikalliseen kehitykseen käytä ngrokia: se tunneloi julkisen HTTPS-URL:n localhostiisi kelvollisella varmenteella.

Täytyykö koodi päivittää, jos API-versio vaihtuu?

Kyllä, kahdesti vuodessa. Meta julkaisee uuden API-version kuuden kuukauden välein ja poistaa vanhat käytöstä 2 vuotta korvaavan version julkaisun jälkeen. Seuraa Messenger Platformin muutoslokia. Koodissa riittää versionumeron vaihtaminen URL-osoitteeseen, kutsulogiikka muuttuu harvoin. Aikataulutettu vanheneminen: v19.0, tammikuu 2026, v20.0, toukokuu 2026, v21.0, lokakuu 2026. Versio v22.0 on aktiivinen toukokuuhun 2027 asti. Aseta $api_version-muuttuja koodissa.

Mitä botille tehdään asennuksen jälkeen: tarkistuslista

Valikko, painike ja tervehdys ovat perusta, eivät maali. Kun perusmekaniikat toimivat, kolme askelta muuttaa botin käyntikortista hyödylliseksi työkaluksi:

  • Yhdistä analytiikka. Facebook Messenger Insights näyttää avaukset, lähetetyt ja vastaanotetut viestit, aktiiviset keskustelut. Ilman tätä dataa et tiedä, mitä valikkokohtia oikeasti käytetään.

  • Määritä varavastaus. Kun käyttäjä kirjoittaa tekstiä, jota ei ole skenaariossa huomioitu, botin tulee vastata mielekkäästi, ei vaieta. Lisää käsittelijään oletushaara, jossa tarjotaan valikon avaamista tai yhteyttä ihmiseen.

  • Päivitä valikko sesongeittain. Kampanjat, uudet tuotteet, juhlapyhien alennusmyynnit, vaihda valikon kohteita ympäri vuoden. Messenger Profile APIn kautta tämä onnistuu yhdellä POST-pyynnöllä.

Jos botti käsittelee tilauksia tai kerää yhteystietoja, määritä verkkotunnus whitelisted_domains-kenttään, jotta WebView toimii oikein Messengerin sisällä. Äläkä unohda nopeusrajoituksia: 10 Profile API -kutsua 10 minuutissa per sivu. Jonoita joukkopäivitykset tuhansille käyttäjille viiveillä.

Toimitus
ToimitusToimitustiimi→ All publications

Ammattimainen kirjoittajien ja toimittajien tiimi, joka on erikoistunut laadukkaan sisällön luomiseen.