Come distribuire Hermes Agent su WhatsApp

WhatsApp è l'app di messaggistica che due miliardi di persone aprono ogni giorno, quindi sembra il posto più ovvio dove mettere il tuo agente AI. Poi inizi la configurazione e scopri che è il singolo canale più difficile su cui distribuire un agente personale, e Meta ha passato il 2026 a renderlo ancora più complicato.

Questa guida ti accompagna attraverso ciò che serve davvero per far parlare Hermes Agent su WhatsApp: le credenziali e il webhook di cui hai bisogno, i costi e i limiti che sorprendono la gente, e la risposta onesta alla domanda se dovresti farlo affatto.

Prima di iniziare: WhatsApp non è Telegram

Se hai letto Come distribuire Hermes Agent su Telegram, dimentica la tabella di marcia da cinque minuti. WhatsApp ti offre due vie d'accesso, ed entrambe hanno un trucco:

La WhatsApp Business Cloud API ufficiale (gestita da Meta). Questa è la strada supportata e duratura. Richiede un account Meta Business, la verifica aziendale, un numero di telefono dedicato, un webhook pubblico e la fatturazione per messaggio.
Librerie non ufficiali (WAHA, Baileys e simili) che automatizzano WhatsApp Web. Gratuite e veloci, ma violano i termini di WhatsApp e comportano un rischio reale di ban permanente del numero: ne parliamo più sotto.

Per una distribuzione su cui poter contare, vuoi la Cloud API ufficiale. Tutto ciò che trovi nella sezione di configurazione presuppone questa strada.

Cosa ti serve per distribuire Hermes su WhatsApp

Una distribuzione funzionante ha quattro credenziali e un pezzo di infrastruttura. Raccoglile tutte prima di toccare la configurazione di Hermes.

1. Un account Meta Business e un'app Cloud API

Accedi a Meta for Developers, crea un'app Business e aggiungici il prodotto WhatsApp. Meta ti fornisce subito un numero di test in sandbox così puoi sperimentare prima di verificare un'azienda reale.

2. Un ID del numero di telefono e un WhatsApp Business Account ID

Dentro la configurazione WhatsApp dell'app, registra il numero di telefono aziendale attraverso cui passeranno i messaggi. Meta ti mostra poi due valori che devi salvare: il Phone Number ID e il WhatsApp Business Account (WABA) ID. Questi identificano da quale numero e account invia Hermes: non sono il numero di telefono in sé.

3. Un token di accesso permanente

Il token temporaneo che Meta mostra nella schermata di configurazione scade in 24 ore, il che va bene per un primo test ma è inutile per una distribuzione. Per qualcosa di reale, crea un System User in Business Settings, assegnagli la tua app e il tuo account WhatsApp con il controllo completo, e genera un token permanente. Questa è la credenziale che Hermes usa per autenticare ogni invio.

4. Un endpoint webhook pubblico

Questa è la parte di cui Telegram non ha bisogno. WhatsApp invia i messaggi in arrivo a un URL che ospiti tu, quindi Hermes ha bisogno di un endpoint HTTPS pubblico con un certificato valido. Registri l'URL più un token di verifica a tua scelta in Meta Business Manager, e Meta esegue un handshake una tantum chiamando il tuo endpoint con un valore hub.challenge che devi restituire. Una volta verificato, ogni messaggio in entrata viene consegnato come webhook a cui il tuo gateway deve rispondere con un HTTP 200 entro 30 secondi.

Collegare WhatsApp a Hermes

Con i quattro pezzi in mano, il lato Hermes ti risulterà familiare se hai già configurato il gateway Telegram. In config.yaml, aggiungi il tuo provider e le credenziali di WhatsApp:

provider: openrouter
model: anthropic/claude-3-5-sonnet
openrouter_api_key: sk-or-your-key-here

whatsapp_phone_number_id: "123456789012345"
whatsapp_business_account_id: "987654321098765"
whatsapp_access_token: EAAG...your-permanent-token
whatsapp_verify_token: a-long-random-string-you-choose
whatsapp_allowed_users: "15551234567"

Due campi meritano attenzione. Il whatsapp_verify_token deve corrispondere esattamente al valore che hai digitato in Meta Business Manager quando hai registrato il webhook, altrimenti l'handshake fallisce silenziosamente. Il campo whatsapp_allowed_users è la tua serratura di sicurezza: Hermes risponde solo ai numeri elencati qui (in formato internazionale completo, senza +), così uno sconosciuto che scrive al tuo numero aziendale non può bruciare i crediti del tuo modello.

Avvia il gateway

Avvia il gateway di messaggistica nello stesso modo in cui faresti per qualsiasi canale:

hermes gateway start --detach

Il gateway espone la route del webhook, valida la firma di Meta su ogni richiesta, instrada il corpo del messaggio nel runtime di Hermes e rinvia la risposta dell'agente tramite la Cloud API. Verifica che sia attivo con hermes gateway status e invia un messaggio di prova da un numero autorizzato.

I costi e i limiti che nessuno menziona

È qui che WhatsApp diverge nettamente da una piattaforma di bot gratuita, ed è qui che molte distribuzioni vanno silenziosamente in pezzi.

WhatsApp è passato alla tariffazione per messaggio a metà 2025. Ogni messaggio che il tuo agente avvia viene fatturato per categoria e paese del destinatario, all'incirca da $0,004 a $0,046 per i messaggi di utilità e fino a circa $0,14 per i messaggi di marketing nei paesi a costo più elevato. L'API ufficiale in sé si colloca in una fascia di $0-99/mese prima di queste tariffe per messaggio, e la maggior parte dei team aggiunge in cima un sovrapprezzo del Business Solution Provider.

