Użytkownik pisze na Viberze, a nikt mu nie odpowiada. Znajomy obrazek dla małego biznesu: jeden menedżer, trzy komunikatory, a klienci odchodzą do tych, którzy odpowiedzieli pierwsi. Chatbot rozwiązuje ten problem radykalnie: pracuje całodobowo, nie męczy się i reaguje natychmiast.

Wcześniej, przed lutym 2024, wdrożenie prostego bota Viber można było zrobić bezpłatnie w pół godziny. Teraz zasady są inne. Viber całkowicie przeniósł boty na komercyjne tory, bez oficjalnego wniosku i partnera tokena nie da się uzyskać. Ale jeśli mają już Państwo konto publiczne (albo zakładają je właśnie teraz), część techniczna, te same sześć kroków w PHP, pozostała niezmieniona. Przeszliśmy tę drogę od tokena do niestandardowej klawiatury i pokazujemy każdy krok.

💡 Szybki przegląd:

• Tworzą Państwo konto publiczne Viber i uzyskują token uwierzytelniający: teraz jest on przekazywany w nagłówku HTTP, a nie w treści JSON
• Konfigurują Państwo webhook z certyfikatem HTTPS i piszą handler PHP dla przychodzących żądań callback
• Implementują Państwo odbieranie wiadomości i wysyłanie odpowiedzi przez API send message: tekst, obrazy, pliki
• Dodają Państwo niestandardową klawiaturę z przyciskami szybkich odpowiedzi i linków, główne narzędzie nawigacji wewnątrz bota
• Kod piszą Państwo pod aktualną wersję Viber REST API 7.3, a nie pod przestarzałe poradniki z 2017 roku

Krok 1. Proszę utworzyć konto publiczne Viber

Pierwszy krok, uzyskanie konta publicznego (PA). Od 5 lutego 2024 boty tworzy się wyłącznie na zasadach komercyjnych za pośrednictwem oficjalnych partnerów Rakuten Viber. Proces wygląda następująco:

• Zostawiają Państwo zgłoszenie na stronie kont publicznych Viber: typ biznesu, scenariusze użycia bota.
• Po zatwierdzeniu przychodzi zaproszenie. Proszę ponownie uruchomić urządzenie, wejść na główny ekran kont publicznych i nacisnąć „Utwórz konto publiczne".
• Wypełniają Państwo dane: nazwa, opis, awatar. Administratorem zostaje Państwa główne konto Viber.

Na wyjściu, konto publiczne i dostęp do ustawień. To właśnie tam pojawia się token uwierzytelniający.

Boty są obsługiwane na iOS i Androidzie od wersji Viber 6.5 wzwyż, a na desktopie od wersji 6.5.3. Jeśli wersja aplikacji jest stara, proszę zaktualizować ją przed rozpoczęciem prac, w przeciwnym razie klawiatury i część metod API nie zadziałają.

Krok 2. Proszę uzyskać token uwierzytelniający

Token (application key) to unikalny, tajny identyfikator Państwa bota. Bez niego żadne żądanie API nie przejdzie.

Po utworzeniu konta publicznego token jest dostępny dla administratora w sekcji „Edytuj informacje" konta publicznego. Alternatywna ścieżka, przez Viber Admin Panel. Token wygląda mniej więcej tak:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

To klucz demonstracyjny, Państwa będzie miał unikalne znaki, ale tę samą strukturę.

Główna zmiana w porównaniu ze starymi poradnikami: począwszy od wersji API 7.0 token jest przekazywany nie w treści żądania POST, a w nagłówku HTTP X-Viber-Auth-Token. Jeśli wyślą Państwo token po staremu, polem auth_token w JSON, API zwróci błąd missing_auth_token.

Stary format (już nie działa):

1
{"auth_token": "ваш_токен", "url": "https://..."}

Współczesne podejście, nagłówek:

1
X-Viber-Auth-Token: ваш_токен

Proszę trzymać token w tajemnicy. Każdy, kto go ma, może wysyłać wiadomości do Państwa subskrybentów w imieniu bota.

Krok 3. Proszę skonfigurować webhook i napisać handler PHP

Webhook to URL Państwa serwera, na który Viber wysyła żądania callback: wiadomości od użytkowników, powiadomienia o subskrypcji i inne zdarzenia.

Wymagania wobec webhook URL:

• Protokół HTTPS z ważnym certyfikatem SSL od zaufanego centrum certyfikacji. Viber nie obsługuje certyfikatów z podpisem własnym.
• Certyfikat musi znajdować się na liście zaufanych Sun Java, proszę sprawdzić przed konfiguracją.

