Guida SMS

UniMsg permette di inviare SMS in tutto il mondo con alta deliverability e tracking completo. Questa guida copre tutte le funzionalità disponibili per il canale SMS.

Caratteristiche

Invio singolo e bulk
Mittente personalizzabile (alfanumerico o numerico)
Supporto messaggi lunghi (concatenati)
Notifiche di consegna (DLR)
Scheduling invio programmato
Costo: 1 credito per SMS standard

Endpoint

Metodo	Endpoint	Descrizione
`POST`	`/v1/sms/send`	Invia un SMS singolo
`POST`	`/v1/sms/bulk`	Invia SMS multipli
`GET`	`/v1/sms/{id}`	Stato di un SMS

Invio SMS Singolo

Richiesta

POST /v1/sms/send
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "to": "+39123456789",
    "message": "Il tuo codice di verifica è: 123456",
    "sender": "MyApp"
}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
`to`	string	Sì	Numero destinatario (formato E.164: +39...)
`message`	string	Sì	Testo del messaggio (max 1600 caratteri)
`sender`	string	No	Mittente (max 11 caratteri alfanumerici o 15 numerici)
`scheduled_at`	string	No	Data/ora invio programmato (ISO 8601)
`callback_url`	string	No	URL per webhook di stato

Risposta

{
    "success": true,
    "data": {
        "message_id": "msg_sms_xxxxxxxxxxxx",
        "to": "+39123456789",
        "status": "queued",
        "segments": 1,
        "credits_used": 1,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Invio Bulk

Per inviare lo stesso messaggio a più destinatari:

POST /v1/sms/bulk
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "recipients": [
        "+39123456789",
        "+39123456790",
        "+39123456791"
    ],
    "message": "Promozione speciale! Usa il codice SCONTO20 per il 20% di sconto.",
    "sender": "MyShop"
}

Risposta

{
    "success": true,
    "data": {
        "batch_id": "batch_xxxxxxxxxxxx",
        "total_recipients": 3,
        "total_credits": 3,
        "status": "processing"
    }
}

Messaggi Lunghi

Un SMS standard può contenere:

160 caratteri con set GSM-7 (lettere base)
70 caratteri con caratteri Unicode (emoji, accenti speciali)

Per messaggi più lunghi, UniMsg li divide automaticamente in segmenti concatenati:

Lunghezza	Segmenti	Crediti
1-160 caratteri	1	1
161-306 caratteri	2	2
307-459 caratteri	3	3
...	...	...

Nota: Nei messaggi concatenati, ogni segmento usa 7 caratteri per l'header UDH, riducendo lo spazio disponibile a 153 caratteri GSM-7 per segmento.

Mittente Personalizzato

Il parametro sender supporta due formati:

Alfanumerico: Max 11 caratteri (es: "MyCompany")
Numerico: Max 15 cifre (es: "+39123456789")

Attenzione: Alcuni paesi non supportano mittenti alfanumerici. In questi casi verrà usato un numero di servizio.

Invio Programmato

Per programmare l'invio in un momento specifico:

{
    "to": "+39123456789",
    "message": "Promemoria: il tuo appuntamento è domani alle 10:00",
    "sender": "Clinica",
    "scheduled_at": "2024-01-16T09:00:00+01:00"
}

Stati del Messaggio

Stato	Descrizione
`queued`	In coda per l'invio
`scheduled`	Programmato per invio futuro
`sent`	Inviato al gateway
`delivered`	Consegnato al destinatario
`failed`	Invio fallito
`expired`	Scaduto (non consegnato in tempo)

Errori Comuni

Codice	Messaggio	Soluzione
`INVALID_PHONE`	Numero non valido	Usa formato E.164 (+39...)
`INVALID_SENDER`	Mittente non valido	Max 11 caratteri alfanumerici
`MESSAGE_TOO_LONG`	Messaggio troppo lungo	Max 1600 caratteri
`BLACKLISTED`	Numero in blacklist	Il destinatario si è disiscritto

Webhook WhatsApp