Ein Nutzer schreibt in Viber, und niemand antwortet. Ein vertrautes Szenario für kleine Unternehmen: ein Manager, drei Messenger, und Kunden gehen zu dem Anbieter, der zuerst reagiert hat. Ein Chatbot löst dieses Problem radikal: Er arbeitet rund um die Uhr, wird nicht müde und reagiert sofort.

Früher, vor Februar 2024, konnte man einen einfachen Viber-Bot in einer halben Stunde kostenlos bereitstellen. Jetzt gelten andere Regeln. Viber hat Bots vollständig auf eine kommerzielle Basis umgestellt; ohne offiziellen Antrag und Partner erhalten Sie keinen Token. Wenn Sie jedoch bereits einen Public Account besitzen (oder ihn gerade einrichten), ist der technische Teil, dieselben sechs Schritte in PHP, gleich geblieben. Wir sind diesen Weg vom Token bis zur benutzerdefinierten Tastatur gegangen und zeigen jeden Schritt.

💡 Kurzüberblick:

• Sie erstellen einen Viber Public Account und erhalten einen Authentifizierungs-Token: Dieser wird jetzt im HTTP-Header übergeben, nicht im JSON-Body.
• Sie richten einen Webhook mit HTTPS-Zertifikat ein und schreiben einen PHP-Handler für eingehende Callback-Anfragen.
• Sie implementieren den Empfang von Nachrichten und das Senden von Antworten über die Send-Message-API: Text, Bilder, Dateien.
• Sie fügen eine benutzerdefinierte Tastatur mit Quick-Reply- und Link-Buttons hinzu, das zentrale Navigationselement innerhalb des Bots.
• Sie schreiben Code für die aktuelle Viber REST API Version 7.3, nicht für veraltete Anleitungen aus dem Jahr 2017.

Schritt 1. Einen Viber Public Account erstellen

Der erste Schritt ist, einen Public Account (PA) zu erhalten. Seit dem 5. Februar 2024 werden Bots nur noch auf kommerzieller Basis über offizielle Rakuten Viber Partner erstellt. Der Ablauf sieht so aus:

• Sie reichen einen Antrag auf der Viber-Public-Accounts-Seite ein: Geschäftstyp, Bot-Nutzungsszenarien.
• Nach der Genehmigung erhalten Sie eine Einladung. Sie starten Ihr Gerät neu, gehen zum Hauptbildschirm der Public Accounts und wählen „Public Account erstellen".
• Sie füllen die Details aus: Name, Beschreibung, Avatar. Ihr Haupt-Viber-Konto wird als Administrator zugewiesen.

Als Ergebnis erhalten Sie einen Public Account und Zugriff auf die Einstellungen. Hier erscheint der Authentifizierungs-Token.

Bots werden auf iOS und Android ab Viber Version 6.5 und höher sowie auf dem Desktop ab Version 6.5.3 unterstützt. Wenn Sie eine ältere Version der App haben, aktualisieren Sie diese vor Entwicklungsbeginn, da sonst Tastaturen und einige API-Methoden nicht funktionieren.

Schritt 2. Den Authentifizierungs-Token erhalten

Der Token (Application Key) ist eine eindeutige, geheime Kennung für Ihren Bot. Ohne ihn wird keine API-Anfrage durchgehen.

Nach der Erstellung eines Public Accounts steht der Token dem Administrator im Bereich „Info bearbeiten" des Public Accounts zur Verfügung. Ein alternativer Weg führt über das Viber Admin Panel. Der Token sieht etwa so aus:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

Dies ist ein Demo-Schlüssel; Ihrer wird eindeutige Zeichen, aber dieselbe Struktur haben.

Die wesentliche Änderung gegenüber alten Anleitungen: Ab API-Version 7.0 wird der Token nicht im Body der POST-Anfrage übergeben, sondern im HTTP-Header X-Viber-Auth-Token. Wenn Sie den Token auf die alte Weise als auth_token-Feld im JSON senden, gibt die API einen missing_auth_token-Fehler zurück.

Altes Format (funktioniert nicht mehr):

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

Moderner Ansatz, Header:

1
X-Viber-Auth-Token: your_token

Bewahren Sie den Token geheim auf. Jeder, der ihn besitzt, kann im Namen des Bots Nachrichten an Ihre Abonnenten senden.

Schritt 3. Den Webhook einrichten und einen PHP-Handler schreiben

Ein Webhook ist eine URL auf Ihrem Server, an die Viber Callback-Anfragen sendet: Nachrichten von Nutzern, Benachrichtigungen über Abonnements und andere Ereignisse.

Anforderungen an die Webhook-URL:

