Käyttäjä kirjoittaa Viberissä, eikä kukaan vastaa. Pienyrityksille tuttu tilanne: yksi vastuuhenkilö, kolme viestintä, ja asiakkaat lähtevät niiden perään, jotka vastasivat ensin. Chatbot ratkaisee tämän ongelman radikaalisti: se toimii ympäri vuorokauden, ei väsy ja reagoi välittömästi.

Aiemmin, ennen helmikuuta 2024, yksinkertaisen Viber-botin pystyi ottamaan käyttöön ilmaiseksi puolessa tunnissa. Nyt säännöt ovat toiset. Viber on siirtänyt botit kokonaan kaupalliselle pohjalle, etkä saa tokenia ilman virallista hakemusta ja kumppania. Mutta jos sinulla on jo julkinen tili (tai olet juuri perustamassa sitä), tekninen osuus, ne samat kuusi vaihetta PHP, on pysynyt samana. Käymme tämän polun tokenista mukautettuun näppäimistöön ja näytämme jokaisen vaiheen.

💡 Pikaopas:

• Luot Viber-julkisen tilin ja hankit todennustokenin: nyt se välitetään HTTP-otsikossa, ei JSON-rungossa
• Määrität webhookin, jossa on HTTPS-varmenne, ja kirjoitat PHP-käsittelijän saapuville callback-pyynnöille
• Toteutat viestien vastaanoton ja vastausten lähetyksen send message -rajapinnan kautta: teksti, kuvat, tiedostot
• Lisäät mukautetun näppäimistön, jossa on pikavastaus- ja linkkipainikkeet, botin tärkein navigointityökalu
• Kirjoitat koodin nykyiselle Viber REST API -versiolle 7.3, et vanhentuneille vuoden 2017 oppaille

Vaihe 1. Luo Viber-julkinen tili

Ensimmäinen askel on hankkia julkinen tili (public account, PA). Helmikuun 5. päivästä 2024 lähtien botit luodaan vain kaupallisesti virallisten Rakuten Viber -kumppaneiden kautta. Prosessi etenee näin:

• Lähetät hakemuksen Viberin julkisten tilien sivulla: yrityksen tyyppi, botin käyttöskenaariot.
• Hyväksynnän jälkeen saapuu kutsu. Käynnistät laitteesi uudelleen, siirryt julkisten tilien päänäyttöön ja painat "Luo julkinen tili".
• Täytät tiedot: nimi, kuvaus, avatar. Pääasiallinen Viber-tilisi asetetaan ylläpitäjäksi.

Lopputuloksena on julkinen tili ja pääsy asetuksiin. Täällä todennustoken tulee näkyviin.

Botit toimivat iOS- ja Android-laitteilla Viber-versiosta 6.5 alkaen ja työpöytäversiossa versiosta 6.5.3 alkaen. Jos sinulla on sovelluksen vanha versio, päivitä se ennen kehityksen aloittamista, muuten näppäimistöt ja jotkin API-metodit eivät toimi.

Vaihe 2. Hanki todennustoken

Token (application key) on bottisi yksilöllinen salainen tunniste. Ilman sitä yksikään API-pyyntö ei mene läpi.

Julkisen tilin luomisen jälkeen token on ylläpitäjän saatavilla julkisen tilin "Muokkaa tietoja" -osiossa. Vaihtoehtoinen tapa on Viber Admin Panelin kautta. Token näyttää suunnilleen tältä:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

Tämä on demotunnus, omassasi on yksilölliset merkit mutta sama rakenne.

Suurin muutos vanhoihin oppaisiin verrattuna: API-versiosta 7.0 alkaen token välitetään ei POST-pyynnön rungossa, vaan X-Viber-Auth-Token-HTTP-otsikossa. Jos lähetät tokenin vanhalla tavalla auth_token-kenttänä JSONissa, API palauttaa missing_auth_token-virheen.

Vanha muoto (ei enää toimi):

1
{"auth_token": "your_token", "url": "https://..."}

Nykyaikainen tapa, otsikko:

1
X-Viber-Auth-Token: your_token

Pidä token salassa. Jokainen, jolla se on, voi lähettää viestejä tilaajillesi botin nimissä.

Vaihe 3. Määritä webhook ja kirjoita PHP-käsittelijä

Webhook on palvelimellasi oleva URL-osoite, johon Viber lähettää callback-pyyntöjä: käyttäjien viestejä, tilausilmoituksia ja muita tapahtumia.

Webhook-URL:n vaatimukset:

• HTTPS-protokolla ja kelvollinen SSL-varmenne luotetulta varmenteen myöntäjältä. Viber ei tue itse allekirjoitettuja varmenteita.
• Varmenteen on oltava Sun Java -luotettujen listalla, tarkista ennen käyttöönottoa.

