ITA – REST API / Protocollo HTTP

OVERVIEW #

L’API REST di AgileTelecom consente l’invio di SMS attraverso semplici chiamate HTTP. Il servizio supporta funzionalità avanzate come SMS concatenati, Unicode, programmazione temporale e invii multipli.

⚠️ Avviso importante #

A partire dal 15 gennaio 2026, le connessioni HTTP saranno accettate esclusivamente tramite TLS (HTTPS).

Le connessioni senza TLS saranno rifiutate.
Le chiamate GET e le chiamate POST con form-data o Content-Type: application/x-www-form-urlencoded non saranno più valide per l’invio.
Sarà supportato solo POST con payload JSON su connessione HTTPS.

Base URL #

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

Autenticazione #

L’API supporta due metodi di autenticazione, entrambi da includere nell’header della richiesta:

1. Basic Authentication

Authorization: Basic <base64_encoded_credentials>

2. API Key

X-Api-Key: <your-api-key>

Endpoints #

1. Invio SMS

Invia uno o più SMS a destinatari singoli o multipli.

POST /sms/send

Headers richiesti

Content-Type: application/json

Struttura del Body (JSON)

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

Campo	Tipo	Obbligatorio	Default	Descrizione
globalId	string	no	–	Identificativo univoco di invio per il cliente
maxIdLen	integer	no	64	Lunghezza massima (caratteri) degli id
enableConcatenated	boolean	no	true	Abilita i concatenati se necessario
enableUnicode	boolean	no	true	Abilita testo in unicode
enableDelivery	boolean	no	true	Abilita la consegna del delivery al cliente
simulation	boolean	no	false	Consente la simulazione, senza reale invio del messaggio
messages	array	Sì		Elenco dei messaggi da inviare

Parametri per ogni messaggio

Campo	Tipo	Obbligatorio	Default	Descrizione
destinations	array	Sì		Elenco dei destinatari (formato internazionale)
ids	array	no		Elenco degli id relativi ai messaggi
sender	string	Sì		Mittente del messaggio (max 11 caratteri alfanumerici o 16 numerici)
body	string	Sì		Testo del messaggio
hexBody	boolean	no	false	Indica se il testo è in formato HEX
udhData	string	no		Codice UDH da inserire nel messaggio
scheduling	string	no		Data di programmazione (formato: “yyyy-MM-dd HH:mm:ss.SSSZ”)

2. Verifica Credit

Ottieni il credito residuo dell’account.

GET /sms/credit

Risposta di successo (JSON)

{
  "credit": 10.324
}

Esempi di utilizzo #

Esempio 1: SMS Semplice

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "messages": [
      {
        "destinations": ["+393351234567"],
        "sender": "TechNews",
        "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
      }
    ]
  }'

Esempio 2: SMS con ID personalizzato

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
    }
  ]
}

Esempio 3: SMS Multipart (lungo)

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "HealthTips",
      "body": "Stay healthy this summer by following our top tips. Drink plenty of water to stay hydrated, wear sunscreen to protect your skin, and try to include fresh fruits and vegetables in your diet. Regular exercise in the early morning or evening can also help you stay fit and energized."
    }
  ]
}

Esempio 4: SMS Unicode

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-unicode-test1"],
      "destinations": ["+393351234567"],
      "sender": "WeatherNow",
      "body": "Attention: Tomorrow temperatures reaching up to 38°C"
    }
  ]
}

Esempio 5: SMS Programmato

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details.",
      "scheduling": "2025-12-08 06:00:00.002+0200"
    }
  ]
}

Esempio 6: Simulazione (senza invio reale)

{
  "simulation": true,
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
    }
  ]
}

Esempio 7: SMS senza Delivery Report

{
  "enableDelivery": false,
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dasdv"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details."
    }
  ]
}

Esempio 8: SMS con UDH

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dudhx"],
      "destinations": ["+393351234567"],
      "sender": "TechNews",
      "body": "Latest tech news! Discover the new smartphones coming soon and the best deals. Visit our website for more details.",
      "udhData": "070645670000"
    }
  ]
}

