API REST SMS

L'API REST SMS ti consente di inviare messaggi di testo a qualsiasi numero mobile in tutto il mondo attraverso un singolo endpoint HTTPS. Gestisce automaticamente codifica, splitting multipart e tracciamento della consegna — tu fornisci la destinazione, l'ID mittente e il corpo del messaggio.

Scarica la Postman Collection SMS Universal.

Avvio Rapido

Il modo più veloce per inviare un SMS: fai una richiesta POST con la tua API key, il numero di destinazione, il mittente e il testo del messaggio. L'API restituisce un messageId che puoi usare per tracciare la consegna.

URL Base

https://lora-api.agiletelecom.com

Autenticazione

Ogni richiesta richiede un'API key passata nell'header X-Api-Key. Genera la tua key dal portale Agile Telecom in Impostazioni > API Keys.

Header	Obbligatorio	Descrizione
`Content-Type`	Sì	Deve essere `application/json`
`X-Api-Key`	Sì	La tua API key dal portale

Variabili d'Ambiente

Queste variabili sono usate negli esempi. Sostituiscile con i tuoi valori effettivi.

Variabile	Esempio	Descrizione
`BASE_URL`	`https://lora-api.agiletelecom.com`	URL base dell'API
`API_KEY`	`ak_live_*****`	La tua API key
`DESTINATION`	`+393471234567`	Numero del destinatario in formato internazionale (con prefisso paese)
`SENDER`	`MyCompany`	Alfanumerico (max 11 caratteri) o numerico (max 16 cifre), registrato nel portale

Invia un SMS

Invia un singolo messaggio di testo a un numero di telefono. Questa è l'operazione più comune — copre il 90% dei casi di integrazione.

Endpoint: POST /api/message-server/sms/send

curl -X POST https://lora-api.agiletelecom.com/api/message-server/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "sender": "MyCompany",
    "body": "Hello from Agile Telecom SMS API!"
  }'

import requests

response = requests.post(
    "https://lora-api.agiletelecom.com/api/message-server/sms/send",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json={
        "destination": "+393471234567",
        "sender": "MyCompany",
        "body": "Hello from Agile Telecom SMS API!"
    }
)

data = response.json()
print(f"Message ID: {data['messageId']}")
print(f"Parts: {data['results']['sms']['parts']}")

const response = await fetch(
  "https://lora-api.agiletelecom.com/api/message-server/sms/send",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "YOUR_API_KEY"
    },
    body: JSON.stringify({
      destination: "+393471234567",
      sender: "MyCompany",
      body: "Hello from Agile Telecom SMS API!"
    })
  }
);

const data = await response.json();
console.log(`Message ID: ${data.messageId}`);
console.log(`Parts: ${data.results.sms.parts}`);

