SMS — Comanda l'AI via Messaggio di Testo | Easy Understand Hermes Agent

SMS — Comanda l’AI via Messaggio di Testo

Ti ricordi i tempi prima degli smartphone, quando mandare un SMS era il modo più veloce per raggiungere qualcuno? Beh, quel canale classico è ancora vivo e vegeto — e ora è un modo completo per parlare con il tuo assistente AI.

Hermes ora si collega agli SMS tramite Twilio, quindi chiunque abbia un numero di telefono può mandare messaggi al tuo bot e ricevere risposte generate dall’AI. Niente installazioni di app, niente codici QR, niente curve di apprendimento. Solo vecchi e semplici messaggi di testo.

Cosa c’è di Nuovo in Questo Aggiornamento

Il gateway SMS ha ricevuto un serio potenziamento. Ecco cosa è cambiato:

SMS_WEBHOOK_URL è ora obbligatoria — Hermes valida le firme dei webhook di Twilio per tenere fuori gli impostori. Il gateway rifiuterà di avviarsi senza di essa.
Nuove variabili d’ambiente — SMS_WEBHOOK_HOST, SMS_WEBHOOK_PORT, SMS_INSECURE_NO_SIGNATURE e SMS_ALLOW_ALL_USERS ti danno più controllo.
Migliori impostazioni di sicurezza predefinite — Il gateway nega l’accesso a tutti gli utenti per impostazione predefinita. Devi esplicitamente inserire nella whitelist i numeri di telefono.
Divisione dei messaggi più intelligente — Le risposte lunghe vengono ora suddivise in punti naturali (a capo, poi spazi) invece di essere tagliate a metà parola.

Per Iniziare

Per prima cosa, ti servirà un account Twilio e un numero di telefono con capacità SMS. Twilio offre una prova gratuita, quindi puoi testare tutto senza spendere un centesimo.

Ti servirà anche un server accessibile pubblicamente. Twilio invia webhook al tuo server quando qualcuno manda un messaggio al tuo numero. Se stai eseguendo Hermes localmente, strumenti come cloudflared o ngrok possono esporre il tuo localhost su internet.

Installa l’extra SMS con:

cd ~/.hermes/hermes-agent && uv pip install -e ".[sms]"

Passo 1: Recupera le Tue Credenziali Twilio

Vai alla Console Twilio, copia il tuo Account SID e Auth Token dal pannello di controllo, e annota il tuo numero di telefono in formato E.164 (come +15551234567).

Passo 2: Configura Hermes

Il modo più semplice è la procedura guidata interattiva:

hermes gateway setup

Seleziona SMS (Twilio) e segui le istruzioni.

Preferisci la configurazione manuale? Aggiungi queste righe a ~/.hermes/.env:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

# Sicurezza: limita a numeri di telefono specifici (consigliato)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Opzionale: imposta un canale predefinito per la consegna dei cron job
SMS_HOME_CHANNEL=+15559876543

Passo 3: Configura il Webhook Twilio

Nella Console Twilio, vai su Phone Numbers → Manage → Active Numbers, clicca sul tuo numero e, sotto Messaging → A MESSAGE COMES IN, imposta il webhook su:

https://your-server:8080/webhooks/twilio

Imposta il metodo HTTP su POST.

Importante: Imposta SMS_WEBHOOK_URL sullo stesso identico URL che hai configurato in Twilio. È necessario per la validazione della firma:

SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio

La porta del webhook è impostata su 8080 come predefinita, ma puoi sovrascriverla con SMS_WEBHOOK_PORT.

Passo 4: Avvia il Gateway

hermes gateway

Dovresti vedere qualcosa del tipo:

[sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567

Ora manda un messaggio al tuo numero Twilio — Hermes risponderà via SMS.

Come si Comporta Diversamente l’SMS

L’SMS è un mezzo di solo testo, quindi Hermes si adatta:

Niente Markdown — Viene rimosso automaticamente poiché l’SMS lo renderebbe come caratteri letterali
Limite di 1600 caratteri — Le risposte più lunghe vengono suddivise in più messaggi in punti naturali
Prevenzione dell’eco — I messaggi provenienti dal tuo stesso numero Twilio vengono ignorati per prevenire loop
Privacy — I numeri di telefono vengono oscurati nei log

La Sicurezza è Importante

Hermes valida che i webhook in entrata provengano genuinamente da Twilio controllando l’header X-Twilio-Signature (HMAC-SHA1). Questo blocca gli attaccanti che tentano di iniettare messaggi falsi.

Il gateway nega l’accesso a tutti gli utenti per impostazione predefinita. Devi configurare una whitelist:

SMS_ALLOWED_USERS=+15559876543,+15551112222

Oppure, se ti senti spericolato (per favore non farlo):

SMS_ALLOW_ALL_USERS=true

Per lo sviluppo locale senza un URL pubblico, puoi disabilitare la validazione della firma:

SMS_INSECURE_NO_SIGNATURE=true

Ma ricorda — quello è solo per lo sviluppo locale, mai per la produzione.

Un Ultimo Avvertimento

L’SMS non ha crittografia integrata. Non usarlo per operazioni sensibili. Per qualsiasi cosa riservata, attieniti a Signal o Telegram.

Risoluzione dei Problemi

I messaggi non arrivano? Controlla:

Che il tuo URL del webhook sia corretto e accessibile pubblicamente
Che il tuo TWILIO_ACCOUNT_SID e TWILIO_AUTH_TOKEN siano corretti
La Console Twilio → Monitor → Logs → Messaging per errori di consegna
Che il tuo numero di telefono sia in SMS_ALLOWED_USERS

Tutto qui! Manda un messaggio al tuo bot, ricevi risposte. Semplice così.