ITA – SMS REST API / Protocollo HTTP (Universal mode)

OVERVIEW #

Questa pagina mostra alcuni esempi pratici di utilizzo dell’API SMS di Agile Telecom e spiega come usare la Postman Collection collegata a questa documentazione.

Scarica la Postman Collection SMS Universal qui

---

Informazioni di base #

Endpoint principale #

Tutti gli esempi di questa pagina usano il seguente endpoint per l’invio di SMS:

POST {{BASE_URL}}/api/message-server/sms/send

Dove:

Parametro	Tipo	Descrizione
{{BASE_URL}}	string	URL base dell’API, ad esempio https://lora-api.agiletelecom.com.

Header richiesti #

Header	Obbligatorio	Descrizione
Content-Type: application/json	Sì	Indica che il corpo della richiesta è in formato JSON.
X-Api-Key: {{API_KEY}}	Sì	Chiave API generata dall’interfaccia web e associata alla tua utenza di invio.

Variabili consigliate (Postman / ambiente) #

Per semplificare l’uso della collection, si consiglia di definire le seguenti variabili (a livello di collection o environment in Postman):

Nome variabile	Esempio	Descrizione
BASE_URL	https://lora-api.agiletelecom.com	URL base dell’API SMS.
API_KEY	ak_live_********************************	Chiave API generata dal portale Agile Telecom.
DESTINATION	+393471234567	Numero di telefono del destinatario in formato internazionale.
SENDER	MyCompany	Sender alfanumerico (max 11 caratteri) o numerico, registrato sul portale.
SCHEDULED_DATE	2025-10-30 18:50:00.000+0000	Data/ora per gli esempi di invio schedulato.
MESSAGE_ID	550e8400-e29b-41d4-a716-446655440000	Identificativo univoco del messaggio (opzionale, se non indicato lo genera il sistema).

Nota: nei comandi curl e negli esempi JSON, i valori racchiusi tra {{...}} si riferiscono a variabili configurate in Postman o nell’applicazione.

---

Esempi di invio SMS #

Invio SMS base #

Esempio di invio di un SMS semplice.

Esempio cURL #

curl --location '{{BASE_URL}}/api/message-server/sms/send' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: {{API_KEY}}' \
  --data '{
    "destination": "{{DESTINATION}}",
    "sender": "{{SENDER}}",
    "body": "Messaggio di test dalla SMS API di Agile Telecom"
  }'

Body JSON della richiesta #

{
  "destination": "{{DESTINATION}}",
  "sender": "{{SENDER}}",
  "body": "Messaggio di test dalla SMS API di Agile Telecom"
}

Esempio di risposta #

In caso di successo, l’API restituisce un codice HTTP 202 Accepted e un JSON simile al seguente:

{
  "messageId": "9b3dfde1-7ee6-411f-8f56-6cb18106e0cc",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1
    }
  }
}

Significato dei campi principali:

• messageId: identificativo univoco del messaggio (usato anche nei callback di delivery).
• simulation: false indica che l’invio è reale; true indica una simulazione.
• results.sms.accepted: se true, il messaggio è stato accettato dal sistema per la messa in invio.
• results.sms.unicode: indica se il testo è stato codificato come Unicode.
• results.sms.parts: numero di parti in cui è stato suddiviso il messaggio (se > 1 si tratta di un SMS multipart).

Invio SMS in simulazione #

Usare il campo simulation per verificare che tutto funzioni, senza inviare realmente l’SMS.

Body JSON della richiesta #

{
  "destination": "{{DESTINATION}}",
  "sender": "{{SENDER}}",
  "body": "Questo SMS non verrà inviato, è solo una simulazione.",
  "simulation": true
}

Esempio di risposta #

{
  "messageId": "3a82f7cb-5fa1-4d6c-9c1f-1f5b3fa76a10",
  "simulation": true,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1
    }
  }
}

Anche in simulazione il sistema esegue tutti i controlli, ma l’SMS non viene inviato alla rete.

Invio SMS schedulato #

