Novità nel Setup WhatsApp di Hermes

Se hai seguito la nostra serie su Hermes Agent, sai che amiamo semplificare le cose. Oggi ci immergiamo nel setup WhatsApp aggiornato — e c’è un grande cambiamento sotto il cofano.

Hermes ora si connette a WhatsApp tramite un bridge integrato basato su Baileys. Pensalo come un’emulazione di una sessione WhatsApp Web. Niente account sviluppatore Meta, niente verifica Business, niente URL pubblico — solo tu, il tuo telefono e un codice QR.

Avvio rapido: Esegui hermes gateway setup e seleziona WhatsApp per una procedura guidata passo-passo.

Due Integrazioni WhatsApp — Conosci la Differenza

Prima di andare avanti, chiariamo un punto di confusione comune. Ci sono due modi per connettere WhatsApp a Hermes:

Integrazione	Ideale per	Richiede
Bridge Baileys (questa guida)	Bot personali, test rapidi, nessun URL pubblico	Solo un telefono con WhatsApp
WhatsApp Business Cloud API	Bot aziendali veri, stabilità, rischio zero di ban	Account Meta Business, URL webhook pubblico

Il bridge Baileys è non ufficiale — comporta un piccolo rischio di ban. La Business Cloud API è il percorso ufficiale supportato da Meta. Puoi anche eseguirli entrambi in parallelo su numeri di telefono diversi se necessario.

⚠️ Due Avvertenze Importanti

Rischio di ban: WhatsApp non supporta ufficialmente bot di terze parti al di fuori della Business API. Per restare al sicuro:

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

Aggiornamenti del protocollo: WhatsApp aggiorna periodicamente il suo protocollo Web, il che può temporaneamente rompere i bridge di terze parti. Se il tuo bot smette di funzionare dopo un aggiornamento di WhatsApp, basta scaricare l’ultima versione di Hermes e ri-associare.

Due Modalità — Scegli il Tuo Stile

Modalità	Come funziona	Ideale per
Numero bot separato (consigliato)	Dedica un numero al bot; le persone gli scrivono direttamente	UX pulita, più utenti, minor rischio di ban
Self-chat personale	Usa il tuo WhatsApp; scrivi a te stesso per parlare con l’agente	Setup rapido, singolo utente, test

Prerequisiti

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

Buone notizie: il bridge attuale basato su Baileys non richiede più Chromium o Puppeteer. Molto più leggero.

Passo 1: Esegui la Procedura Guidata

hermes whatsapp

La procedura guidata:

Chiederà quale modalità vuoi (bot o self-chat)
Installerà le dipendenze del bridge se necessario
Mostrerà un codice QR nel terminale
Attenderà che tu lo scansiona

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.

Suggerimento: Se il codice QR appare distorto, assicurati che il terminale sia largo almeno 60 colonne e supporti Unicode.

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

Per la modalità bot, hai bisogno di un numero non già registrato su WhatsApp. Tre opzioni:

Opzione	Costo	Note
Google Voice	Gratuito	Solo USA. Verifica WhatsApp via SMS tramite l’app Google Voice.
SIM prepagata	$5–15 una tantum	Attiva, verifica, poi la SIM può restare in un cassetto. Fai una chiamata ogni 90 giorni per mantenerla attiva.
Servizi VoIP	Gratuito–$5/mese	TextNow, TextFree, ecc. Alcuni numeri sono bloccati da WhatsApp — provane alcuni.

Dopo aver ottenuto il numero:

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

Passo 3: Configura Hermes

Aggiungi questo al tuo file ~/.hermes/.env:

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

# Controllo accessi — scegline UNO:
WHATSAPP_ALLOWED_USERS=15551234567         # Numeri separati da virgola (prefisso internazionale, senza +)
# WHATSAPP_ALLOWED_USERS=*                 # OPPURE consenti a tutti
# WHATSAPP_ALLOW_ALL_USERS=true            # OPPURE imposta questo flag (equivalente a *)

Scorciatoia consenti-tutti: Impostare WHATSAPP_ALLOWED_USERS=* consente tutti i mittenti — equivalente a WHATSAPP_ALLOW_ALL_USERS=true. Per usare invece il flusso di associazione, rimuovi entrambe le variabili e affidati al sistema di pairing via DM.

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair (default globale) invia un codice di associazione ai mittenti DM sconosciuti.
ignore mantiene WhatsApp silenzioso per DM non autorizzati — di solito 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   # Linux: servizio di sistema all'avvio

Persistenza della Sessione e Ri-Associazione

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

Le sessioni sopravvivono ai riavvii — niente ri-scansioni ogni volta
I dati della sessione includono chiavi di crittografia e credenziali del dispositivo
Non condividere o committare questa directory — concede accesso completo all’account

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

hermes whatsapp

Questo genera un nuovo codice QR per la ri-associazione.

Questo è il nuovo setup WhatsApp in sintesi. Rapido, leggero e senza burocrazia Meta. Prossimo articolo della serie: confronteremo questo bridge fianco a fianco con la WhatsApp Business Cloud API — restate sintonizzati!