Webhookin määritys on POST-pyyntö osoitteeseen https://chatapi.viber.com/pa/set_webhook. X-Viber-Auth-Token-otsikossa on tokenisi. Pyynnön runko:

1
{
2
  "url": "https://yourdomain.com/viber-webhook.php",
3
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"],
4
  "send_name": true,
5
  "send_photo": true
6
}

Parametrit:

• url, webhook-URL:si (pakollinen, HTTPS).
• event_types, callback-tapahtumat. Pakolliset ja suodattamattomat: message, subscribed ja unsubscribed. Loput ovat valinnaisia.
• send_name ja send_photo, pyydetäänkö käyttäjän nimi ja kuva. Toimii vain, jos käyttäjä on sallinut "Sisällön personoinnin" Viberin tietosuoja-asetuksissa.

Lähetämme pyynnön cURL-työkalulla:

1
<?php
2
 
3
$url = 'https://chatapi.viber.com/pa/set_webhook';
4
 
5
$jsonData = json_encode([
6
    'url' => 'https://yourdomain.com/viber-webhook.php',
7
    'event_types' => ['delivered', 'seen', 'failed', 'subscribed', 'unsubscribed', 'conversation_started'],
8
    'send_name' => true,
9
    'send_photo' => true
10
]);
11
 
12
$ch = curl_init($url);
13
curl_setopt($ch, CURLOPT_POST, 1);
14
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
15
curl_setopt($ch, CURLOPT_HTTPHEADER, [
16
    'Content-Type: application/json',
17
    'X-Viber-Auth-Token: your_auth_token'
18
]);
19
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
20
$result = curl_exec($ch);
21
curl_close($ch);
22
 
23
echo $result;

Lähetyksen jälkeen Viber lähettää webhook-URL-osoitteeseesi takaisinkutsun varmistaakseen tavoitettavuuden. Odotettavissa on HTTP 200 -vastaus. Takaisinkutsun data:

1
{
2
  "event": "webhook",
3
  "timestamp": 1457764197627,
4
  "message_token": 241256543215
5
}

PHP-käsittelijäsi tulee palauttaa vastaus:

1
{
2
  "status": 0,
3
  "status_message": "ok",
4
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started", "message"]
5
}

Koko webhook-käsittelijän koodi, viber-webhook.php-tiedosto palvelimella:

1
<?php
2
 
3
$request = file_get_contents("php://input");
4
$input = json_decode($request, true);
5
 
6
if ($input['event'] == 'webhook') {
7
    $webhook_response['status'] = 0;
8
    $webhook_response['status_message'] = "ok";
9
    $webhook_response['event_types'] = 'delivered';
10
    echo json_encode($webhook_response);
11
    die;
12
}
13
elseif ($input['event'] == "subscribed") {
14
    // User subscribed — can send a welcome message
15
}
16
elseif ($input['event'] == "conversation_started") {
17
    // User opened chat — can send a menu
18
}
19
elseif ($input['event'] == "message") {
20
    $type = $input['message']['type'];
21
    $text = $input['message']['text'];
22
    $sender_id = $input['sender']['id'];
23
    $sender_name = $input['sender']['name'];
24
 
25
    // Form response
26
    $data = [
27
        'receiver' => $sender_id,
28
        'type' => 'text',
29
        'text' => "Hello, $sender_name! You wrote: $text",
30
        'sender' => [
31
            'name' => 'My Viber Bot'
32
        ]
33
    ];
34
 
35
    $ch = curl_init("https://chatapi.viber.com/pa/send_message");
36
    curl_setopt($ch, CURLOPT_POST, 1);
37
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
38
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
39
        'Content-Type: application/json',
40
        'X-Viber-Auth-Token: your_auth_token'
41
    ]);
42
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
43
    $result = curl_exec($ch);
44
    curl_close($ch);
45
}

Kun webhook on otettu onnistuneesti käyttöön, bottiin ilmestyy 1:1-keskustelupainike ja käyttäjät voivat aloittaa keskustelun. Jos haluat poistaa tämän vaihtoehdon käytöstä, lähetä set_webhook tyhjällä url-arvolla.

Vaihe 4. Vastaanota viestejä käyttäjiltä

Kun käyttäjä kirjoittaa botille, Viber lähettää webhookiisi takaisinkutsun tässä muodossa:

1
{
2
  "event": "message",
3
  "timestamp": 1457764197627,
4
  "message_token": 4912661846655238145,
5
  "sender": {
6
    "id": "01234567890A=",
7
    "name": "yarden",
8
    "avatar": "http://avatar_url"
9
  },
10
  "message": {
11
    "type": "text",
12
    "text": "a message to the service",
13
    "media": "http://download_url",
14
    "location": {
15
      "lat": 50.76891,
16
      "lon": 6.11499
17
    },
18
    "tracking_data": "tracking data"
19
  }
20
}

