Chatbot Viber per l'assistenza clienti: come funziona e come configurarlo

Il tuo bot è identificato da un token di autenticazione. Ogni richiesta alla REST Bot API deve includerlo in un header HTTP chiamato X-Viber-Auth-Token; se lo ometti, ricevi un errore missing_auth_token. Registri un webhook HTTPS pubblico con set_webhook, Viber vi invia le callback man mano che succedono le cose e tu rispondi con send_message.

Quando chiami set_webhook, Viber verifica il tuo URL inviandogli una callback con l'evento webhook. La verifica riesce solo se il tuo server risponde con lo stato HTTP 200. Una risposta set_webhook riuscita ha status 0; un URL irraggiungibile restituisce status 1, invalidUrl.

1. Il cliente apre il tuo bot da un link sul tuo sito web e Viber invia una callback conversation_started.
2. Il tuo bot invia un messaggio di benvenuto con pulsanti per gli argomenti più comuni.
3. Il cliente risponde, il che lo iscrive, e il tuo bot riceve una callback message.
4. Il bot risponde alle domande semplici e raccoglie i dati per tutto il resto.
5. I casi non risolti diventano ticket nell'helpdesk, e le risposte degli operatori tornano indietro tramite send_message.

L'URL del webhook deve usare SSL con un certificato valido emesso da un'autorità di certificazione attendibile. L'elenco facoltativo event_types in set_webhook stabilisce quali callback ricevi, ma alcune non si possono disattivare.

Viber firma ogni callback. L'header X-Viber-Content-Signature contiene un HMAC-SHA256 del corpo della richiesta, calcolato con il tuo token di autenticazione come chiave, quindi verificalo prima di elaborare qualsiasi cosa. Se il tuo webhook non restituisce HTTP 200, Viber ritenta la callback più volte, quindi assicurati che una callback ripetuta non crei un ticket duplicato.

Questa regola definisce ogni flusso di assistenza su Viber: il tuo bot può inviare messaggi solo agli utenti che si sono iscritti. Un evento conversation_started non è un'iscrizione. Consente un solo messaggio di benvenuto, che secondo Viber va inviato entro 5 minuti tramite send_message, includendo il parametro receiver. L'evento si attiva anche per gli utenti già iscritti.

Un utente si iscrive inviando un messaggio al bot. Quel primo messaggio genera una callback message, non una callback subscribed, quindi salva l'ID utente da entrambi gli eventi. Gli utenti possono annullare l'iscrizione in qualsiasi momento, il che blocca subito ogni ulteriore messaggio dal bot, e ricevi una callback unsubscribed con il loro ID. Se si iscrivono di nuovo, il contesto o i tracking_data della conversazione vengono eliminati.

Per avviare conversazioni dal tuo sito web, usa un deep link nel formato viber://pa?chatURI= seguito dall'URI del tuo bot. Aggiungere un parametro context passa un valore, come la pagina da cui arriva il cliente, nella callback conversation_started. Viber segnala che alcuni browser potrebbero non riconoscere il deep link. Per gli avvisi di disservizio, la broadcast API invia fino a 300 destinatari per richiesta, e chiunque non sia iscritto viene restituito come failed.

Una richiesta send_message indica il receiver (l'ID utente), il tipo di messaggio e un oggetto sender il cui name è obbligatorio e limitato a 28 caratteri. I messaggi di testo possono arrivare a 7.000 caratteri. Due campi facoltativi sono utili per l'assistenza: tracking_data (fino a 4.096 caratteri), che Viber ripassa insieme alla risposta dell'utente, quindi può contenere un ID ticket o il passaggio corrente di un flusso; e min_api_version, la versione minima dell'API client necessaria per il messaggio, che per impostazione predefinita è 1.

Le tastiere si possono associare a qualsiasi tipo di messaggio tramite il campo keyboard. Ogni pulsante ha un ActionType:

• reply (il valore predefinito) invia al bot la risposta del pulsante.
• open-url apre un URL, all'interno di Viber o in un browser esterno a seconda di OpenURLType, e invia l'URL al bot.
• Sono disponibili anche location-picker, share-phone e none.

Due impostazioni della tastiera aiutano i flussi di assistenza. InputFieldState impostato su hidden rimuove il campo di testo quando vuoi che i clienti scelgano un pulsante, e DefaultHeight impostato su true mantiene la tastiera all'altezza di quella nativa.

A ottobre 2026, la documentazione per sviluppatori di Viber afferma che “dal 5.02.24 i bot Viber possono essere creati solo a condizioni commerciali”, con richieste da inviare direttamente a Rakuten Viber o tramite i suoi partner ufficiali verificati. Chiedi a Viber o a un partner i prezzi attuali prima di sviluppare. La risposta di send_message include anche un campo con lo stato di fatturazione (billing status) che mostra come ogni messaggio è stato classificato ai fini della fatturazione.

Per il passaggio agli operatori, Zendesk elenca Viber tra i canali disponibili tramite Sunshine Conversations. Aggiungere canali Sunshine Conversations all'Agent Workspace richiede Suite Professional o superiore, e devi anche usare la messaggistica e l'Agent Workspace. I messaggi diventano così ticket, e le risposte degli operatori tornano al cliente. Senza questa opzione, lo schema abituale è un piccolo servizio che crea ticket tramite l'API del tuo helpdesk e invia le risposte degli operatori con send_message.

I canali per bot indicati da TascaLab sono sito web, telefono, WhatsApp, Telegram, Facebook Messenger e Instagram. Viber non è in quell'elenco, ma altri canali con un'API possono essere valutati durante la call di Health Check gratuita di 30 minuti. TascaLab lavora sopra gli strumenti che usi già, come Zendesk, Freshdesk, Jira e Slack, tramite API, webhook e Make o n8n. Uno Starter Chat Bot costa 360 € per uno o due canali e uno Standard Chat Bot 510 € per tre-cinque canali. Ogni progetto include 30 giorni di supporto dopo il lancio, una documentazione di base e nessun costo nascosto, e la maggior parte delle configurazioni richiede 1–3 settimane.