WhatsApp — AI per la Chat Più Usata al Mondo

WhatsApp è ovunque. Oltre due miliardi di persone la usano ogni giorno, e ora puoi collegare Hermes direttamente. Niente account sviluppatore Meta. Niente verifica business. Niente configurazione API complicata. Basta scansionare un codice QR e stai già parlando con il tuo agente AI dalla stessa app che usi per scrivere ai tuoi amici.

Come Funziona

Hermes si collega a WhatsApp tramite un bridge integrato basato su Baileys. Pensalo come un’emulazione di una sessione WhatsApp Web — lo stesso modo in cui collegheresti un browser al tuo telefono. Non è l’API ufficiale WhatsApp Business, il che significa che non servono approvazioni speciali per iniziare.

Esegui hermes gateway setup e scegli WhatsApp per una procedura guidata passo-passo.

Due Modi per Usarlo

Modalità	Come funziona	Ideale per
Numero bot separato (consigliato)	Dedica un numero di telefono al bot. Le persone scrivono direttamente a quel numero.	UX pulita, più utenti, minor rischio di ban
Self-chat personale	Usa il tuo WhatsApp. Scrivi a te stesso per parlare con l’agente.	Configurazione rapida, singolo utente, test

L’approccio con numero bot separato è più pulito — la tua AI ha la sua identità e non mescoli chat personali con conversazioni del bot. La modalità self-chat è perfetta per un test rapido.

Prima di Iniziare

Ti servirà:

Node.js v18+ e npm — il bridge WhatsApp gira come processo Node.js
Un telefono con WhatsApp installato (per scansionare il codice QR)

Buone notizie: a differenza dei vecchi bridge basati su browser, non serve installare Chromium o Puppeteer. La configurazione è molto più leggera.

Passo 1: Esegui la Procedura Guidata

hermes whatsapp

La procedura:

Chiede quale modalità vuoi (bot o self-chat)
Installa le dipendenze del bridge se necessario
Mostra un codice QR nel terminale
Attende che tu lo scansioni

Per scansionare il codice QR:

Apri WhatsApp sul telefono
Vai su Impostazioni → Dispositivi collegati
Tocca Collega un dispositivo
Punta la fotocamera verso il codice QR nel terminale

Una volta associato, la procedura conferma la connessione ed esce. La tua sessione viene salvata automaticamente.

Consiglio: Se il codice QR appare distorto, assicurati che il terminale sia largo almeno 60 colonne e supporti Unicode. Puoi anche provare un emulatore di terminale diverso.

Passo 2: Ottenere un Secondo Numero di Telefono (Modalità Bot)

Per la modalità bot, ti serve un numero non già registrato su WhatsApp. Ecco le tue opzioni:

Opzione	Costo	Note
Google Voice	Gratuito	Solo USA. Ottieni un numero su voice.google.com. Verifica WhatsApp via SMS tramite l’app Google Voice.
SIM prepagata	$5–15 una tantum	Qualsiasi operatore. Attiva, verifica WhatsApp, poi la SIM può stare in un cassetto. Il numero deve restare attivo (fai una chiamata ogni 90 giorni).
Servizi VoIP	Gratuito–$5/mese	TextNow, TextFree o simili. Alcuni numeri VoIP vengono bloccati da WhatsApp — prova più opzioni se il primo non funziona.

Dopo aver ottenuto il numero:

Installa WhatsApp su un telefono (o usa l’app WhatsApp Business con doppia SIM)
Registra il nuovo numero con WhatsApp
Esegui hermes whatsapp e scansiona il codice QR da quell’account WhatsApp

Passo 3: Configura Hermes

Aggiungi quanto segue al file ~/.hermes/.env:

# Obbligatorio
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" o "self-chat"

# Controllo accessi — scegli UNA di queste opzioni:
WHATSAPP_ALLOWED_USERS=15551234567         # Numeri di telefono separati da virgola (con prefisso internazionale, senza +)
# WHATSAPP_ALLOWED_USERS=*                 # OPPURE usa * per permettere a tutti
# WHATSAPP_ALLOW_ALL_USERS=true            # OPPURE imposta questo flag (stesso effetto di *)

Scorciatoia allow-all: Impostare WHATSAPP_ALLOWED_USERS=* permette a tutti i mittenti. Per usare invece il flusso di associazione, rimuovi entrambe le variabili e affidati al sistema di pairing via DM.

Impostazioni opzionali di comportamento in ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair è il default globale. I mittenti DM sconosciuti ricevono un codice di associazione.
whatsapp.unauthorized_dm_behavior: ignore fa sì che WhatsApp resti in silenzio per i DM non autorizzati — di solito la scelta migliore per un numero privato.

Poi avvia il gateway:

hermes gateway              # In primo piano
hermes gateway install      # Installa come servizio utente
sudo hermes gateway install --system   # Solo Linux: servizio di sistema all'avvio

Il gateway avvia automaticamente il bridge WhatsApp usando la sessione salvata.

Persistenza della Sessione

Il bridge Baileys salva la sessione in ~/.hermes/platforms/whatsapp/session. Questo significa:

Le sessioni sopravvivono ai riavvii — non devi riscansionare il codice QR ogni volta
I dati della sessione includono chiavi di crittografia e credenziali del dispositivo
Non condividere o committare questa directory di sessione — concede accesso completo all’account WhatsApp

Riassociazione

Se la sessione si rompe (reset del telefono, aggiornamento WhatsApp, scollegamento manuale), vedrai errori di connessione nei log del gateway. Per risolvere:

hermes whatsapp

Questo genera un nuovo codice QR per la riassociazione.

Una Parola di Cautela

WhatsApp non supporta ufficialmente bot di terze parti al di fuori dell’API Business. Usare un bridge di terze parti comporta un piccolo rischio di restrizioni sull’account. Per minimizzare il rischio:

Usa un numero di telefono dedicato per il bot (non il tuo numero personale)
Non inviare messaggi di massa/spam — mantieni un uso conversazionale
Non automatizzare messaggi in uscita verso persone che non ti hanno scritto per prime

Inoltre, WhatsApp aggiorna periodicamente il protocollo Web, il che può temporaneamente rompere la compatibilità con i bridge di terze parti. Quando succede, Hermes aggiornerà la dipendenza del bridge. Se il bot smette di funzionare dopo un aggiornamento di WhatsApp, scarica l’ultima versione di Hermes e riassocia.

Vuoi Qualcosa di Più Ufficiale?

Se stai gestendo un bot business serio e vuoi stabilità, dai un’occhiata alla guida all’API WhatsApp Business Cloud. È il percorso ufficiale supportato da Meta: nessun rischio di ban dell’account, ma richiede un account Meta Business e un URL webhook pubblico. I due adattatori possono anche girare in parallelo su numeri di telefono diversi se hai un motivo per farlo.

Per la maggior parte dei progetti personali e degli esperimenti, però, il bridge Baileys è il modo più veloce per portare l’AI nel tuo WhatsApp. Scansiona, configura e inizia a chattare.