Un utente scrive su Viber e nessuno risponde. Uno scenario familiare per le piccole imprese: un solo manager, tre messenger, e i clienti se ne vanno da chi ha risposto per primo. Un chatbot risolve questo problema in modo radicale: lavora 24 ore su 24, non si stanca e reagisce all'istante.

Prima, fino a febbraio 2024, mettere in piedi un semplice bot Viber si poteva fare gratis in mezz'ora. Ora le regole sono diverse. Viber ha spostato completamente i bot su base commerciale: non si può ottenere un token senza una richiesta ufficiale e un partner. Ma se avete già un account pubblico (o lo state configurando adesso), la parte tecnica, quei sei passaggi in PHP, è rimasta la stessa. Abbiamo percorso questo tragitto dal token alla tastiera personalizzata e vi mostriamo ogni passaggio.

💡 Panoramica rapida:

• Create un account pubblico Viber e ottenete un token di autenticazione: ora va passato nell'header HTTP, non nel corpo JSON
• Impostate un webhook con certificato HTTPS e scrivete un handler PHP per le richieste di callback in arrivo
• Implementate la ricezione dei messaggi e l'invio delle risposte tramite l'API send message: testo, immagini, file
• Aggiungete una tastiera personalizzata con pulsanti di risposta rapida e link, lo strumento principale di navigazione dentro il bot
• Scrivete il codice per la versione corrente 7.3 delle REST API di Viber, non per guide obsolete del 2017

Step 1. Creare un account pubblico Viber

Il primo passo è ottenere un account pubblico (PA). Dal 5 febbraio 2024, i bot si creano solo su base commerciale tramite i partner ufficiali di Rakuten Viber. Il processo funziona così:

• Inviate una richiesta sulla pagina degli account pubblici Viber: tipo di attività, scenari di utilizzo del bot.
• Dopo l'approvazione, arriva un invito. Riavviate il dispositivo, andate alla schermata principale degli account pubblici e premete "Crea account pubblico".
• Compilate i dettagli: nome, descrizione, avatar. Il vostro account Viber principale viene assegnato come amministratore.

Il risultato è un account pubblico e l'accesso alle impostazioni. È qui che compare il token di autenticazione.

I bot sono supportati su iOS e Android a partire da Viber versione 6.5 e successive, e su desktop dalla versione 6.5.3. Se avete una versione vecchia dell'app, aggiornatela prima di iniziare lo sviluppo, altrimenti le tastiere e alcuni metodi API non funzioneranno.

Step 2. Ottenere il token di autenticazione

Il token (chiave applicativa) è un identificatore segreto univoco per il vostro bot. Senza, nessuna richiesta API andrà a buon fine.

Dopo aver creato un account pubblico, il token è disponibile per l'amministratore nella sezione "Modifica info" dell'account pubblico. Un percorso alternativo è tramite il Pannello di amministrazione Viber. Il token ha un aspetto simile a questo:

455a0f2c05b4fe54-cb4e33d3200fbbae-95f29ebc06af09a8

Questa è una chiave demo, la vostra avrà caratteri unici ma la stessa struttura.

Il cambiamento principale rispetto alle vecchie guide: a partire dalla versione API 7.0, il token va passato non nel corpo della richiesta POST, ma nell'header HTTP X-Viber-Auth-Token. Se inviate il token alla vecchia maniera, come campo auth_token nel JSON, l'API restituirà un errore missing_auth_token.

Vecchio formato (non più funzionante):

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

Approccio moderno, header:

1
X-Viber-Auth-Token: your_token

Tenete il token segreto. Chiunque ne sia in possesso può inviare messaggi ai vostri iscritti per conto del bot.

Step 3. Impostare il webhook e scrivere un handler PHP

Un webhook è un URL sul vostro server a cui Viber invia le richieste di callback: messaggi dagli utenti, notifiche di iscrizione e altri eventi.