Tärkeimmät jäsennettävät kentät:

Mitä käsittelijässä on tärkeää tehdä:

• Tallenna sender.id → name/context-linkki tietokantaan. Viber API ei sisällä "hae kaikki tilaajat" -metodia, joten keräät tunnukset itse sitä mukaa kuin pyyntöjä tulee.
• Jos käyttäjä lähetti kuvan (type: "picture"), tiedoston URL on message.media-kentässä.
• Älä ohita tracking_data-kenttää: se linkittää käyttäjän vastauksen lähtevään viestiisi, mikä on korvaamatonta keskusteluanalytiikan kannalta.

Vaihe 5. Lähetä viestejä käyttäjille

send_message-rajapinta tukee tekstiä, kuvia, videoita, tiedostoja, sijainteja, yhteystietoja, tarroja, karuselleja ja URL-esikatseluja. Käydään läpi tärkeimmät tyypit.

Tekstiviesti. POST-pyyntö osoitteeseen https://chatapi.viber.com/pa/send_message X-Viber-Auth-Token-otsakkeella:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "text",
4
  "text": "Hello! How can I help you?",
5
  "sender": {
6
    "name": "Support Bot"
7
  },
8
  "tracking_data": "welcome_message_001"
9
}

Kuvan lähettäminen:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "picture",
4
  "text": "March 2026 promotion",
5
  "media": "https://yourdomain.com/img/promo.jpg",
6
  "thumbnail": "https://yourdomain.com/img/promo_thumb.jpg",
7
  "sender": {
8
    "name": "Shop Bot"
9
  }
10
}

• media, kuvan URL (vain JPEG).
• thumbnail, pikkukuvan URL (myös JPEG).
• text, kuvaus, voi olla null.

PHP-funktio viestien lähettämiseen, yleiskäyttöinen kääre, jota käytämme käytännössä:

1
<?php
2
 
3
function sendViberMessage($receiverId, $type, $data, $trackingData = '') {
4
    $token = 'your_auth_token';
5
    $apiUrl = 'https://chatapi.viber.com/pa/send_message';
6
 
7
    $payload = array_merge(['receiver' => $receiverId, 'type' => $type], $data);
8
 
9
    if ($trackingData) {
10
        $payload['tracking_data'] = $trackingData;
11
    }
12
 
13
    $ch = curl_init($apiUrl);
14
    curl_setopt($ch, CURLOPT_POST, 1);
15
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
16
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
17
        'Content-Type: application/json',
18
        "X-Viber-Auth-Token: $token"
19
    ]);
20
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
21
    $result = curl_exec($ch);
22
    curl_close($ch);
23
 
24
    return json_decode($result, true);
25
}

Rajoitus: JSON-pyynnön maksimikoko on 30 kt. Ota tämä huomioon, kun lähetät karuselleja, joissa on paljon elementtejä.

Vaihe 6. Lisää mukautettu näppäimistö painikkeilla

Näppäimistö korvaa laitteen vakionäppäimistön painikesarjalla: pikavastauksia, linkkejä sivustolle, siirtymiä osioihin. Tämä on botin sisäinen päänavigointityökalu.

Näppäimistö liitetään mihin tahansa viestityyppiin keyboard-kentän kautta send_message-pyynnössä:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "text",
4
  "text": "What are you interested in?",
5
  "sender": {
6
    "name": "Help Bot"
7
  },
8
  "keyboard": {
9
    "Type": "keyboard",
10
    "BgColor": "#FFFFFF",
11
    "Buttons": [
12
      {
13
        "Columns": 6,
14
        "Rows": 1,
15
        "BgColor": "#2db9b9",
16
        "ActionType": "reply",
17
        "ActionBody": "Services",
18
        "Text": "📋 Services",
19
        "TextVAlign": "middle",
20
        "TextHAlign": "center",
21
        "TextSize": "regular"
22
      },
23
      {
24
        "Columns": 6,
25
        "Rows": 1,
26
        "BgColor": "#2db9b9",
27
        "ActionType": "open-url",
28
        "ActionBody": "https://yoursite.com/prices",
29
        "Text": "💰 Prices",
30
        "TextVAlign": "middle",
31
        "TextHAlign": "center",
32
        "TextSize": "regular"
33
      }
34
    ]
35
  }
36
}

Näppäimistön parametrit:

Kunkin painikkeen parametrit:

Muutama tärkeä käytännön nyanssi:

• Painike, jossa on ActionType: "open-url", avaa linkin ulkoisessa selaimessa, ei Viberin sisällä.
• Älä kuormita näppäimistöä liikaa: 4-6 painiketta on optimaalinen määrä yhdelle näytölle.
• Tausta-GIF:t painikkeissa (BgMedia) tukevat toistoa silmukassa BgLoop: true -asetuksella.