Konfiguracja webhooka to żądanie POST do https://chatapi.viber.com/pa/set_webhook. W nagłówku X-Viber-Auth-Token, Państwa token. Treść żądania:

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
}

Parametry:

• url, Państwa webhook URL (obowiązkowy, HTTPS).
• event_types, zdarzenia do callback. Obowiązkowe i niefiltrowane: message, subscribed i unsubscribed. Pozostałe opcjonalne.
• send_name i send_photo, czy pytać o imię i zdjęcie użytkownika. Działa tylko wtedy, gdy użytkownik włączył „Personalizację treści" w ustawieniach prywatności Viber.

Wysyłamy zapytanie przez cURL:

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;

Po wysłaniu Viber wyśle callback na Państwa webhook URL w celu weryfikacji dostępności. Oczekiwana jest odpowiedź HTTP 200. Dane callback:

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

Państwa handler PHP musi zwrócić odpowiedź:

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

Pełny kod handlera webhook, plik viber-webhook.php na serwerze:

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
    // Пользователь подписался — можно отправить приветствие
15
}
16
elseif ($input['event'] == "conversation_started") {
17
    // Пользователь открыл чат — можно отправить меню
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
    // Формируем ответ
26
    $data = [
27
        'receiver' => $sender_id,
28
        'type' => 'text',
29
        'text' => "Привет, $sender_name! Вы написали: $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
}

Po pomyślnym ustawieniu webhooka w bocie pojawi się przycisk czatu 1-na-1, użytkownicy będą mogli rozpocząć rozmowę. Aby wyłączyć tę możliwość, należy wysłać set_webhook z pustym url.

Krok 4. Odbieraj wiadomości od użytkowników

Gdy użytkownik pisze do bota, Viber wysyła na Państwa webhook callback w następującym formacie:

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
}

Kluczowe pola do parsowania:

Co ważne, aby zrobić w handlerze:

• Proszę zapisać powiązanie sender.id → имя/контекст w bazie danych. Viber API nie ma metody „pobierz wszystkich subskrybentów", gromadzą Państwo ID samodzielnie w miarę zgłoszeń.
• Jeśli użytkownik wysłał obraz (type: "picture"), URL pliku znajduje się w message.media.
• Proszę nie ignorować tracking_data: wiąże ono odpowiedź użytkownika z Państwa wiadomością wychodzącą, jest niezastąpione do analityki dialogów.

Krok 5. Wysyłaj wiadomości do użytkowników

API send_message obsługuje tekst, obrazy, wideo, pliki, lokalizację, kontakty, naklejki, karuzele i podglądy URL. Omówmy główne typy.

Wiadomość tekstowa. Zapytanie POST do https://chatapi.viber.com/pa/send_message z nagłówkiem X-Viber-Auth-Token:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "text",
4
  "text": "Здравствуйте! Чем могу помочь?",
5
  "sender": {
6
    "name": "Support Bot"
7
  },
8
  "tracking_data": "welcome_message_001"
9
}

Wysyłanie obrazu:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "picture",
4
  "text": "Акция марта 2026",
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, URL obrazu (tylko JPEG).
• thumbnail, URL miniatury (również JPEG).
• text, opis, może być null.

Funkcja PHP do wysyłania wiadomości, uniwersalny wrapper, którego używamy w praktyce:

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
}

Ograniczenie: maksymalny rozmiar żądania JSON, 30 KB. Proszę uwzględnić to podczas wysyłania karuzel z dużą liczbą elementów.

Krok 6. Dodanie niestandardowej klawiatury z przyciskami

Klawiatura zastępuje standardową klawiaturę urządzenia zestawem przycisków: szybkie odpowiedzi, linki do stron, przejścia do sekcji. To główne narzędzie nawigacji wewnątrz bota.

Klawiaturę dołącza się do dowolnego typu wiadomości poprzez pole keyboard w żądaniu send_message:

1
{
2
  "receiver": "01234567890A=",
3
  "type": "text",
4
  "text": "Что вас интересует?",
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": "Услуги",
18
        "Text": "📋 Услуги",
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": "💰 Цены",
30
        "TextVAlign": "middle",
31
        "TextHAlign": "center",
32
        "TextSize": "regular"
33
      }
34
    ]
35
  }
36
}

Parametry klawiatury:

Parametry każdego przycisku:

Kilka ważnych niuansów z praktyki:

• Przycisk z ActionType: "open-url" otwiera link w zewnętrznej przeglądarce, a nie wewnątrz Vibera.
• Nie przeciążaj Pan klawiatury: 4-6 przycisków to optimum na jeden ekran.
• GIF-y w tle przycisków (BgMedia) obsługują zapętlenie przez BgLoop: true.