$ch = curl_init("https://lora-api.agiletelecom.com/api/message-server/sms/send");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-Api-Key: YOUR_API_KEY"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "destination" => "+393471234567",
        "sender" => "MyCompany",
        "body" => "Hello from Agile Telecom SMS API!"
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Message ID: " . $data["messageId"] . "\n";
echo "Parts: " . $data["results"]["sms"]["parts"] . "\n";

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String json = """
    {
        "destination": "+393471234567",
        "sender": "MyCompany",
        "body": "Hello from Agile Telecom SMS API!"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://lora-api.agiletelecom.com/api/message-server/sms/send"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");

var payload = new
{
    destination = "+393471234567",
    sender = "MyCompany",
    body = "Hello from Agile Telecom SMS API!"
};

var content = new StringContent(
    System.Text.Json.JsonSerializer.Serialize(payload),
    System.Text.Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://lora-api.agiletelecom.com/api/message-server/sms/send",
    content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "io"
)

func main() {
    payload, _ := json.Marshal(map[string]string{
        "destination": "+393471234567",
        "sender":      "MyCompany",
        "body":        "Hello from Agile Telecom SMS API!",
    })

    req, _ := http.NewRequest("POST",
        "https://lora-api.agiletelecom.com/api/message-server/sms/send",
        bytes.NewBuffer(payload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", "YOUR_API_KEY")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

require "net/http"
require "json"
require "uri"

uri = URI("https://lora-api.agiletelecom.com/api/message-server/sms/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = "YOUR_API_KEY"
request.body = {
  destination: "+393471234567",
  sender: "MyCompany",
  body: "Hello from Agile Telecom SMS API!"
}.to_json

response = http.request(request)
data = JSON.parse(response.body)
puts "Message ID: #{data['messageId']}"
puts "Parts: #{data['results']['sms']['parts']}"

Risposta

In caso di successo, l'API restituisce HTTP 202 Accepted:

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

Campo	Descrizione
`messageId`	Identificatore univoco per il tracciamento dello stato di consegna tramite webhook
`simulation`	`false` = invio reale, `true` = dry run (nessun SMS inviato)
`results.sms.accepted`	`true` significa che il messaggio è entrato nella pipeline di consegna
`results.sms.unicode`	Se il messaggio richiedeva codifica Unicode (emoji, CJK, arabo, ecc.)
`results.sms.parts`	Numero di parti SMS — i messaggi oltre 160 caratteri (GSM) o 70 caratteri (Unicode) vengono divisi automaticamente

Modalità Simulazione

Testa la tua integrazione senza inviare un vero SMS. L'API convalida tutto — autenticazione, registrazione mittente, codifica messaggio — e restituisce una risposta realistica, ma nulla raggiunge il telefono del destinatario.

Imposta "simulation": true nel corpo della richiesta. Tutti gli altri parametri rimangono uguali.

{
  "destination": "+393471234567",
  "sender": "MyCompany",
  "body": "This SMS will not be sent, it's only a simulation.",
  "simulation": true
}

Quando Usare la Simulazione

Usa la modalità simulazione durante lo sviluppo e il test della pipeline CI/CD. Convalida il tuo payload senza consumare crediti o raggiungere numeri di telefono reali.

Consegna Pianificata

Metti in coda un SMS per una consegna futura. Il messaggio viene archiviato lato server e inviato alla data e ora specificate. Utile per promemoria appuntamenti, campagne marketing e notifiche sensibili al tempo.

Aggiungi scheduledDate in formato ISO 8601 al corpo della richiesta:

{
  "destination": "+393471234567",
  "sender": "MyCompany",
  "body": "Your appointment is tomorrow at 10:00.",
  "scheduledDate": "2025-10-30T18:50:00.000+0000",
  "enableNotification": true
}

Campo	Descrizione
`scheduledDate`	Data/ora di consegna in formato ISO 8601 con offset di fuso orario
`enableNotification`	Imposta su `true` per ricevere callback di consegna per questo messaggio

Fuso Orario

Includi sempre l'offset di fuso orario (es. +0000 per UTC, +0100 per CET). Senza di esso, l'ora pianificata potrebbe essere interpretata in modo errato.

Messaggi Personalizzati con Placeholder

Inserisci valori dinamici nel testo del messaggio. Definisci token placeholder con parentesi graffe nel corpo, poi fornisci i valori di sostituzione nell'oggetto placeholders. Ideale per codici OTP, nomi clienti, numeri d'ordine e notifiche personalizzate.

{
  "destination": "+393471234567",
  "sender": "MyCompany",
  "body": "Hello {name}, your code is {code}.",
  "placeholders": {
    "name": "Luigi",
    "code": "123456"
  }
}

Il destinatario riceve: "Hello Luigi, your code is 123456."

Sintassi Placeholder

I token sono sensibili alle maiuscole: \{Name\} e \{name\} sono placeholder diversi. Assicurati che le chiavi in placeholders corrispondano esattamente ai token in body.

ID Messaggio Personalizzato

Per impostazione predefinita, il sistema genera un UUID per ogni messaggio. Se hai bisogno di correlare i messaggi con i tuoi record interni, passa il tuo messageId:

{
  "destination": "+393471234567",
  "sender": "MyCompany",
  "body": "Order #12345 has been shipped.",
  "messageId": "550e8400-e29b-41d4-a716-446655440000"
}

Lo stesso ID comparirà nei callback di consegna, consentendoti di abbinare lo stato di consegna ai tuoi record.

UDH (User Data Header)

Per casi d'uso avanzati come WAP Push, Flash SMS o concatenazione personalizzata, puoi includere dati UDH grezzi in formato esadecimale:

{
  "destination": "+393471234567",
  "sender": "MyCompany",
  "body": "Message with custom UDH",
  "udhData": "050003CC0201"
}

Funzione Avanzata

UDH è destinato agli sviluppatori che hanno bisogno di controllo di basso livello sui header PDU SMS. La maggior parte delle integrazioni non ha bisogno di questo — l'API gestisce la concatenazione automaticamente.

Callback di Consegna (Webhook)

Quando configuri un URL di consegna nel portale Agile Telecom, il sistema invia un HTTP POST al tuo endpoint ogni volta che uno stato del messaggio cambia. Questo ti consente di tracciare se ogni SMS è stato effettivamente consegnato al dispositivo del destinatario.

Payload Webhook

Il tuo endpoint riceve un payload JSON come questo:

Consegnato con successo:

{
  "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
}

Non consegnabile:

{
  "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
}

Campi Webhook

Campo	Descrizione
`channel`	Sempre `"SMS"` per questa API
`eventType`	Sempre `"DELIVERY"` — attivato quando il carrier conferma lo stato finale
`messageId`	Corrisponde all'ID restituito quando hai inviato il messaggio
`destination`	Numero di telefono del destinatario
`statusCode`	Stato di consegna numerico (vedi tabella sottostante)
`description`	Etichetta di stato leggibile dall'uomo
`eventDate`	Timestamp ISO 8601 dell'evento di consegna
`price`	Costo addebitato per questa parte del messaggio
`numPart`	Numero della parte (per SMS multipart)
`totalParts`	Parti totali nel messaggio

Codici di Stato di Consegna

Codice	Stato	Cosa Significa
1	Accettato	Il messaggio è entrato nella pipeline di consegna, in attesa di essere inviato
2	Rifiutato	La validazione ha fallito prima dell'invio (mittente non valido, destinazione limitata, ecc.)
3	Consegnato	Confermato consegnato al dispositivo del destinatario
4	Scaduto	La finestra di consegna è trascorsa — il telefono potrebbe essere stato spento o non raggiungibile
5	Eliminato	Messaggio rimosso prima della consegna (per policy o su richiesta)
6	Non Consegnabile	Fallimento permanente — il numero non esiste, errore di rete, ecc.

Codici di Errore

Se l'API rifiuta la tua richiesta, restituisce uno di questi codici di errore insieme a uno stato HTTP di errore:

Codice	Significato	Cosa Verificare
8	Errore del server	Riprova dopo un breve ritardo; contatta il supporto se persistente
26	Mittente non autorizzato	Registra l'alias del mittente nel portale prima di usarlo
100	IP non consentito	L'IP del tuo server deve essere whitelistato — contatta il supporto

Riferimento Codifica SMS

Codifica	Max Caratteri per Parte	Quando Usata
GSM 7-bit	160	Caratteri latino standard, cifre, simboli comuni
Unicode (UCS-2)	70	Emoji, cinese/giapponese/coreano, arabo, cirillico, ecc.
GSM Multipart	153 per parte	Messaggi GSM oltre 160 caratteri (7 caratteri per parte riservati per UDH)
Unicode Multipart	67 per parte	Messaggi Unicode oltre 70 caratteri

L'API rileva automaticamente la codifica in base al contenuto del tuo messaggio. Non hai bisogno di specificarla.

Regole ID Mittente

Mittente alfanumerico: max 11 caratteri (lettere, cifre, spazi). Deve essere pre-registrato nel portale.
Mittente numerico: max 16 cifre. Utile per SMS bidirezionale dove i destinatari possono rispondere.

Postman Collection

La Postman Collection contiene richieste pre-configurate per ogni esempio su questa pagina. Importala e imposta le tue variabili per iniziare a testare in secondi.

Scarica la collection
Importa in Postman via File > Import
Imposta BASE_URL, API_KEY, DESTINATION e SENDER nelle variabili della collection
Esegui qualsiasi richiesta — controlla la risposta per messageId e accepted: true

Generazione Codice

Postman può generare snippet di codice in 15+ linguaggi. Apri qualsiasi richiesta, fai clic sull'icona Code (</>) a destra, e seleziona il tuo linguaggio.

Supporto

Per assistenza tecnica, contatta help@agiletelecom.com.

Qual è il Prossimo?

API REST SMS (Legacy) — endpoint HTTP più vecchio, compatibile con integrazioni esistenti
Protocollo SMPP — protocollo binario per invio ad alto throughput
SMS in Ingresso — ricevi messaggi sul tuo numero dedicato

Avvio Rapido​

URL Base​

Autenticazione​

Variabili d'Ambiente​

Invia un SMS​

Risposta​

Modalità Simulazione​

Consegna Pianificata​

Messaggi Personalizzati con Placeholder​

ID Messaggio Personalizzato​

UDH (User Data Header)​

Callback di Consegna (Webhook)​

Payload Webhook​

Campi Webhook​

Codici di Stato di Consegna​

Codici di Errore​

Riferimento Codifica SMS​

Postman Collection​

Supporto​

Qual è il Prossimo?​