Kasutaja vajutab vestluses nuppu ja saab vastuseks mitte palja teksti, vaid piltide, linkide ja värviliste klahvidega ruudustiku. See näeb välja nagu tavaline rakendus. Tegelikult on see tavaline JSON, mille sinu PHP skript Viberi REST API kaudu tagastab.

Enamiku õpetuste probleem: need õpetavad vastama tekstile tekstiga. Päris äribott peab kuvama klaviatuurimenüüd koos linginuppude, piltide ja karussellidega. Muidu kasutaja lihtsalt ei saa aru, mida bott teha suudab, ja lahkub. Alates 2024. aasta veebruarist on Viber muutnud boti loomise äriliseks (100 € kuus ametlike Rakuten Viberi partnerite kaudu) ning autentimine käib nüüd HTTP päises X-Viber-Auth-Token, mitte päringu kehas. JSON-i sees olevad auth_token-iga koodijupid enam ei tööta.

Siin on töötav Viberi bott PHP-s nullist: alates veebihaagi seadistamisest kuni struktureeritud klaviatuurimenüü saatmiseni koos vastamis- ja URL-i avamise nuppudega. Kood on ajakohane API versiooni 7.3 jaoks.

💡 Kiirülevaade:

• Registreeri äriline bott Viberi partneri kaudu ja hangi autentimistoken
• Seadista veebihaak set_webhook kaudu koos X-Viber-Auth-Token päisega
• Võta vastu Viberi callback-sündmused: veebihaak → subscribed → message
• Ehita klaviatuurimenüü (nuppude ruudustik kohandatud värvide, suuruste ja tegevustega)
• Saada struktureeritud vastus: tekst, pildid, lingid, karussellid send_message kaudu

Kuidas Viber Bot API töötab

Viber Bot API töötab REST-mudelil: sinu server saab veebihaagil callback-päringuid ja vastab, kutsudes välja https://chatapi.viber.com/pa/send_message. Iga päring autenditakse tokeniga X-Viber-Auth-Token päises.

Põhitsükkel näeb välja selline:

