Domande Frequenti
Domande comuni sulla SMS API di Agile Telecom. Per supporto aggiuntivo scrivi a help@agiletelecom.com o apri il portale wholesale.
Autenticazione
Quale metodo di autenticazione devo usare?
L'autenticazione tramite API Key è consigliata per tutte le nuove integrazioni. Includi la tua API key nell'header X-Api-Key:
X-Api-Key: your_api_key_here
Basic Auth è supportato per i client legacy.
Dove trovo la mia API key?
Accedi al portale wholesale e apri Settings → API Keys.
Posso avere più API key?
Sì. Crea key indipendenti per ambiente o servizio. Ogni key è revocabile senza impattare le altre.
- Settings → API Keys
- Generate New Key
- Dai un nome descrittivo e copia subito il valore — non potrai più visualizzarlo.
La mia API key è sensibile?
Sì. Trattala come una password — mai committarla né esporla in codice client. In caso di leak, revoca immediatamente e ruota.
Invio SMS
Differenza tra "accepted" e "delivered"?
- Accepted — La piattaforma ha accettato il messaggio per l'invio. Tipicamente in pochi secondi. Non significa che è arrivato al telefono.
- Delivered — Confermato dall'operatore e/o dal telefono via delivery report. Asincrono, può richiedere più tempo.
Usa sempre i delivery report per confermare la consegna effettiva.
Qual è la lunghezza massima di un messaggio?
Dipende dall'encoding.
| Encoding | 1 parte | Per parte in concatenazione |
|---|---|---|
| GSM-7 | 160 caratteri | 153 caratteri |
| UCS-2 (Unicode) | 70 caratteri | 67 caratteri |
Un solo carattere non-GSM (es. un'emoji) sposta tutto il messaggio su UCS-2. Vedi Invio SMS per la tabella completa.
Posso schedulare un messaggio?
Sì. Usa il campo scheduling sul messaggio con un timestamp ISO-like e offset di timezone (es. 2026-05-20 08:30:00.000+0200). Vedi Invio SMS.
Posso inviare a molti numeri in una sola chiamata?
Sì. Aggiungi più numeri a destinations, o più oggetti message a messages[]. Vedi Invio SMS.
Quali sender ID posso usare?
- Numerico — Short code o numeri lunghi (rispondibili se possiedi il numero).
- Alfanumerico — Fino a 11 caratteri (non rispondibile; in alcuni paesi serve pre-registrazione).
Delivery Report
Come ricevo i delivery report?
Imposta enableDelivery: true sulla send e configura un URL webhook in Settings → Webhooks sul portale wholesale. Vedi Delivery Report.
Cosa deve restituire il mio webhook?
200 OK entro 10 secondi. Qualsiasi altra risposta è trattata come errore e ritentata con back-off esponenziale fino a 24 ore.
Cosa significa ogni stato DLR?
| Stato | Significato |
|---|---|
DELIVERED | Il telefono ha confermato la ricezione |
BUFFERED | In coda sull'operatore, non ancora consegnato |
EXPIRED | Periodo di validità scaduto prima della consegna |
REJECTED | L'operatore ha rifiutato il messaggio |
UNDELIVERABLE | Numero errato, blacklisted, opt-out |
UNKNOWN | Nessuno stato finale ricevuto nella finestra di validità |
FAILED | Errore interno prima della submission |
Reference completo in Delivery Report.
SMS in ingresso
Come ricevo le risposte?
Noleggia un numero dal portale wholesale e bindalo a un URL webhook o email. Vedi SMS in ingresso.
Perché il webhook continua a essere ritentato?
L'endpoint deve rispondere esattamente con +OK (solo body) entro 30 secondi. Qualsiasi altra risposta innesca i retry — fino a 3 tentativi, a 15 minuti di distanza, poi il messaggio è scartato.
Codici di errore
Cosa significano gli status HTTP?
| Codice | Significato | Azione |
|---|---|---|
200 | Accettato (verifica statusCode per messaggio) | Continua, aspetta i DLR |
400 | Bad request | Correggi il payload |
401 | Credenziali non valide | Verifica API key / Basic Auth |
403 | IP non in whitelist | Aggiungi l'IP alla whitelist |
408 | Timeout | Ritenta con back-off |
413 | Payload troppo grande | Suddividi il batch |
429 | Rate limit superato | Back-off esponenziale |
5xx | Errore server | Ritenta con back-off, allerta se persiste |
Mapping completo in Gestione errori.
Come gestisco il rate limiting?
Implementa back-off esponenziale con jitter partendo da 1 secondo. Cap a qualche minuto. Rispetta l'header Retry-After quando presente. Vedi Best Practice.
Network services
Posso verificare il credito prima dell'invio?
Sì. Usa l'API Credit Check — utile prima di campagne grandi.
Posso validare i numeri prima dell'invio?
Sì. Usa il lookup MNP per rilevare numeri invalidi o portati. Riduce gli invii sprecati e migliora i KPI di deliverability.
Compliance
Come gestisco l'opt-out?
Implementa la gestione di STOP / UNSUBSCRIBE sul webhook inbound, persisti l'opt-out per numero e consultalo prima di ogni invio marketing. Vedi Best Practice.
HTTP è ancora supportato?
No — dal 15 gennaio 2026 le connessioni HTTP in chiaro vengono rifiutate. Tutte le chiamate API devono essere su HTTPS (TLS). Le richieste GET e le POST form-encoded non sono più accettate sull'endpoint SMS — solo POST con JSON su HTTPS.
Supporto
- Email: help@agiletelecom.com
- Portale wholesale: wholesale.agiletelecom.com
- Console SMS API: wholesale.agiletelecom.com/services/sms