Telegram non ha bisogno di questa configurazione — funziona con semplice long-polling, nessun IP pubblico richiesto. WhatsApp via Twilio richiede un URL pubblico raggiungibile da Internet sulla porta 5010.
Tu (WhatsApp) ──→ Twilio ──→ [URL webhook :5010] ──→ Amira ──→ AI ──→ risposta ──→ Twilio ──→ Te
Twilio riceve il tuo messaggio WhatsApp, lo gira all'addon tramite una richiesta HTTP POST al webhook URL. Amira elabora il messaggio con l'AI e risponde via Twilio.
L'URL https://ha.tuodominio.eu punta all'interfaccia di Home Assistant (porta 443), non all'addon Amira. L'ingress di HA smista le richieste agli addon solo tramite un token speciale (/api/hassio_ingress/<token>/...) che Twilio non conosce.
Amira ascolta direttamente sulla porta 5010. L'URL corretto è:
http://ha.tuodominio.eu:5010/api/whatsapp/webhook
oppure con HTTPS (se il tuo reverse proxy gestisce la 5010 con SSL):
https://ha.tuodominio.eu:5010/api/whatsapp/webhook
| Requisito | Dove ottenerlo |
|---|---|
| Account Twilio (gratuito per il Sandbox) | twilio.com |
| Account SID | Console Twilio → home |
| Auth Token | Console Twilio → home |
Numero WhatsApp Sandbox (+1 415 523 8886) |
Console → Messaging → Try it out → Send a WhatsApp message |
| Porta 5010 aperta sul router/firewall verso HA | Vedi Step 2 |
Nella configurazione dell'addon Amira, imposta:
twilio_account_sid: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # inizia con "AC"
twilio_auth_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio_whatsapp_from: +14155238886 # Sandbox TwilioIl numero
twilio_whatsapp_fromè il numero mittente Twilio, non il tuo numero personale. Per il Sandbox è sempre+14155238886.
Salva e riavvia l'addon.
Amira espone l'API sulla porta 5010 dell'host Home Assistant. Twilio deve poter raggiungere questa porta da Internet.
- Accedi al pannello del tuo router
- Aggiungi una regola Port Forwarding:
- Porta esterna:
5010 - Porta interna:
5010 - Protocollo:
TCP - IP destinazione: l'IP locale di Home Assistant (es.
192.168.1.100)
- Porta esterna:
- Salva
Dal telefono con WiFi spento (rete mobile), o da una rete esterna:
curl http://TUO_IP_PUBBLICO:5010/api/statusDovresti ricevere un JSON con lo stato dell'addon. Se ottieni timeout o connessione rifiutata, la porta non è aperta.
Se preferisci non esporre la porta 5010, puoi configurare Nginx per girare solo il path del webhook:
server {
listen 443 ssl;
server_name ha.tuodominio.eu;
# ... certificato SSL ...
location /api/whatsapp/webhook {
proxy_pass http://127.0.0.1:5010/api/whatsapp/webhook;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Host $host;
proxy_read_timeout 60s;
}
}Con questa configurazione puoi usare https://ha.tuodominio.eu/api/whatsapp/webhook (porta 443, senza esporre la 5010).
-
Vai su console.twilio.com
-
Menu sinistro → Messaging → Try it out → Send a WhatsApp message
-
Tab "Sandbox settings"
-
Campo "When a message comes in": inserisci l'URL completo:
Scenario URL da inserire Porta 5010 diretta http://ha.tuodominio.eu:5010/api/whatsapp/webhookNginx proxy su 443 https://ha.tuodominio.eu/api/whatsapp/webhookngrok (test) https://abc123.ngrok-free.app/api/whatsapp/webhook -
Metodo: HTTP POST
-
Clicca Save
- Menu sinistro → Messaging → Senders → WhatsApp senders
- Clicca sul tuo numero → sezione "A message comes in"
- Inserisci l'URL del webhook e metodo HTTP POST
- Salva
Per ricevere messaggi dal Sandbox Twilio, ogni utente deve prima "unirsi":
- Apri WhatsApp
- Manda un messaggio al numero +1 415 523 8886
- Testo: il codice che vedi nella tua console Twilio (es.
join subject-parts) - Twilio risponde confermando — da quel momento ricevi le risposte di Amira
Il codice di join è in: Console → Messaging → Try it out → Send a WhatsApp message → tab "Sandbox"
Manda un messaggio WhatsApp al numero Twilio. Controlla i log dell'addon:
Settings → Add-ons → Amira → Log
Messaggi da cercare:
✅ WhatsApp bot initialized→ credenziali trovateWhatsApp message from +39...→ webhook funzionante, messaggio ricevutoWhatsApp webhook signature invalid→ problema URL (vedi troubleshooting)WhatsApp not configured→ credenziali mancanti
Stai navigando sull'ingress di Home Assistant (porta 443), non su Amira (porta 5010).
→ Usa http://ha.tuodominio.eu:5010/api/whatsapp/webhook
La porta 5010 non è raggiungibile da Internet. → Verifica il Port Forwarding sul router e che il firewall del server la consenta.
Amira tenta automaticamente più varianti dell'URL. Se persiste, l'URL nel campo webhook Twilio deve essere identico all'URL pubblico effettivamente raggiunto. Controlla nei log:
WhatsApp webhook signature invalid (url tried: 'http://...:5010/api/whatsapp/webhook')
Il webhook non è configurato su Twilio, o l'URL non include il path /api/whatsapp/webhook.
Credenziali mancanti. Verifica che twilio_account_sid inizi con AC, che twilio_auth_token sia corretto e che tu abbia riavviato l'addon dopo aver salvato.
La sessione Sandbox Twilio scade dopo 24 ore di inattività. Manda di nuovo il codice di join.
| Sandbox (gratuito) | Numero acquistato | |
|---|---|---|
| Costo | Gratuito | ~$15/mese + messaggi |
| Setup | Solo join code | Approvazione WhatsApp Business |
| Utenti | Max ~5 (devono fare join) | Illimitati |
| Numero | Condiviso (+1 415 523 8886) |
Dedicato |
| Adatto per | Test e sviluppo | Produzione |
Guida aggiornata per Amira v4.x — per problemi apri una issue su GitHub