Ancora peggio, specificamente per un agente, è la finestra di assistenza clienti di 24 ore. Dopo che un utente ti scrive, puoi rispondere liberamente per 24 ore. Una volta che quella finestra si chiude non puoi inviare un messaggio in forma libera: solo un template pre-approvato, e ogni invio di template viene fatturato. Un agente personale è proattivo per natura: ti manda un promemoria con lo standup mattutino, ti dice che un'attività lunga è terminata, ti ricorda una fattura tre giorni dopo. Ognuno di questi cade fuori dalla finestra, quindi su WhatsApp diventa un invio di template a pagamento. Lo analizziamo per intero in Telegram vs WhatsApp per un agente AI.

La scorciatoia non ufficiale (e perché si ritorce contro)

Cerca "bot WhatsApp gratuito" e troverai WAHA, Baileys e una dozzina di wrapper attorno a WhatsApp Web. Sono davvero rapidi da mettere in piedi e non costano nulla in commissioni per messaggio. Sono anche una trappola per qualsiasi distribuzione a cui tieni.

Queste librerie sono frutto di reverse engineering e violano i termini di servizio di WhatsApp. Meta gestisce un sistema di rilevamento a più livelli (fingerprinting di registrazione, analisi comportamentale, segnalazioni degli utenti, pattern di contenuto) e ha inasprito le misure contro i chatbot AI di terze parti nei primi mesi del 2026. L'esito realistico di far girare un gateway non ufficiale self-hosted a qualsiasi volume è un ban permanente del numero che hai usato. Per un test usa e getta su una SIM di scorta, va bene. Per il numero su cui i tuoi contatti ti raggiungono davvero, non ne vale la pena.

Modalità di guasto comuni

Il webhook non si verifica mai. Il token di verifica in config.yaml non corrisponde a quello in Meta Business Manager, oppure il tuo endpoint non è raggiungibile via HTTPS con un certificato valido. Meta deve restituire correttamente hub.challenge prima di inviare anche un solo messaggio.

I messaggi arrivano ma Hermes non risponde mai. O il gateway non è in esecuzione (hermes gateway status) oppure il mittente non è in whatsapp_allowed_users. Controlla che il numero sia in formato internazionale completo senza +.

Il token funziona per un giorno, poi tutto si ferma. Hai effettuato la distribuzione con il token temporaneo di 24 ore invece che con un token permanente di System User. Rigenera quello permanente e aggiorna la tua configurazione.

I messaggi proattivi falliscono silenziosamente. Stai cercando di inviare fuori dalla finestra di 24 ore senza un template approvato. Questa è una regola della piattaforma, non un bug: è il motivo principale per cui gli agenti faticano su WhatsApp. La mentalità diagnostica della guida alla risoluzione dei problemi di Telegram si applica a qualsiasi gateway tu gestisca.

Mantenerlo in funzione

Anche dopo che il bot risponde, ti accolli una responsabilità continua che non esiste sui canali più semplici: un endpoint HTTPS pubblico che deve restare attivo e con certificato valido, un token permanente che non deve trapelare, le approvazioni dei template da gestire e una fattura per messaggio da tenere d'occhio. Il gateway funziona finché il processo e l'endpoint sono in salute, e ammutolisce nel momento in cui uno dei due viene meno. Su un laptop o un container riciclato, succede più spesso di quanto vorresti.

Telegram è la casa migliore per un agente personale

Allontanati dalla meccanica della configurazione e il verdetto è difficile da contestare: per un agente AI personale, Telegram vince su ogni asse che conta.

Aperto e gratuito. La Bot API di Telegram è pubblica, documentata e non costa nulla per messaggio. La Cloud API di WhatsApp è vincolata alla verifica Meta Business e ti fattura per conversazione.
Proattivo di default. Il tuo agente può scriverti nel momento in cui un'attività finisce, ogni mattina, o tre giorni dopo a proposito di una fattura: nessuna finestra di 24 ore, nessun template pre-approvato, nessuna commissione per messaggio.
Attivo in minuti, non settimane. Nessuna verifica aziendale, nessun numero dedicato, nessun webhook pubblico con certificato valido da tenere in vita.
Nessun rischio di ban. Sei su un'API supportata e di prima classe, non su una libreria frutto di reverse engineering a un solo controllo di rilevamento dal perdere il numero.

WhatsApp si può far funzionare se hai davvero bisogno di quello specifico canale e accetti il costo e l'onere operativo. Per tutti gli altri, Telegram è semplicemente il default più sensato.

Salta la configurazione: fai girare il tuo agente su Telegram con Hermify

Hermify è un host gestito per Hermes Agent, e si integra nativamente con Telegram, il canale costruito esattamente per questo tipo di agente personale sempre attivo. Porti una chiave del modello, il runtime esegue il provisioning su infrastruttura gestita, e scrivi al tuo agente come a qualsiasi altro contatto. Nessun server da accudire, nessun webhook da tenere in vita, nessuna fattura per messaggio.

Questo ti dà un agente persistente che si ricorda di te, esegue skill pianificate e vive nella tua tasca: funziona nel momento in cui finisci la registrazione, non dopo una coda di verifica Meta.

Inizia con Hermify e il tuo agente è attivo su Telegram in pochi minuti.