SMS in ingresso
Noleggia un numero dedicato da Agile Telecom e ricevi ogni SMS inviato ad esso — perfetto per customer support bidirezionale, flussi di opt-in/opt-out, conferme di appuntamento e chatbot leggeri.
Per il contratto API completo, vedi il reference Inbound SMS.
Metodi di consegna
Scegli come far arrivare i messaggi quando noleggi il numero:
| Metodo | Adatto a | Latenza |
|---|---|---|
| Webhook (HTTP POST) | Automazione, database, chatbot real-time. | Secondi |
| Casi d'uso a basso volume, flussi manuali, audit. | Tipica delle email |
Puoi cambiare metodo in qualsiasi momento da Numbers → Inbound nel portale wholesale.
Flusso Webhook (consigliato)
La piattaforma invia un POST form-encoded all'URL con i dati del messaggio, e si aspetta esattamente +OK nel body della risposta entro 30 secondi.
Parametri POST inbound
| Parametro | Descrizione | Esempio |
|---|---|---|
originator | Numero del mittente (internazionale) | +393351234567 |
destination | Il tuo numero SIM noleggiato | +393331234333 |
date_time | Timestamp di ricezione YYYYMMDDHHMMSS | 20260514102301 |
text | Body dell'SMS | News ON |
Risposta obbligatoria
+OK
Se il tuo server non risponde con +OK entro 30 secondi, la consegna è considerata fallita e viene ritentata dopo 15 minuti. Dopo 3 tentativi falliti il messaggio viene scartato.
Tieni il webhook veloce: parse, queue, rispondi +OK. Lavori pesanti (NLP, scrittura DB, chiamate ad altri servizi) vanno su worker in background.
Flusso Email
I messaggi inbound arrivano da smsin@agiletelecom.com con oggetto Agile Telecom -- SMS received e un body strutturato con gli stessi campi del payload webhook (From / To / Date/Time / Body). Utile quando:
- Non hai un endpoint HTTPS pubblico.
- Il volume è basso e una revisione manuale è accettabile.
- Vuoi un audit trail del traffico inbound in mailbox.
Pattern comuni
Parole opt-out — Implementa la gestione di STOP / UNSUBSCRIBE nel webhook. Marca il mittente come opted-out nel tuo database e smetti di inviargli campagne. La maggior parte dei paesi lo richiede.
Codici 2FA — Accetta codici di conferma in risposta; il webhook è il canale più affidabile.
Risposte automatiche — Innesca un invio outbound dal webhook handler per confermare ricezione o guidare l'utente.
Checklist di sicurezza
- Solo HTTPS. Rifiuta qualsiasi traffico webhook su HTTP in chiaro.
- Allowlist degli IP di Agile Telecom se il tuo firewall lo supporta. Chiedi la lista aggiornata al supporto.
- Valida
destination— Assicurati che il numero SIM sia tuo; ignora traffico spoofato. - Rate-limita la tua risposta per non essere usato come mittente di spam outbound.
Troubleshooting
| Sintomo | Causa probabile | Fix |
|---|---|---|
| I messaggi vengono ritentati | Il server ha risposto qualcosa di diverso da +OK (o è andato in timeout) | Riduci il lavoro nell'handler, metti su queue async |
| Doppio processing | Stesso messaggio rilanciato dopo un +OK lento | Usa originator + date_time + text come chiave dedup |
| Inbound mancante | Numero non legato al metodo di consegna corretto | Verifica il routing nel portale wholesale |
Prossimi passi
- Reference Inbound SMS API — Contratto completo request/response.
- Best Practice — Compliance opt-out, rate limiting.
- Gestione errori — Pattern di recovery.