• HTTPS-Protokoll mit einem gültigen SSL-Zertifikat einer vertrauenswürdigen Zertifizierungsstelle. Viber unterstützt keine selbstsignierten Zertifikate.
• Das Zertifikat muss in der Sun Java Trusted List enthalten sein; prüfen Sie dies vor der Einrichtung.

Die Einrichtung des Webhooks erfolgt per POST-Anfrage an https://chatapi.viber.com/pa/set_webhook. Im X-Viber-Auth-Token-Header steht Ihr Token. Anfrage-Body:

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
}

Parameter:

• url, Ihre Webhook-URL (erforderlich, HTTPS).
• event_types, Ereignisse für den Callback. Verpflichtend und nicht filterbar: message, subscribed und unsubscribed. Die übrigen sind optional.
• send_name und send_photo, ob Name und Foto des Nutzers angefordert werden sollen. Funktioniert nur, wenn der Nutzer in den Viber-Datenschutzeinstellungen „Inhaltspersonalisierung" aktiviert hat.

Wir senden die Anfrage per 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;

Nach dem Absenden sendet Viber einen Callback an Ihre Webhook-URL, um die Verfügbarkeit zu prüfen. Erwartet wird eine HTTP-200-Antwort. Callback-Daten:

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

Ihr PHP-Handler sollte folgende Antwort zurückgeben:

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

Vollständiger Webhook-Handler-Code, Datei viber-webhook.php auf dem Server:

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
}

Nach erfolgreichem Webhook-Setup erscheint im Bot ein Button für den 1-zu-1-Chat, Nutzer können einen Dialog starten. Um diese Option zu deaktivieren, senden Sie set_webhook mit einer leeren url.

Schritt 4. Nachrichten von Nutzern empfangen

Wenn ein Nutzer dem Bot schreibt, sendet Viber einen Callback in diesem Format an Ihren Webhook:

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
}

Die wichtigsten auszuwertenden Felder:

Was im Handler unbedingt zu tun ist:

• Speichern Sie den sender.id → name/context-Link in der Datenbank. Die Viber-API bietet keine Methode „Alle Abonnenten abrufen", Sie sammeln die IDs selbst, sobald die Anfragen eingehen.
• Wenn der Nutzer ein Bild gesendet hat (type: "picture"), befindet sich die Datei-URL in message.media.
• Ignorieren Sie tracking_data nicht: Es verknüpft die Antwort des Nutzers mit Ihrer ausgehenden Nachricht und ist für die Dialoganalyse unverzichtbar.

Schritt 5. Nachrichten an Nutzer senden

Die send_message-API unterstützt Text, Bilder, Videos, Dateien, Standorte, Kontakte, Sticker, Karussells und URL-Vorschauen. Betrachten wir die wichtigsten Typen.

Textnachricht. POST-Anfrage an https://chatapi.viber.com/pa/send_message mit X-Viber-Auth-Token-Header:

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
}

Ein Bild senden:

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, Bild-URL (nur JPEG).
• thumbnail, Thumbnail-URL (ebenfalls JPEG).
• text, Beschreibung, kann null sein.

PHP-Funktion zum Senden von Nachrichten, ein universeller Wrapper, den wir in der Praxis einsetzen:

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
}

Einschränkung: Die maximale Größe einer JSON-Anfrage beträgt 30 KB. Berücksichtigen Sie dies beim Versand von Karussells mit vielen Elementen.

Schritt 6: Eine benutzerdefinierte Tastatur mit Schaltflächen hinzufügen

Die Tastatur ersetzt die Standardtastatur des Geräts durch eine Reihe von Schaltflächen: Schnellantworten, Links zur Website, Übergänge zu Abschnitten. Dies ist das wichtigste Navigationsinstrument innerhalb des Bots.

Die Tastatur wird über das Feld keyboard in der send_message-Anfrage an jeden Nachrichtentyp angehängt:

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
}

Tastaturparameter:

Parameter für jede Schaltfläche:

Einige wichtige Nuancen aus der Praxis:

• Eine Schaltfläche mit ActionType: "open-url" öffnet den Link in einem externen Browser, nicht innerhalb von Viber.
• Überladen Sie die Tastatur nicht: 4-6 Schaltflächen sind optimal für einen Bildschirm.
• Hintergrund-GIFs in Schaltflächen (BgMedia) unterstützen Looping über BgLoop: true.

Ab diesem Punkt ist der Bot einsatzbereit: Er empfängt Nachrichten, antwortet mit Text und Bildern und zeigt eine Menü-Tastatur an.

In diesem Video sehen Sie eine Live-Demonstration des gesamten Zyklus: von der Erstellung eines öffentlichen Accounts bis zum Versenden der ersten Nachricht mit einer Tastatur. Hilfreich, um es anzusehen, bevor Sie den Code auf Ihrem eigenen Server ausführen.