• Registreerid boti Viberi partneri kaudu ja saad tokeni paneelil „Edit Info".
• Seadistad veebihaagi (sinu serveri URL kehtiva SSL-iga; Let's Encrypt töötab, kuna see on Viberi usaldusväärsete Java sertifikaatide nimekirjas; iseallkirjastatud sertifikaate ei aktsepteerita).
• Viber saadab sellele URL-ile POST-päringuid iga sündmuse korral: kasutaja tellis, saatis sõnumi, vajutas nuppu.
• Sinu PHP skript loeb sissetuleva JSON-i, parsib event välja ja vastab send_message väljakutsega.

Esimene samm mõistmiseks on vaadata elavat botti. Ava Viber ja otsi mõne tuntud brändi avalikku kontot. Peaaegu igal ühel on vestlusbott koos menüüga. Allolev ekraanipilt näitab tüüpilist avaliku konto otsingutulemust.

Pärast tellimist sisenete privaatvestlusesse. See näeb välja umbes selline: avatar, tervitussõnum ja nupp vestluse alustamiseks.

Puudutage paremas ülanurgas sõnumiikooni ja saatke "Tere". Kui botil on seadistatud klaviatuurimenüü, näete vastust koos nuppude ruudustikuga:

See on struktureeritud sõnum. Nuppe on kahte tüüpi: reply saadab botile teksti tagasi (vajutades „Uudised" või „Artiklid"), samas kui open-url avab brauseris lingi. Nüüd kirjutame koodi, mis seda tekitab.

1. Samm: hangi token ja seadista veebihaak

Token asub Viberi halduspaneelil: jaotis Edit Info → väli App Key. See on tähtede ja numbrite jada, mille lisad igasse API päringusse.

Veebihaak seatakse ühe POST-päringuga aadressile https://chatapi.viber.com/pa/set_webhook. Päringu keha on JSON sinu töötleja URL-i ja tellitavate sündmuste loendiga. Päis on X-Viber-Auth-Token koos sinu tokeniga.

Veebihaagi seadistamise skript (salvesta kui setup.php ja käivita üks kord):

1
<?php
2
$token = 'ВАШ_X_VIBER_AUTH_TOKEN';
3
 
4
$data = json_encode([
5
    'url'         => 'https://your-domain.com/webhook.php',
6
    'event_types' => ['message', 'subscribed', 'conversation_started'],
7
]);
8
 
9
$ch = curl_init('https://chatapi.viber.com/pa/set_webhook');
10
curl_setopt($ch, CURLOPT_POST, 1);
11
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
12
curl_setopt($ch, CURLOPT_HTTPHEADER, [
13
    'Content-Type: application/json',
14
    'X-Viber-Auth-Token: ' . $token,
15
]);
16
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
17
 
18
$result = curl_exec($ch);
19
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
20
curl_close($ch);
21
 
22
echo "HTTP {$httpCode}: {$result}\n";
23
 
24
if ($httpCode === 200) {
25
    $response = json_decode($result, true);
26
    if (($response['status'] ?? -1) === 0) {
27
        echo "Вебхук установлен успешно.\n";
28
    } else {
29
        echo "Ошибка Viber: " . ($response['status_message'] ?? 'неизвестная') . "\n";
30
    }
31
}

Mis siin toimub: cURL saadab POST-i aadressile set_webhook. Token on rangelt päises, mitte kehas. Viber tagastab õnnestumisel {"status":0} ja saadab kohe määratud URL-ile webhook callbacki, et kontrollida selle kättesaadavust. Sellele callbackile {"status":0,"status_message":"ok"} vastamine on kohustuslik (käsitleme seda järgmises sammus).

Kui saad vastuseks invalidUrl, kontrolli oma SSL-sertifikaati. Let's Encrypt töötab; iseallkirjastatud ei tööta. Sinu serveris piisab, kui käivitada certbot --nginx -d your-domain.com ja seadistada automaatne uuendamine croni kaudu.

2. Samm: võta vastu Viberi callback-sündmused

Kui kasutaja botiga suhtleb, saadab Viber sinu veebihaagile POST-päringu koos JSON-iga. Sinu ülesanne on lugeda event välja ja reageerida.

Minimaalne töötleja webhook.php, mis vastab korrektselt kõigile sündmustele:

1
<?php
2
$request = file_get_contents("php://input");
3
$input = json_decode($request, true);
4
 
5
if ($input['event'] === 'webhook') {
6
    $response = [
7
        'status'         => 0,
8
        'status_message' => 'ok',
9
        'event_types'    => ['delivered', 'seen', 'message', 'subscribed', 'conversation_started'],
10
    ];
11
    echo json_encode($response);
12
    exit;
13
}
14
 
15
if ($input['event'] === 'subscribed') {
16
    $sender_id = $input['sender']['id'];
17
    sendWelcomeMessage($sender_id);
18
}
19
 
20
if ($input['event'] === 'conversation_started') {
21
    $sender_id = $input['sender']['id'];
22
    sendMainMenu($sender_id);
23
}
24
 
25
if ($input['event'] === 'message') {
26
    $type       = $input['message']['type'];
27
    $text       = $input['message']['text'];
28
    $sender_id  = $input['sender']['id'];
29
    $sender_name = $input['sender']['name'];
30
 
31
    $data = match ($text) {
32
        'News'      => getNewsList($sender_id),
33
        'Articles'  => getArticleList($sender_id),
34
        'Gallery'   => getGalleryList($sender_id),
35
        default     => getMainMenu($sender_id),
36
    };
37
 
38
    sendToViber($data);
39
}

Sündmuste jaotus:

• webhook saabub üks kord, kui veebihaak on seadistatud. Peate tagastama {"status":0,"status_message":"ok"} koos toetatud sündmuste loendiga. Ilma selleta ei kinnita Viber URL-i ja bot ei käivitu.
• subscribed tähendab, et kasutaja on boti tellinud. See on ideaalne hetk tervitusmenüü saatmiseks.
• conversation_started tähendab, et kasutaja avas vestluse (esimest korda või uuesti). Sobib samuti peamenüü kuvamiseks.
• message on peamine töösündmus. Väli text sisaldab kas suvalist kasutaja sõnumit või vajutatud nupu ActionBody't (kui selle tüüp on reply). Nii saab bot aru, mis valiti: „Uudised", „Artiklid" või „Galerii".

Konstrukt match() on saadaval alates PHP 8-st. Kui teil on PHP 7.4, asendage see switch'iga.

Samm 3: klaviatuurimenüü koostamine

Klaviatuur lisatakse igale sõnumile keyboard välja kaudu send_message JSON-objektis. See on nuppude massiiv, millel on eraldi seaded laiuse (Columns, 1-6), kõrguse (Rows, 1-2), taustavärvi, teksti ja tegevuse jaoks.

Funktsioon, mis koostab peamenüü seitsmest vastusnupust ja ühest linginupust:

1
<?php
2
 
3
function getMainMenu(string $user_id): array
4
{
5
    $buttons = [];
6
 
7
    $addReplyButton = function (string $label, string $actionBody, int $cols = 2, int $rows = 2) use (&$buttons) {
8
        $buttons[] = [
9
            'Columns'      => $cols,
10
            'Rows'         => $rows,
11
            'Text'         => $label,
12
            'TextSize'     => 'regular',
13
            'TextVAlign'   => 'bottom',
14
            'TextHAlign'   => 'center',
15
            'TextOpacity'  => 100,
16
            'ActionType'   => 'reply',
17
            'ActionBody'   => $actionBody,
18
            'BgColor'      => '#FFFFFF',
19
        ];
20
    };
21
 
22
    $addReplyButton('NEWS',              'News');
23
    $addReplyButton('ARTICLES',          'Articles');
24
    $addReplyButton('INTERVIEWS',        'Interviews');
25
    $addReplyButton('GALLERY',           'Gallery');
26
    $addReplyButton('POLL',              'Poll');
27
    $addReplyButton('PLAYER OF THE MONTH','POTM');
28
    $addReplyButton('QUOTE OF THE DAY',  'Quote');
29
 
30
    $buttons[] = [
31
        'Columns'      => 4,
32
        'Rows'         => 2,
33
        'Text'         => 'VISIT OUR WEBSITE',
34
        'TextSize'     => 'regular',
35
        'TextVAlign'   => 'bottom',
36
        'TextHAlign'   => 'center',
37
        'TextOpacity'  => 100,
38
        'ActionType'   => 'open-url',
39
        'ActionBody'   => 'https://your-site.com',
40
        'BgColor'      => '#FFFFFF',
41
    ];
42
 
43
    return [
44
        'receiver'   => $user_id,
45
        'type'       => 'text',
46
        'text'       => 'Please select one of the options below:',
47
        'keyboard'   => [
48
            'Type'    => 'keyboard',
49
            'BgColor' => '#FFFFFF',
50
            'Buttons' => $buttons,
51
        ],
52
    ];
53
}

Nupud seadetega Columns=2 ja Rows=2 on ruudukujulised, kolm rea kohta (2+2+2=6). Linginupp Columns=4 hõivab terve oma rea. Ruudustik koostatakse vasakult paremale, ülevalt alla. Rea Columns väärtuste summa määrab paigutuse.

Nupu parameetrid:

Samm 4: andmete saatmine send_message kaudu

Saatmisfunktsioon, mida kutsute sündmuste töötlejast:

1
<?php
2
 
3
function sendToViber(array $data): void
4
{
5
    $token = 'ВАШ_X_VIBER_AUTH_TOKEN';
6
 
7
    $ch = curl_init('https://chatapi.viber.com/pa/send_message');
8
    curl_setopt($ch, CURLOPT_POST, 1);
9
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
10
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
11
        'Content-Type: application/json',
12
        'X-Viber-Auth-Token: ' . $token,
13
    ]);