Tästä eteenpäin botti on valmis toimimaan: se vastaanottaa viestejä, vastaa tekstillä ja kuvilla, näyttää valikkonäppäimistön.

Tällä videolla on live-esittely koko syklistä: julkisen tilin luomisesta ensimmäisen viestin lähettämiseen näppäimistön kanssa. Hyödyllistä katsoa ennen koodin ajamista omalla palvelimella.

⁉️🤔 Usein kysytyt kysymykset

Voiko Viber-botin luoda ilmaiseksi vuonna 2026?

Ei. Helmikuun 5. päivästä 2024 alkaen Viber on siirtänyt bottien luomisen yksinomaan kaupallisille ehdoille. Tokenin saamiseksi sinun on otettava yhteyttä suoraan Rakuten Viberiin tai johonkin virallisista kumppaneista. Ilmaisia testitilejä ei enää myönnetä. Ennen tätä päivämäärää luodut botit jatkavat toimintaansa.

Onko PHP:n käyttö pakollista Viber-botille?

Ei, kielellä ei ole väliä. Viber API toimii HTTP POST/GET -pyyntöjen kautta, mikä tahansa backend käy: Node.js, Python, Go, Ruby. Näytämme PHP:n, koska se on yleisin kieli WordPress-hostingeilla ja jaetuilla palvelimilla, useimpien sivustonomistajien saatavilla ilman erillistä ympäristön pystytystä.

Miten tarkistan, että webhook toimii?

set_webhook-kutsun jälkeen Viber lähettää välittömästi takaisinkutsun, jossa on "event": "webhook", URL-osoitteeseesi. Palvelin palauttaa HTTP 200, webhook on aktiivinen. Voit tarkistaa nykyisen tilan toistamalla set_webhook-kutsun samoilla parametreilla, API-vastaus näyttää rekisteröidyt event_types-tyypit. Virheenkorjaukseen käytä file_get_contents("php://input")-funktion lokitusta tiedostoon palvelimella.

Mitä eroa on vanhalla ja uudella todennusmenetelmällä?

Ennen API-versiota 7.0 token välitettiin kunkin pyynnön JSON-rungossa auth_token-kenttänä. Moderni API (7.0+) edellyttää tokenin välittämistä X-Viber-Auth-Token-HTTP-otsikossa. Vanhaa muotoa ei tueta, pyynnöt, joissa on auth_token rungossa, palauttavat missing_auth_token-virheen. Jos siirrät koodia vuosien 2017-2023 oppaista, korvaa tokenin välitys otsikolla.

Mitä tehdä, jos käyttäjä ei näe näppäimistöä?

Kolme todennäköistä syytä: (1) JSON-pyyntö ylitti 30 kt:n rajan, vähennä painikkeiden määrää tai poista taustamedia; (2) Type-kenttä sisältää jotain muuta kuin "keyboard", tämä on ainoa tuettu arvo; (3) käyttäjällä on vanha Viber-versio, näppäimistöjä tuetaan versiosta 6.5 alkaen.

Voinko poistaa webhookin ja poistaa 1-on-1-chatin käytöstä?

Kyllä, lähetä set_webhook tyhjällä merkkijonolla url-kentässä:

1
{"url": ""}

Chat-painike katoaa, mutta token ja julkinen tili säilyvät. Hyödyllistä, kun bottia siirretään toiselle palvelimelle.

Mitä valita vuonna 2026: oma PHP-botti vai no-code-alusta

Jos luit tänne asti, edessäsi on kaksi polkua. Ensimmäinen on kirjoittaa botti PHP:llä yllä olevia vaiheita noudattaen. Saat täyden hallinnan logiikasta, datasta ja hostingista. Sopii, kun botti on osa laajempaa projektia: verkkokauppa, tukipalvelu, sisäinen tiimityökalu.

Toinen polku on no-code-alustat, kuten SendPulse, Infobip tai Kommunicate. Ne hoitavat webhook-infrastruktuurin ja tarjoavat visuaalisen editorin skenaarioille. Hintana on kuukausitilaus ja ilmaistason rajoitukset. Tyypillisiin tehtäviin, kuten UKK-automaattivastauksiin ja mainoslähetyksiin, tämä on enemmän kuin riittävä.

Käytännössä yhdistämme yleensä: botin ydin PHP:llä räätälöityä logiikkaa varten, ja kokoamme näppäimistöt ja tervetuloketjut alustan visuaalisella editorilla, nopeammin ja havainnollisemmin. Valitse se, mikä on lähempänä taitojasi ja tehtävääsi. Aloita ensimmäisestä vaiheesta tänään, julkinen tili syntyy puolessa tunnissa, ja sen jälkeen jokainen seuraava vaihe kestää juuri sen aikaa, mikä kuluu koodin kopioimiseen ja mukauttamiseen tästä oppaasta.