API REST SMS (Legacy)

Invia SMS ai tuoi clienti con un'API REST semplice e affidabile. Questo endpoint legacy supporta tutte le funzionalità di messaggistica di cui hai bisogno — dai testi di base agli invii pianificati, messaggi concatenati e broadcast in massa.

Aggiornamento di Sicurezza

A partire dal 15 gennaio 2026, le connessioni HTTP sono accettate solo su TLS (HTTPS). Le connessioni non-TLS saranno rifiutate. Le richieste GET e le richieste POST con form-encoded non saranno più accettate — solo POST con payload JSON su HTTPS è supportato.

URL Base

Scegli l'endpoint in base al tipo di account:

Clienti legacy:

https://secure.agiletelecom.com/services/

Nuovi clienti:

https://http-api.agiletelecom.com/services/

Autenticazione

Aggiungi uno di questi metodi di autenticazione agli header della tua richiesta:

Autenticazione di Base

Authorization: Basic <base64_encoded_credentials>

API Key (Consigliato)

X-Api-Key: YOUR_API_KEY

Invia SMS

Invia messaggi SMS a uno o più destinatari in una singola chiamata API.

Endpoint

POST /sms/send

Header Obbligatori

Content-Type: application/json

Corpo della Richiesta

{
  "globalId": "string",
  "maxIdLen": 64,
  "enableConcatenated": true,
  "enableUnicode": true,
  "enableDelivery": true,
  "simulation": false,
  "messages": [
    {
      "ids": ["string"],
      "destinations": ["+393351234567"],
      "sender": "string",
      "body": "string",
      "hexBody": false,
      "udhData": "string",
      "scheduling": "2025-12-08 06:00:00.002+0200"
    }
  ]
}

Parametri della Richiesta

Campo	Tipo	Obbligatorio	Default	Descrizione
globalId	stringa	No	--	Identificatore univoco per questa richiesta di invio, utile per il tracciamento e la correlazione di risposte
maxIdLen	intero	No	64	Lunghezza massima (caratteri) degli ID dei messaggi
enableConcatenated	booleano	No	true	Dividi automaticamente i messaggi lunghi in più parti SMS
enableUnicode	booleano	No	true	Supporta caratteri speciali e testo non-ASCII
enableDelivery	booleano	No	true	Ricevi notifiche di consegna tramite webhook
simulation	booleano	No	false	Testa la tua richiesta senza inviare effettivamente messaggi
messages	array	Sì	--	Array di oggetti messaggio da inviare

Parametri del Messaggio

Campo	Tipo	Obbligatorio	Default	Descrizione
destinations	array	Sì	--	Numeri di telefono in formato internazionale (includi prefisso paese)
ids	array	No	--	Identificatori univoci per il tracciamento di ogni messaggio
sender	stringa	Sì	--	ID mittente (alfanumerico max 11 caratteri, o numerico max 16 cifre)
body	stringa	Sì	--	Contenuto del messaggio (testo o HEX se hexBody=true)
hexBody	booleano	No	false	Imposta true se il body è codificato in HEX
udhData	stringa	No	--	User Data Header per formattazione speciale del messaggio
scheduling	stringa	No	--	Ora di consegna in formato "yyyy-MM-dd HH:mm:ss.SSSZ"

Verifica Crediti Account

Verifica il saldo del tuo account rimanente prima di inviare.

Endpoint

GET /sms/credit

Risposta di Successo

{
  "credit": 10.324
}

Formati di Risposta

Risposta di Successo (2XX)

Quando la tua richiesta ha successo, riceverai:

{
  "globalId": "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "processedMessages": 2,
  "processedSmsParts": 4,
  "credit": 10.324
}

Campo	Tipo	Descrizione
globalId	stringa	Echo del tuo ID globale dalla richiesta
processedMessages	intero	Numero di oggetti messaggio accettati
processedSmsParts	intero	Parti SMS totali da inviare (più alte se si verifica concatenazione)
credit	double	Il tuo credito rimanente in EUR

Errori Client (4XX)

Problemi di validazione o autenticazione:

{
  "status": "fail",
  "data": {
    "body": "Missing message body(ies)",
    "number": "Wrong destination number(s)"
  },
  "code": 6
}

Campo	Tipo	Descrizione
status	stringa	Sempre "fail" per risposte 4XX
data	oggetto/stringa	Dettagli su quali campi hanno fallito la validazione
code	intero	Codice di errore (vedi tabella sottostante)

Errori Server (5XX)

Indisponibilità del servizio o timeout:

{
  "status": "error",
  "message": "Number check service unavailable",
  "code": 9
}

Campo	Tipo	Descrizione
status	stringa	Sempre "error" per risposte 5XX
message	stringa	Descrizione di errore leggibile dall'uomo
code	intero	Codice di errore (vedi tabella sottostante)

Codici di Errore

Codice	Descrizione
1	Credenziali errate
2	Crediti insufficienti
3	Numero di destinazione non consentito
4	Errore sconosciuto
5	Numero di destinazione troppo breve
6	Numero di destinazione troppo lungo
7	Numero di destinazione non valido
8	Errore del server
9	Timeout del servizio
10	Lunghezza ID globale errata

Supporto

Per assistenza tecnica, contatta help@agiletelecom.com.

Qual è il Prossimo?

• API REST SMS — endpoint REST moderno con funzionalità avanzate
• Protocollo SMPP — protocollo binario per invio ad alto throughput
• SMS in Ingresso — ricevi messaggi sul tuo numero dedicato