Esempio 9: SMS con corpo in HEX

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-unicode-test1"],
      "destinations": ["+393351234567"],
      "sender": "WeatherNow",
      "body": "0041007400740065006E00740069006F006E003A00200054006F006D006F00720072006F0077002000740065006D0070006500720061007400750072006500730020007200650061006300680069006E006700200075007000200074006F00200033003800B00043",
      "hexBody": true
    }
  ]
}

Esempio 10: Invio multiplo – stesso SMS a più destinatari

{
  "messages": [
    {
      "ids": [
        "157d541b-e0cd-4340-ac77-bc5d530dd90e",
        "d0f2e3c1-a043-418d-ad5e-0248184b9833"
      ],
      "destinations": [
        "+393351234567",
        "+393351234568"
      ],
      "sender": "PromoDeals",
      "body": "Don't miss out! Buy 2 products and get the 3rd one free. Offer valid until Sunday."
    }
  ]
}

Esempio 11: Invio multiplo – SMS diversi

{
  "messages": [
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dd90p"],
      "destinations": ["+393351234567"],
      "sender": "ShopNow",
      "body": "Big Sale! Today only, get up to 50% off on all items. Visit our store and take advantage of the offer!"
    },
    {
      "ids": ["157d541b-e0cd-4340-ac77-bc5d530dd90a"],
      "destinations": ["+393351234561"],
      "sender": "Foodies",
      "body": "Try our new summer menu! Book your table now and receive a complimentary dessert."
    }
  ]
}

Esempio 12: Verifica credito

curl -X GET https://secure.agiletelecom.com/services/sms/credit \
  -H "X-Api-Key: your-api-key"

Risposte #

Risposta di successo (2XX)

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

Campo	Tipo	Descrizione
globalId	string	Valore del globalId riportato dalla richiesta
processedMessages	integer	Messaggi accettati come da sezione messages sulla richiesta
processedSmsParts	integer	Parti che verranno spedite (differisce dal precedente in caso di concatenati)
credit	double	Credito residuo dell’account espresso in €

Errori client (4XX)

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

Campo	Tipo	Descrizione
status	string	Vale sempre “fail” per gli errori 4XX
data	object / string	Elenco chiave-valore con i campi problematici o stringa descrittiva
code	integer	Codice di errore custom

Errori server (5XX)

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

Campo	Tipo	Descrizione
status	string	Vale sempre “error” per gli errori 5XX
message	string	Descrizione del problema riscontrato
code	integer	Codice di errore custom

Codici di errore #

Codice	Descrizione
1	Wrong credentials
2	Insufficient credit
8	Server error
9	Server error (service timeout)
26	Alias (Sender) non autorizzato
100	Source IP is not allowed

Delivery Report (Webhook) #

Se abilitato, AgileTelecom invierà una notifica di consegna all’URL specificato dal cliente.

Struttura del Delivery Report

{
  "messageId": "157d541b-e0cd-4340-ac77-bc5d530dd90e",
  "destination": "41793026727",
  "statusCode": 3,
  "description": "Delivered",
  "doneDate": "2022-05-09 09:00:05.002+0200",
  "concatTotal": 2,
  "concatProgressive": 1,
  "lcrOperator": "22210",
  "realOperator": "22201",
  "price": 0.003
}

Parametri del Delivery Report

Campo	Tipo	Descrizione
messageId	string	ID che identifica in modo univoco il messaggio spedito
destination	string	Numero di telefono del destinatario
statusCode	integer	Codice stato di ricezione
description	string	Descrizione dello status
doneDate	string	Data relativa al delivery
concatTotal	integer	Numero di parti totali in caso di messaggio concatenato
concatProgressive	integer	Numero della parte del messaggio
lcrOperator	string	(Opzionale) Operatore individuato dal servizio LCR
realOperator	string	(Opzionale) Operatore reale del numero
price	double	(Opzionale) Costo dell’invio

Codici di stato Delivery

Codice	Stato
1	Accepted
2	Rejected
3	Delivered
4	Expired
5	Deleted
6	Undeliverable

Note importanti #