Requisiti dell'URL del webhook:

• Protocollo HTTPS con un certificato SSL valido rilasciato da un'autorità di certificazione attendibile. Viber non supporta i certificati autofirmati.
• Il certificato deve essere nella lista di fiducia Sun Java, verificate prima della configurazione.

L'impostazione del webhook è una richiesta POST a https://chatapi.viber.com/pa/set_webhook. Nell'header X-Viber-Auth-Token, il vostro token. Corpo della richiesta:

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
}

Parametri:

• url, l'URL del vostro webhook (obbligatorio, HTTPS).
• event_types, eventi per il callback. Obbligatori e non filtrabili: message, subscribed e unsubscribed. Gli altri sono opzionali.
• send_name e send_photo, se richiedere nome e foto dell'utente. Funziona solo se l'utente ha attivato "Personalizzazione dei contenuti" nelle impostazioni sulla privacy di Viber.

Inviamo la richiesta via 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;

Dopo l'invio, Viber invierà un callback al tuo URL webhook per verificarne la disponibilità. È attesa una risposta HTTP 200. Dati del callback:

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

Il tuo handler PHP deve restituire una risposta:

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

Codice completo del gestore webhook, file viber-webhook.php sul 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
}

Dopo la configurazione riuscita del webhook, nel bot apparirà un pulsante per la chat 1-a-1 e gli utenti potranno avviare un dialogo. Per disabilitare questa opzione, invia set_webhook con un url vuoto.

Step 4. Ricevere messaggi dagli utenti

Quando un utente scrive al bot, Viber invia un callback al tuo webhook in questo formato:

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
}

Campi chiave da analizzare:

Cosa è importante fare nel gestore:

• Salvare il collegamento sender.id → name/context nel database. Le API Viber non hanno un metodo "ottieni tutti gli iscritti": accumuli gli ID in autonomia man mano che arrivano le richieste.
• Se l'utente ha inviato un'immagine (type: "picture"), l'URL del file si trova in message.media.
• Non ignorare tracking_data: collega la risposta dell'utente al tuo messaggio in uscita, è prezioso per l'analisi dei dialoghi.

Step 5. Inviare messaggi agli utenti

L'API send_message supporta testo, immagini, video, file, posizioni, contatti, sticker, caroselli e anteprime URL. Vediamo i tipi principali.

Messaggio di testo. Richiesta POST a https://chatapi.viber.com/pa/send_message con header X-Viber-Auth-Token:

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
}

Invio di un'immagine:

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, URL dell'immagine (solo JPEG).
• thumbnail, URL della miniatura (anch'essa JPEG).
• text, descrizione, può essere null.

Funzione PHP per l'invio di messaggi, un wrapper universale che usiamo nella pratica:

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
}

Limitazione: la dimensione massima della richiesta JSON è di 30 KB. Tenerne conto quando si inviano caroselli con molti elementi.

Passaggio 6. Aggiungere una tastiera personalizzata con pulsanti

La tastiera sostituisce la tastiera standard del dispositivo con un set di pulsanti: risposte rapide, link al sito, passaggi a sezioni. È il principale strumento di navigazione all'interno del bot.

La tastiera si associa a qualsiasi tipo di messaggio tramite il campo keyboard nella richiesta send_message:

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
}

Parametri della tastiera:

Parametri per ciascun pulsante:

Alcune sfumature importanti dalla pratica:

• Un pulsante con ActionType: "open-url" apre il link in un browser esterno, non all'interno di Viber.
• Non sovraccaricare la tastiera: 4-6 pulsanti sono il numero ottimale per una schermata.
• Le GIF di sfondo nei pulsanti (BgMedia) supportano il loop tramite BgLoop: true.

Da questo momento, il bot è pronto per funzionare: riceve messaggi, risponde con testo e immagini, mostra una tastiera menu.