14
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
15
 
16
    $result = curl_exec($ch);
17
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
18
    curl_close($ch);
19
 
20
    if ($httpCode !== 200) {
21
        error_log("Viber API error: HTTP {$httpCode} - {$result}");
22
    }
23
}

Peamine erinevus vanadest õpetustest: token on päises, mitte JSON-i kehas. Keha sisaldab ainult välju receiver, type, text, keyboard ja valikuliselt sender.name, sender.avatar, tracking_data. Maksimaalne JSON-i suurus on 30 KB. Kui seda ületate, jätab Viber sõnumi vaikselt saatmata; kontrollige enne saatmist strlen(json_encode($data)).

Samm 5: nuppude sisu kokkupanek

Kui kasutaja vajutab vastusnuppu, saadetakse selle ActionBody veebihaaki sõnumi tekstina. Töötlete seda match()'is ja kutsute välja vastava funktsiooni. Siin on näide uudiste loendist piltidega:

1
<?php
2
 
3
function getNewsList(string $user_id): array
4
{
5
    $newsItems = [
6
        [
7
            'title' => 'Your Article Title',
8
            'link'  => 'https://your-site.com/article-1',
9
            'image' => 'https://your-site.com/images/article-1.jpg',
10
        ],
11
        [
12
            'title' => 'Another Article',
13
            'link'  => 'https://your-site.com/article-2',
14
            'image' => 'https://your-site.com/images/article-2.jpg',
15
        ],
16
    ];
17
 
18
    $buttons = [];
19
    foreach ($newsItems as $item) {
20
        $buttons[] = [
21
            'Columns'    => 2,
22
            'Rows'       => 2,
23
            'ActionType' => 'open-url',
24
            'ActionBody' => $item['link'],
25
            'BgColor'    => '#FFFFFF',
26
            'Image'      => $item['image'],
27
        ];
28
        $buttons[] = [
29
            'Columns'    => 4,
30
            'Rows'       => 2,
31
            'Text'       => $item['title'],
32
            'TextSize'   => 'regular',
33
            'TextHAlign' => 'left',
34
            'TextVAlign' => 'top',
35
            'ActionType' => 'open-url',
36
            'ActionBody' => $item['link'],
37
            'BgColor'    => '#F5F5F5',
38
        ];
39
    }
40
 
41
    return [
42
        'receiver' => $user_id,
43
        'type'     => 'text',
44
        'text'     => 'Here are the latest updates:',
45
        'keyboard' => [
46
            'Type'    => 'keyboard',
47
            'BgColor' => '#DDDDDD',
48
            'Buttons' => $buttons,
49
        ],
50
    ];
51
}

