Hermes Agent su WhatsApp non si connette: soluzioni

Il bot non risponde mai e i log sono muti

Hai collegato Hermes Agent a WhatsApp, il gateway parte senza errori, e il numero a cui scrivi resta fermo come un sasso. Nessun evento entrante nei log, nessuna ricevuta di consegna sul telefono, nessun indizio chiaro su quale dei dieci pezzi in movimento sia rotto. WhatsApp è il canale più fragile dello stack Hermes, e quasi ogni caso di connessione silenziosa si riduce a una di quattro cause.

Tre delle quattro falliscono in silenzio per design, ed è per questo che il setup sembra corretto mentre non funziona nulla. Questo post attraversa ogni causa, come confermare che sia la tua, e la soluzione esatta. Parti dall'alto - l'ordine conta, perché la prima causa è quella che sta pescando tutti da maggio 2026.

Causa 1: WhatsApp Shortcake ha rotto la tua libreria QR

Se stai eseguendo Hermes Agent tramite Baileys, WAHA o qualunque altra libreria che fa scraping di WhatsApp Web, e il QR si rifiuta di essere scansionato o disconnette il bot subito dopo, stai sbattendo contro il rollout di Shortcake per i dispositivi collegati. WhatsApp ora richiede una passkey WebAuthn sul dispositivo collegato, e un server headless non ha una passkey da presentare: navigator.credentials.get() fallisce e il link viene respinto con un 428.

Sintomo: il QR si disegna, il tuo telefono lo scansiona, e o l'accoppiamento non si conclude mai o la sessione muore in pochi minuti. Le sessioni vecchie che si riconnettevano da sole hanno iniziato a restituire Stream Errored (conflict) dopo maggio 2026 per lo stesso motivo. Se funzionava ad aprile ed è smesso di funzionare da un giorno all'altro, è la tua causa.

La soluzione ha due forme:

