Invio SMS

Questa guida copre i fondamentali dell'invio SMS tramite la REST API di Agile Telecom: encoding del testo, sender ID, parti concatenate, schedulazione e invio massivo. Per il reference completo di request/response apri la SMS API sul portale wholesale.

Encoding: GSM-7 vs Unicode (UCS-2)

I messaggi SMS sono codificati in uno di due standard. L'encoding influisce direttamente sul numero di caratteri che entrano in una singola parte.

Encoding	Limite per parte	Parti concatenate (per parte)	Uso tipico
GSM-7	160 caratteri	153 caratteri	Italiano, inglese, alfabeti latini
UCS-2	70 caratteri	67 caratteri	Emoji, arabo, cirillico, cinese, greco

Un singolo carattere non-GSM (es. un'emoji o una vocale accentata fuori dall'extended set) sposta l'intero messaggio su UCS-2 e riduce la lunghezza per parte a 70 caratteri.

Imposta enableUnicode: true per consentire la rilevazione automatica dell'encoding. Imposta enableConcatenated: true per permettere a messaggi più lunghi di una parte di essere divisi e ricomposti sul telefono.

{
  "enableConcatenated": true,
  "enableUnicode": true,
  "messages": [
    {
      "destinations": ["+393351234567"],
      "sender": "Agile",
      "body": "Ciao — il tuo codice è 12345. Rispondi STOP per disiscriverti."
    }
  ]
}

Sender ID

Il campo sender è l'identificativo "from" mostrato sul telefono del destinatario. Due formati accettati:

• Numerico — Short code o numero lungo (solo cifre). Le risposte sono possibili se affitti un numero inbound.
• Alfanumerico — Fino a 11 caratteri, lettere/cifre, senza spazi. Visibile ma non rispondibile. Alcuni paesi richiedono pre-registrazione.

"sender": "Agile"      // alfanumerico (non rispondibile)
"sender": "393351234"  // numerico (rispondibile se possiedi il numero)

Regolamentazioni paese

Sender alfanumerici, parole opt-out e shortcode sono regolamentati per paese. Verifica sempre le regole locali prima di inviare in un nuovo mercato.

SMS Concatenati (Lunghi)

Quando un messaggio supera il limite di una parte, la piattaforma lo divide in più parti e le concatena sul dispositivo via UDH (User Data Header). Ogni parte è fatturata separatamente.

Encoding	1 parte	2 parti	3 parti	4 parti
GSM-7	160	306	459	612
UCS-2	70	134	201	268

Lascia enableConcatenated: true salvo motivi specifici per forzare una singola parte — altrimenti i body lunghi saranno rifiutati.

Schedulazione

Invia il campo scheduling su un messaggio per posticiparne la consegna. Il formato è ISO-like con offset di timezone:

{
  "messages": [
    {
      "destinations": ["+393351234567"],
      "sender": "Agile",
      "body": "Promemoria: appuntamento domani alle 10:00.",
      "scheduling": "2026-05-20 08:30:00.000+0200"
    }
  ]
}

Un messaggio schedulato può essere cancellato prima dell'orario di invio dal portale wholesale o dall'endpoint di cancellazione.

Invio Massivo

Invia a molti destinatari in una sola chiamata API aggiungendo più oggetti all'array messages, o più numeri in destinations.

Stesso body a più numeri

{
  "enableConcatenated": true,
  "enableDelivery": true,
  "messages": [
    {
      "destinations": [
        "+393351234567",
        "+393351234568",
        "+393351234569"
      ],
      "sender": "Agile",
      "body": "Promo primavera: 20% di sconto fino a domenica."
    }
  ]
}

Body personalizzati

{
  "enableConcatenated": true,
  "enableDelivery": true,
  "messages": [
    {
      "destinations": ["+393351234567"],
      "sender": "Agile",
      "body": "Ciao Anna, il tuo codice è 5571."
    },
    {
      "destinations": ["+393351234568"],
      "sender": "Agile",
      "body": "Ciao Marco, il tuo codice è 8843."
    }
  ]
}

Una singola richiesta può portare migliaia di destinazioni. Per volumi molto grandi, preferisci SMPP per throughput sostenuto — vedi il reference SMPP.

Modalità Simulazione

Imposta simulation: true per validare la tua richiesta end-to-end senza inviare realmente e senza consumare credito. La risposta ha forma identica a un invio reale.

{
  "simulation": true,
  "messages": [ ... ]
}

ID di Tracking

Usa il campo ids su un messaggio per associare ID di tracking per destinazione. Vengono restituiti sulla submission e sui delivery report.

{
  "messages": [
    {
      "destinations": ["+393351234567", "+393351234568"],
      "ids": ["ordine_5571_a", "ordine_5571_b"],
      "sender": "Agile",
      "body": "Ordine confermato."
    }
  ]
}

Prossimi passi

• Delivery Report — Traccia lo stato finale in asincrono.
• Best Practice — Throughput, retry, opt-out.
• Gestione errori — Codici di stato e recovery.
• Reference SMS API — Schema completo request/response.