Od tego momentu bot jest gotowy do pracy: odbiera wiadomości, odpowiada tekstem i obrazami, wyświetla menu-klawiaturę.

W tym filmie znajduje się demonstracja na żywo pełnego cyklu: od utworzenia konta publicznego do wysłania pierwszej wiadomości z klawiaturą. Warto obejrzeć przed uruchomieniem kodu na swoim serwerze.

⁉️🤔 Często zadawane pytania

Czy można utworzyć bota Viber za darmo w 2026 roku?

Nie. Od 5 lutego 2024 Viber przeniósł tworzenie botów wyłącznie na warunki komercyjne. Aby uzyskać token, należy skontaktować się bezpośrednio z Rakuten Viber lub jednym z oficjalnych partnerów. Darmowe konta testowe nie są już wydawane. Boty utworzone przed tą datą nadal działają.

Czy do stworzenia bota Viber konieczne jest użycie PHP?

Nie, język nie ma znaczenia. API Vibera działa poprzez żądania HTTP POST/GET, odpowiedni będzie każdy backend: Node.js, Python, Go, Ruby. Pokazujemy PHP, ponieważ jest to najpopularniejszy język na hostingach WordPress i serwerach współdzielonych, dostępny dla większości właścicieli stron bez dodatkowej konfiguracji środowiska.

Jak sprawdzić, czy webhook działa?

Po wywołaniu set_webhook Viber natychmiast wysyła callback z "event": "webhook" na Pana adres URL. Jeśli serwer zwróci HTTP 200, webhook jest aktywny. Aktualny status można sprawdzić, wywołując ponownie set_webhook z tymi samymi parametrami, odpowiedź API pokaże zarejestrowane event_types. Do debugowania proszę używać logowania file_get_contents("php://input") do pliku na serwerze.

Czym różni się stary sposób uwierzytelniania od nowego?

Przed wersją API 7.0 token był przekazywany w ciele JSON każdego żądania w polu auth_token. Współczesne API (7.0+) wymaga przekazywania tokena w nagłówku HTTP X-Viber-Auth-Token. Stary format nie jest obsługiwany, żądania z auth_token w ciele zwracają błąd missing_auth_token. Jeśli przenosi Pan kod z poradników z lat 2017-2023, proszę zastąpić przekazywanie tokena nagłówkiem.

Co zrobić, jeśli użytkownik nie widzi klawiatury?

Trzy prawdopodobne przyczyny: (1) żądanie JSON przekroczyło limit 30 KB, proszę zmniejszyć liczbę przycisków lub usunąć tła multimedialne; (2) w polu Type podano wartość inną niż "keyboard", jest to jedyna obsługiwana wartość; (3) użytkownik ma starą wersję Vibera, klawiatury są obsługiwane od wersji 6.5.

Czy można usunąć webhook i wyłączyć czat 1-na-1?

Tak, proszę wysłać set_webhook z pustym ciągiem w url:

1
{"url": ""}

Przycisk czatu zniknie, ale token i konto publiczne zostaną zachowane. Przydatne podczas przenoszenia bota na inny serwer.

Co wybrać w 2026 roku: własnego bota PHP czy platformę no-code

Jeśli doczytał Pan do tego miejsca, ma Pan przed sobą dwie ścieżki. Pierwsza to napisanie bota w PHP według powyższych kroków. Otrzymuje Pan pełną kontrolę nad logiką, danymi i hostingiem. Jest to odpowiednie, gdy bot jest częścią większego projektu: sklepu internetowego, działu obsługi klienta, wewnętrznego narzędzia zespołu.

Druga ścieżka to platformy no-code, takie jak SendPulse, Infobip lub Kommunicate. Przejmują one infrastrukturę webhooków i oferują wizualny edytor scenariuszy. Kosztem jest miesięczna subskrypcja i ograniczenia darmowego planu. Dla typowych zadań, jak autoinformator FAQ czy wysyłka promocji, to w zupełności wystarcza.

W praktyce zazwyczaj łączymy oba podejścia: rdzeń bota na PHP do niestandardowej logiki, a klawiatury i łańcuchy powitalne budujemy w wizualnym edytorze platformy, co jest szybsze i bardziej przejrzyste. Proszę wybrać to, co jest bliższe Pana umiejętnościom i zadaniu. Proszę zacząć od pierwszego kroku już dziś, założenie konta publicznego zajmuje pół godziny, a każdy kolejny krok wymaga dokładnie tyle czasu, ile potrzeba na skopiowanie i dostosowanie kodu z tego poradnika.