Passa alla Cloud API ufficiale. È il percorso supportato, non è vulnerabile a Meta che rompe una libreria di scraping un martedì qualsiasi, ed è quello che il resto del post assume. Configura Hermes Agent con WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID e WHATSAPP_WEBHOOK_VERIFY_TOKEN al posto del flusso QR. La guida al deploy di WhatsApp percorre l'intera danza delle credenziali.
Resta su Baileys se non hai alternative, e fissa il commit upstream esatto che ancora ti funziona (i maintainer tracciano i workaround per la passkey nella issue #2672). Sappi che il prossimo cambio di Meta ti rompe di nuovo. Non è la scelta giusta per qualcosa su cui ti affidi davvero.

Il resto del post copre il percorso Cloud API.

Causa 2: la tua WABA non è sottoscritta alla tua app

È il fallimento più comune della Cloud API e il più silenzioso. Imposti l'URL del webhook nell'App Dashboard, il GET di verifica passa, Meta mostra una spunta verde accanto all'endpoint, e nessun evento di messaggio arriva mai.

Cosa succede: fissare l'URL del webhook sull'app è solo metà del cablaggio. Ogni WhatsApp Business Account (WABA) deve poi sottoscriversi separatamente a quell'app perché i suoi messaggi vengano instradati al tuo endpoint. L'App Dashboard non mostra questa sottoscrizione da nessuna parte, e la UI del webhook ti lascia finire il setup senza WABA collegata. Meta chiama questo problema shadow delivery, e la soluzione è una chiamata API che la procedura guidata di setup non menziona.

Prima controlla:

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

Se l'array data è vuoto o non contiene l'ID della tua app, questo è il tuo problema.

La soluzione:

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

La chiamata restituisce {"success": true} e il messaggio entrante successivo arriva al webhook di Hermes Agent in pochi secondi. Non serve riavviare il gateway. Se in seguito ruoti l'access token, riesegui questa chiamata: la sottoscrizione è legata all'app ma la scrittura richiede un token con il permesso whatsapp_business_management.

Causa 3: stai ancora usando il token temporaneo da 24 ore

Il token che Meta mostra nella schermata di setup di WhatsApp scade in esattamente 24 ore. Se l'hai copiato nel .env di Hermes Agent martedì pomeriggio e il bot è ammutolito mercoledì pomeriggio, è per questo.

Sintomo: il tuo gateway logga OAuthException o HTTP 401 sul prossimo invio in uscita dopo la scadenza. Le chiamate di webhook entranti da Meta possono continuare ad arrivare (non hanno bisogno del tuo token), ma ogni risposta che Hermes tenta di pubblicare indietro fallisce, quindi il bot riceve il tuo messaggio, genera una risposta e la perde per strada.

La soluzione è un token permanente di System User, non un token temporaneo più lungo:

In Meta Business Suite apri Users poi System Users e crea un nuovo System User con il ruolo Admin.
Assegna la tua app WhatsApp e il tuo WhatsApp Business Account a quel System User con Full control.
Clicca Generate new token, scegli la tua app, e spunta sia whatsapp_business_messaging (serve per inviare) sia whatsapp_business_management (serve per la chiamata subscribed_apps della Causa 2).
Imposta la scadenza su Never. Copia il token, mettilo in WHATSAPP_ACCESS_TOKEN, riavvia il gateway.

Controlla prima di andartene:

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

Deve restituire l'ID e il nome del tuo System User, non un errore OAuth.

Causa 4: stai inviando al Phone Number ID sbagliato

La Cloud API di WhatsApp usa tre ID e sono tutti facili da confondere: il numero di telefono in sé, il Phone Number ID e il WABA ID. Hermes Agent ha bisogno del Phone Number ID, non del numero. Se hai messo il numero di telefono in WHATSAPP_PHONE_NUMBER_ID, ogni chiamata in uscita restituisce Object with ID '+39...' does not exist e ogni chiamata in ingresso arriva ma non ha percorso di risposta.

Per confondere le cose, il Phone Number ID è un numero di 15 o 16 cifre che assomiglia molto a un telefono. Non lo è.

Dove trovarlo: nell'App Dashboard, apri WhatsApp poi API Setup. Il dropdown From elenca i tuoi numeri registrati. Sotto ogni numero, in piccolo, c'è un campo chiamato Phone number ID. Quel valore è quello che serve a Hermes Agent.

Verifica che il valore che hai sia reale:

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

Un ID valido restituisce display_phone_number, verified_name e quality_rating. Un ID sbagliato restituisce un errore del Graph API il cui messaggio nomina l'ID che non è riuscito a trovare.

Già che ci sei, controlla la variabile WHATSAPP_BUSINESS_ACCOUNT_ID: è un ID separato per la WABA proprietaria del numero, usato dalla chiamata di sottoscrizione della Causa 2, ed è facilissimo scambiare i due quando li copi dal dashboard.

Due trappole extra da escludere

Se le quattro cause di sopra sono pulite e i messaggi ancora non scorrono, controlla queste in sequenza:

L'app è bloccata in modalità Dev. WhatsApp consegna webhook solo per messaggi che il proprietario dell'app ha inviato o ricevuto nelle ultime 24 ore, e solo da numeri aggiunti esplicitamente in WhatsApp poi API Setup poi To. Passa l'app su Live in App Review quando sei pronto per traffico reale.
Il campo webhook messages non è sottoscritto. In WhatsApp poi Configuration, guarda la sezione Webhook fields e conferma che messages abbia una spunta verde. Meta ti lascia salvare un URL webhook senza campi sottoscritti, e silenziosamente non consegna nulla.

Ordine di diagnosi che fa risparmiare tempo

Quando il bot ammutolisce, attraversa le cause in questo ordine invece di reinstallare tutto:

Sei sul percorso QR? Se sì, migra alla Cloud API prima di spendere un altro minuto su qualcosa d'altro. Shortcake non se ne va.
La tua WABA è sottoscritta alla tua app? L'unica chiamata curl di sopra risponde in tre secondi. Il tasso di successo più alto sui deploy Cloud API.
Controlla il token. curl /me fallisce all'istante se il token è morto, sbagliato o senza scope.
Verifica il Phone Number ID. curl /$PHONE_NUMBER_ID restituisce i campi del numero quando è valido.
Controlla la modalità Dev e i campi sottoscritti. Più lento da ispezionare, meno comune come causa radice, ma vale escluderlo prima di aprire un ticket con Meta.

Per il percorso completo di prima installazione, guarda la guida al deploy di Hermes Agent su WhatsApp. Se Telegram può andar bene per il tuo caso d'uso, il confronto Telegram vs WhatsApp attraversa i tradeoff prima che ti impegni.

Quando preferisci non combattere con Meta ogni settimana

Meta rilascia cambiamenti alla UI del webhook, stringe la verifica e rompe il percorso QR con il suo ritmo. Se la tua lettura è che un agente IA personale non dovrebbe richiedere un account Business Manager e un token System User per rispondere ciao, inizia con Hermify. Hermify esegue un Hermes Agent gestito su Telegram con la stessa memoria e le stesse skill, attivo in circa un minuto, senza la configurazione Meta da tenere d'occhio.