Usare il campo simulation per verificare che tutto funzioni, senza inviare realmente l’SMS.

Body JSON della richiesta #

{
  "destination": "{{DESTINATION}}",
  "sender": "{{SENDER}}",
  "body": "Questo SMS non verrà inviato, è solo una simulazione.",
  "simulation": true
}

Esempio di risposta #

{
  "messageId": "3a82f7cb-5fa1-4d6c-9c1f-1f5b3fa76a10",
  "simulation": true,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1
    }
  }
}

Anche in simulazione il sistema esegue tutti i controlli, ma l’SMS non viene inviato alla rete.

Invio SMS schedulato #

È possibile programmare l’invio in una data futura usando il campo scheduledDate.

Body JSON della richiesta #

{
  "destination": "{{DESTINATION}}",
  "sender": "{{SENDER}}",
  "body": "Questo SMS verrà inviato in futuro.",
  "messageId": "{{MESSAGE_ID}}",
  "scheduledDate": "{{SCHEDULED_DATE}}",
  "enableNotification": true
}

enableNotification indica se applicare le impostazioni di delivery configurate nel sistema (ad esempio callback HTTP).

Esempio di risposta #

{
  "messageId": "{{MESSAGE_ID}}",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1
    }
  }
}

Invio SMS con placeholder #

I placeholder permettono di inserire variabili nel corpo del messaggio. Il testo conterrà marcatori tra parentesi graffe, sostituiti in base al campo placeholders.

Body JSON della richiesta #

{
  "destination": "{{DESTINATION}}",
  "sender": "{{SENDER}}",
  "body": "Ciao {name}, il tuo codice è {code}.",
  "placeholders": {
    "name": "Luigi",
    "code": "123456"
  }
}

Il messaggio inviato al destinatario sarà: “Ciao Luigi, il tuo codice è 123456.”

Invio SMS con UDH (User Data Header) #

Il campo udhData permette di inviare dati speciali UDH insieme all’SMS (ad es. per funzionalità avanzate o casi specifici).

Body JSON della richiesta #

{
  "destination": "{{DESTINATION}}",
  "sender": "{{SENDER}}",
  "body": "Messaggio con UDH personalizzato",
  "udhData": "050003CC0201"
}

---

Callback di delivery (webhook) #

Quando sono configurate le notifiche di delivery, il sistema invia una richiesta HTTP al tuo endpoint con il risultato finale di consegna.

Endpoint di esempio #

POST https://www.yoururl.com/delivery/sms
Sostituisci l’URL con il tuo endpoint reale, ad esempio: POST https://api.miodominio.it/agiletelecom/delivery/sms.

Payload di esempio – messaggio consegnato (DELIVERED) #

{
  "channel": "SMS",
  "eventType": "DELIVERY",
  "messageId": "813d4183-8d15-4aa3-a820-8d16a435bf77",
  "destination": "+393401234567",
  "statusCode": 3,
  "description": "delivered",
  "eventDate": "2025-11-24T16:10:21Z",
  "price": 0.075,
  "numPart": 1,
  "totalParts": 2
}

Payload di esempio – messaggio non consegnabile (UNDELIVERABLE) #

{
  "channel": "SMS",
  "eventType": "DELIVERY",
  "messageId": "813d4183-8d15-4aa3-a820-8d16a435bf77",
  "destination": "+393401234567",
  "statusCode": 6,
  "description": "Undeliverable",
  "eventDate": "2025-11-24T16:10:21Z",
  "price": 0.075,
  "numPart": 1,
  "totalParts": 1
}

Significato dei campi principali:

• channel: per gli SMS è sempre "SMS".
• eventType: per i delivery SMS è sempre "DELIVERY".
• messageId: stesso ID restituito in fase di invio.
• destination: numero di telefono del destinatario.
• statusCode: codice numerico che descrive lo stato (vedi tabella più sotto).
• description: descrizione testuale dello stato.
• eventDate: data/ora in cui si è verificato l’evento di delivery.
• price: prezzo associato al messaggio.
• numPart: numero della parte del messaggio a cui è associato il delivery.
• totalParts: numero totale di parti da cui è composto il messaggio.