⁉️🤔 Häufig gestellte Fragen

Kann man 2026 kostenlos einen Viber-Bot erstellen?

Nein. Seit dem 5. Februar 2024 stellt Viber die Bot-Erstellung ausschließlich auf kommerzielle Bedingungen um. Um ein Token zu erhalten, müssen Sie sich direkt an Rakuten Viber oder einen der offiziellen Partner wenden. Kostenlose Test-Accounts werden nicht mehr ausgegeben. Bots, die vor diesem Datum erstellt wurden, funktionieren weiterhin.

Ist es zwingend erforderlich, PHP für einen Viber-Bot zu verwenden?

Nein, die Sprache spielt keine Rolle. Die Viber-API arbeitet über HTTP POST/GET-Anfragen, jedes Backend ist geeignet: Node.js, Python, Go, Ruby. Wir zeigen PHP, weil es die gängigste Sprache auf WordPress-Hosting und Shared Servern ist und den meisten Website-Betreibern ohne zusätzliche Umgebungseinrichtung zur Verfügung steht.

Wie überprüfe ich, ob der Webhook funktioniert?

Nach dem Aufruf von set_webhook sendet Viber sofort einen Callback mit "event": "webhook" an Ihre URL. Antwortet der Server mit HTTP 200, ist der Webhook aktiv. Sie können den aktuellen Status mit einem erneuten set_webhook-Aufruf mit denselben Parametern prüfen, die API-Antwort zeigt die registrierten event_types an. Nutzen Sie zum Debuggen das Logging von file_get_contents("php://input") in eine Datei auf dem Server.

Was ist der Unterschied zwischen der alten und der neuen Authentifizierungsmethode?

Vor API-Version 7.0 wurde das Token im JSON-Body jeder Anfrage als Feld auth_token übergeben. Die moderne API (7.0+) erfordert die Übergabe des Tokens im HTTP-Header X-Viber-Auth-Token. Das alte Format wird nicht unterstützt, Anfragen mit auth_token im Body geben einen missing_auth_token-Fehler zurück. Wenn Sie Code aus Anleitungen von 2017-2023 migrieren, ersetzen Sie die Token-Übergabe durch einen Header.

Was tun, wenn der Nutzer die Tastatur nicht sieht?

Drei wahrscheinliche Ursachen: (1) Die JSON-Anfrage hat das 30-KB-Limit überschritten, reduzieren Sie die Anzahl der Schaltflächen oder entfernen Sie Hintergrundmedien; (2) das Feld Type enthält etwas anderes als "keyboard", dies ist der einzige unterstützte Wert; (3) der Nutzer verwendet eine alte Version von Viber, Tastaturen werden ab Version 6.5 unterstützt.

Kann ich den Webhook löschen und den 1-zu-1-Chat deaktivieren?

Ja, senden Sie set_webhook mit einem leeren String in url:

1
{"url": ""}

Die Chat-Schaltfläche verschwindet, aber das Token und der öffentliche Account bleiben erhalten. Nützlich, wenn ein Bot auf einen anderen Server umzieht.

Was Sie 2026 wählen sollten: Ihren eigenen PHP-Bot oder eine No-Code-Plattform

Wenn Sie bis hierhin gelesen haben, liegen zwei Wege vor Ihnen. Der erste ist, einen Bot in PHP nach den obigen Schritten zu schreiben. Sie erhalten die volle Kontrolle über Logik, Daten und Hosting. Geeignet, wenn der Bot Teil eines größeren Projekts ist: Onlineshop, Support-Service, internes Team-Tool.

Der zweite Weg sind No-Code-Plattformen wie SendPulse, Infobip oder Kommunicate. Sie übernehmen die Webhook-Infrastruktur und bieten einen visuellen Editor für Szenarien. Der Preis ist ein monatliches Abonnement und die Einschränkungen der kostenlosen Tarife. Für typische Aufgaben wie FAQ-Autoantworten oder Werbe-Mailings ist das mehr als ausreichend.

In der Praxis kombinieren wir meist: den Bot-Kern in PHP für die individuelle Logik, und Tastaturen sowie Begrüßungsketten erstellen wir im visuellen Editor der Plattform, das ist schneller und anschaulicher. Wählen Sie, was Ihren Fähigkeiten und Ihrer Aufgabe näher liegt. Beginnen Sie noch heute mit dem ersten Schritt, ein öffentlicher Account ist in einer halben Stunde eingerichtet, und jeder weitere Schritt dauert genau so lange, wie Sie brauchen, um den Code aus dieser Anleitung zu kopieren und anzupassen.