In questo video, una dimostrazione dal vivo del ciclo completo: dalla creazione di un account pubblico all'invio del primo messaggio con tastiera. Utile da guardare prima di eseguire il codice sul proprio server.

⁉️🤔 Domande frequenti

È possibile creare un bot Viber gratuitamente nel 2026?

No. Dal 5 febbraio 2024, Viber ha spostato la creazione di bot esclusivamente su termini commerciali. Per ottenere un token, è necessario contattare direttamente Rakuten Viber o uno dei partner ufficiali. Non vengono più rilasciati account di test gratuiti. I bot creati prima di questa data continuano a funzionare.

È obbligatorio usare PHP per un bot Viber?

No, il linguaggio non ha importanza. L'API di Viber funziona tramite richieste HTTP POST/GET, qualsiasi backend va bene: Node.js, Python, Go, Ruby. Mostriamo PHP perché è il linguaggio più diffuso su hosting WordPress e server condivisi, disponibile per la maggior parte dei proprietari di siti senza dover configurare ambienti aggiuntivi.

Come verifico che il webhook funzioni?

Dopo aver chiamato set_webhook, Viber invia immediatamente un callback con "event": "webhook" al tuo URL. Se il server restituisce HTTP 200, il webhook è attivo. Puoi controllare lo stato attuale con una chiamata ripetuta a set_webhook con gli stessi parametri: la risposta dell'API mostrerà gli event_types registrati. Per il debug, usa il logging di file_get_contents("php://input") su un file nel server.

Qual è la differenza tra il vecchio metodo di autenticazione e quello nuovo?

Prima della versione 7.0 dell'API, il token veniva passato nel corpo JSON di ogni richiesta come campo auth_token. L'API moderna (7.0+) richiede di passare il token nell'header HTTP X-Viber-Auth-Token. Il vecchio formato non è supportato, le richieste con auth_token nel corpo restituiscono un errore missing_auth_token. Se stai migrando codice da guide del 2017-2023, sostituisci il passaggio del token con un header.

Cosa fare se l'utente non vede la tastiera?

Tre probabili cause: (1) la richiesta JSON ha superato il limite di 30 KB, riduci il numero di pulsanti o rimuovi i media di sfondo; (2) il campo Type contiene un valore diverso da "keyboard", che è l'unico valore supportato; (3) l'utente ha una versione vecchia di Viber, le tastiere sono supportate dalla versione 6.5.

Posso eliminare il webhook e disabilitare la chat 1-a-1?

Sì, invia set_webhook con una stringa vuota in url:

1
{"url": ""}

Il pulsante della chat scomparirà, ma il token e l'account pubblico saranno conservati. Utile quando si sposta un bot su un altro server.

Cosa scegliere nel 2026: il proprio bot PHP o una piattaforma no-code

Se sei arrivato a leggere fin qui, hai due strade davanti. La prima è scrivere un bot in PHP seguendo i passaggi sopra. Ottieni il pieno controllo su logica, dati e hosting. È la scelta giusta quando il bot fa parte di un progetto più ampio: negozio online, servizio di assistenza, strumento interno per il team.

La seconda strada sono le piattaforme no-code come SendPulse, Infobip o Kommunicate. Loro gestiscono l'infrastruttura del webhook e forniscono un editor visuale per gli scenari. Il prezzo è un abbonamento mensile e le limitazioni del piano gratuito. Per attività tipiche come risposte automatiche alle FAQ e invii promozionali, questo è più che sufficiente.

Nella pratica, di solito combiniamo: il core del bot in PHP per la logica personalizzata, mentre assembliamo tastiere e catene di benvenuto nell'editor visuale della piattaforma, più veloce e visivo. Scegli ciò che è più vicino alle tue competenze e al tuo obiettivo. Inizia oggi con il primo passaggio: un account pubblico si configura in mezz'ora, e poi ogni passaggio successivo richiede esattamente il tempo necessario per copiare e adattare il codice di questa guida.