Kasutaja poolel näeb see välja nagu kaartide ruudustik: pilt vasakul, pealkiri paremal. Ükskõik millisele osale vajutamine avab lingi brauseris.

Galerii, artiklite loend või küsitlused pannakse kokku täpselt samamoodi; muutuvad ainult massiivi $buttons sisu ja sõnumi tekst. Kui sisu on palju ja JSON läheneb 30 KB-le, jagage see lehekülgedeks nupuga „Järgmine".

Kui eelistate töötada valmis PHP teegiga, mitte toore API-ga, vaadake Bogdaani viber-bot-php. See tegeleb teie eest allkirja valideerimise, sündmuste marsruutimise ja JSON-i genereerimisega.

Kokkuvõte: täielik käivitamise järjekord

• Hangi token Viberi administraatori paneelist: Edit Info jaotis → App Key.
• Paigalda töötleja HTTPS-iga serverisse. Let's Encrypt töötab; iseallkirjastatud sertifikaat ei tööta. Viber valideerib sertifikaadid usaldusväärsete Java juur-CA-de nimekirja alusel.
• Sea veebihaak POST-päringuga aadressile https://chatapi.viber.com/pa/set_webhook kehaga {"url":"https://your-domain/webhook.php","event_types":[...]} ja päisega X-Viber-Auth-Token.
• Kontrolli vastust: {"status":0} tähendab õnnestumist. Viber saadab kohe webhook-i tagasikutse sinu URL-ile. Veendu, et skript tagastab {"status":0,"status_message":"ok"}.
• Saada esimene menüü: conversation_started sündmuse korral kutsu välja getMainMenu() ja edasta tulemus funktsioonile sendToViber().

⁉️🤔 Korduma kippuvad küsimused

Kas veebihaagi jaoks võib kasutada iseallkirjastatud SSL-sertifikaati?

Ei. Viber valideerib sertifikaadi usaldusväärsete Java juursertifikaadi autorite nimekirja alusel. Iseallkirjastatud sertifikaat põhjustab veebihaagi seadistamisel invalidUrl vea. Let's Encrypt on selles nimekirjas ja on tasuta. Käivita oma serveris certbot --nginx -d your-domain.com, lisa automaatne uuendamine cron-isse ja Viber aktsepteerib sertifikaati probleemideta.