---

Codici di errore in fase di invio #

In caso di problemi durante la richiesta di invio, l’API può restituire codici di errore specifici (oltre al codice HTTP).

Codice	Descrizione
8	Server error
26	Alias (Sender) non autorizzato
100	Source IP is not allowed

Suggerimento: in presenza di questi errori, verificare la configurazione del sender, l’indirizzo IP sorgente e, se necessario, contattare il supporto Agile Telecom.

---

Codici di stato delivery #

I seguenti codici vengono usati nel campo statusCode del payload di delivery:

statusCode	Stato	Descrizione
1	Accepted	Messaggio accettato dal sistema, in attesa di elaborazione o invio.
2	Rejected	Messaggio rifiutato prima dell’invio (es. validazione fallita, restrizioni, ecc.).
3	Delivered	Messaggio correttamente consegnato al dispositivo del destinatario.
4	Expired	Messaggio non consegnato entro la finestra di validità (scaduto).
5	Deleted	Messaggio cancellato prima della consegna (ad esempio su richiesta o per policy).
6	Undeliverable	Messaggio non consegnabile in modo definitivo (es. numero inesistente).

---

Note importanti sull’uso degli SMS #

• Formato numeri: i numeri di destinazione devono essere in formato internazionale con prefisso paese (es. +39 per l’Italia).
• Limiti di lunghezza SMS:
  • SMS standard (GSM 7-bit): 160 caratteri per parte.
  • SMS Unicode: 70 caratteri per parte.
  • Se il testo supera questi limiti, il messaggio viene automaticamente suddiviso in più parti (multipart).
• Mittente (sender):
  • Alfanumerico: massimo 11 caratteri.
  • Numerico: massimo 16 cifre.
  • Il sender va registrato tramite l’interfaccia web prima dell’utilizzo.
• Encoding: il corpo del messaggio può essere inviato in UTF-8; il sistema si occupa di codificarlo in GSM o Unicode dove necessario.
• Rate limiting: verificare con Agile Telecom eventuali limiti di invio per secondo/minuto.

---

Come usare la Postman Collection #

Importare la collection #

1. Scarica il file JSON della Postman Collection (link in alto in questa pagina).
2. Apri Postman.
3. Clicca su Import in alto a sinistra.
4. Trascina il file JSON nella finestra oppure clicca su Upload Files e seleziona il file.
5. Conferma l’importazione.

Configurare le variabili #

1. Nel pannello laterale, clicca sul nome della collection (es. Agile Telecom SMS API).
2. Apri la tab Variables.
3. Imposta almeno:
   • BASE_URL
   • API_KEY
   • DESTINATION
   • SENDER
   • SCHEDULED_DATE (per gli esempi di schedulazione)
4. Salva le modifiche cliccando su Save.

Eseguire una chiamata di test #

1. Nella collection, apri la cartella Send SMS.
2. Seleziona la richiesta Send basic SMS.
3. Verifica il body JSON (tab Body) e controlla che contenga destination, sender e body.
4. Clicca su Send.
5. Controlla la risposta nel pannello Response e annota il valore di messageId.

Testare le callback di delivery #

1. Prepara un endpoint HTTP pubblico in grado di ricevere POST con JSON.
2. Configura nel portale Agile Telecom l’URL dell’endpoint come URL di delivery.
3. Nella collection, usa le richieste di simulazione delivery (se presenti) per inviare esempi di payload al tuo endpoint.
4. Verifica nei log del tuo sistema che il payload ricevuto corrisponda agli esempi in questa pagina.

Generazione del codice da Postman #

Postman permette di generare automaticamente il codice per diversi linguaggi (cURL, Python, JavaScript, PHP, ecc.).

1. Apri una richiesta (ad esempio Send basic SMS).
2. Clicca sull’icona <> Code nella parte destra della finestra.
3. Seleziona il linguaggio desiderato (cURL, Python, JavaScript, …).
4. Copia il codice generato e usalo come base per la tua integrazione.