Formato numeri: I numeri di destinazione devono essere in formato internazionale con prefisso paese (es. +39 per l’Italia)
Limiti SMS:
– SMS standard (GSM 7-bit): 160 caratteri
– SMS Unicode: 70 caratteri
– Gli SMS più lunghi vengono automaticamente concatenati se enableConcatenated è true
Mittente:
– Alfanumerico: massimo 11 caratteri
– Numerico: massimo 16 cifre
Encoding: Il corpo del messaggio può essere inviato in UTF-8 o in formato esadecimale
Rate limiting: Verificare con AgileTelecom eventuali limiti di invio per secondo/minuto

Postman Collection #

Scarica la collection: Download Postman Collection

Importa in Postman:
– Apri Postman
– Clicca su “Import” in alto a sinistra
– Trascina il file JSON scaraicato or clicca “Upload Files”
– Conferma l’importazione

Configura le variabili:
– Clicca sul nome della collection “Http Post Example” nel pannello laterale
– Seleziona la tab “Variables”
– Troverai due colonne: “Initial Value” e “Current Value”
– Initial Value: valore predefinito della variabile
– Current Value: valore effettivamente utilizzato nelle chiamate
– Modifica i valori nella colonna “Current Value”:
– username: inserisci il tuo username (per Basic Auth)
– password: inserisci la tua password (per Basic Auth)
– api-key: inserisci la tua API key (per autenticazione tramite API Key)
– enable_apikey: imposta true per usare API Key, false per Basic Auth
– Salva le modifiche cliccando sul pulsante “Save” in alto a destra

Note sulla Collection

Valori di test: I valori predefiniti nella collection (user, pass, api-value) sono credenziali di test che simulano l’invio senza effettivamente inviare SMS
Test del payload: Puoi utilizzare questi valori di test per verificare la correttezza della struttura JSON prima di utilizzare le tue credenziali reali
Organizzazione: La collection è organizzata in cartelle:
- Basic example: esempi di invio semplici
- Advanced example: funzionalità avanzate (scheduling, UDH, simulazione)
- Multiple sending: invii multipli
- ApiKey No PostMan Script: esempi diretti con API Key

Configurazione Ambiente

La collection include script di pre-request che gestiscono automaticamente l’autenticazione basandosi sulla variabile enable_apikey:

Se enable_apikey = true: utilizza l’autenticazione tramite API Key
Se enable_apikey = false: utilizza la Basic Authentication

Generazione Codice da Postman

Postman offre una funzionalità molto utile per generare codice in vari linguaggi di programmazione:

Apri una richiesta nella collection
Clicca sull’icona “< >” (Code snippet) nella parte destra della finestra
Seleziona il linguaggio desiderato dal menu a tendina:
– cURL
– Python (requests)
– JavaScript (fetch, axios)
– PHP
– Java
– C#
– Go
– Ruby
– E molti altri…
Copia il codice generato e utilizzalo come reference implementation per la tua integrazione

Esempio di cURL generato automaticamente:

curl --location 'https://secure.agiletelecom.com/services/sms/send' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: your-api-key' \
--data '{
    "messages": [
        {
            "destinations": ["+393351234567"],
            "sender": "TechNews",
            "body": "Latest tech news!"
        }
    ]
}'

Questa funzionalità è particolarmente utile per:

Velocizzare l’integrazione nel tuo linguaggio preferito
Verificare la corretta formattazione delle richieste
Testare rapidamente le API da linea di comando
Creare esempi di codice per la documentazione interna

Supporto #

Per assistenza tecnica o informazioni commerciali, contattare il supporto AgileTelecom all’indirizzo help@agiletelecom.com

Send SMS

Receive SMS

Credit Check

Mobile Number Portability

ITA – REST API / Protocollo HTTP

OVERVIEW #

⚠️ Avviso importante #

Base URL #

Autenticazione #

Endpoints #

Esempi di utilizzo #

Risposte #

Codici di errore #

Delivery Report (Webhook) #

Note importanti #

Postman Collection #

Supporto #

What are your Feelings

Products

Industries

Developers

How we work

Get in touch