Mis vahe on reply ja open-url ActionType'il?

reply saadab ActionBody veebihaagile tagasi sõnumi tekstina. PHP skript näeb seda väljal $input['message']['text'] ja suunab selle match() kaudu edasi. Kasuta seda boti-siseseks navigeerimiseks. open-url avab lingi välises brauseris ega käivita veebihaaki. Praktikas kombineerivad menüüd mõlemat tüüpi: viis või kuus reply-nuppu sektsioonide jaoks ja üks lai open-url-nupp veebisaidile liikumiseks.

Milliseid sõnumitüüpe Viber Bot API toetab?

Viber Bot API toetab üheksat type väärtust sõnumis send_message: text (lihttekst), picture (JPEG-pilt), video (videofail), file (mis tahes fail kuni 50 MB), location (geopunkt), contact (kontaktikaart), sticker (kleeps), rich_media (kaardikarussell) ja url (lingi eelvaade). Praeguse nimekirja koos nõutavate väljadega leiad Viber Developers Hub dokumentatsioonist. Kõige tavalisem stsenaarium on text + keyboard menüüde jaoks ja picture piltide saatmiseks. Karussellid sobivad suurepäraselt tootekataloogide ja e-poodide jaoks, kuid nõuavad rohkem koodi.

Mida teha, kui kasutaja ei näe klaviatuuri?

Sellel on kolm levinumat põhjust. Esiteks: JSON koos klaviatuuriga ületas 30 KB ja Viber jätab sellised sõnumid vaikimisi kõrvale. Kontrolli enne saatmist strlen(json_encode($data)). Teiseks: set_webhook vastus ei sisaldanud "status":0, veebihaaki ei seatud ja bot ei võta sõnumeid vastu. Kolmandaks: kasutad vana formaati, kus JSON-kehas on auth_token. Alates API 7.0-st ignoreeritakse seda; vaja on X-Viber-Auth-Token päist. Silumiseks luba Viber API vastuse logimine: see tagastab loetava JSON-i veakoodidega nagu invalidAuthToken, badData või missingData.

Kas klaviatuuri saab pärast saatmist muuta?

Jah. Iga uue sõnumiga saad saata erineva klaviatuuri. Viberi klient kuvab alati viimast saadud klaviatuuri. See võimaldab ehitada mitmetasandilisi menüüsid: peamenüü → sektsiooni alammenüü → konkreetne sisu. Igal tasandil on oma nuppude komplekt ja kasutaja liigub nende vahel reply-klahve vajutades.

Kui palju maksab Viberi boti käivitamine 2026. aastal?

Alates 5. veebruarist 2024 maksab uue boti loomine ametlike Rakuten Viberi partnerite kaudu 100 € kuus. Enne seda kuupäeva loodud botid jätkavad vanadel tingimustel. Hind sisaldab spetsiaalset kontot koos administraatori paneeli, analüütika ja juurdepääsuga kõikidele sõnumitüüpidele, sealhulgas rich_media ja Viber Pay. API tehniline osa on äriliste ja pärand-tasuta bottide puhul identne.

Bot on valmis: mis saab edasi

Klaviatuurimenüü on vaid sisenemispunkt. Kui põhimehaanika töötab, lisa sisukarussellid rich_media kaudu, maksed Viber Pay kaudu ja kasutajate segmenteerimine selle põhjal, milliseid nuppe nad kõige sagedamini vajutavad. Iga uus tase ei muuda alust: loed endiselt event ja saadad endiselt send_message koos X-Viber-Auth-Token päisega.

Kui vajad elavat näidet töötavast koodist, vaata viber-bot-php repositooriumit GitHubis. See hõlmab kõiki sündmusi, päringu allkirjastamist ja piltidega klaviatuuri ehitamist. Visuaalseks alguseks on siin pooltunnine õpetus Viberi boti nullist loomise kohta:

Peamine, mida meeles pidada: Viber Bot API on alguses lihtne, kuid detailide suhtes nõudlik. Õige autentimispäis, usaldusväärne SSL, kehtiv JSON alla 30 KB ja selge ActionBody marsruutimine on piisavad, et bot töötaks tõrgeteta. Võta ülaltoodud koodijupid, asenda oma token ja domeen ning käivita oma esimene menüü juba täna.