Invio SMS Transazionale

Invia SMS personalizzati a uno o più destinatari con supporto a variabili, link tracciati e scheduling.

POST /api/v1/{account_code}/sms/transactional/send/
Authorization Bearer {token}  — 56 caratteri

La richiesta è composta da due sezioni principali: default (parametri comuni a tutti i destinatari) e specific (array di destinatari con override individuali). I parametri in specific sovrascrivono quelli di default per ogni singolo messaggio. È possibile inviare al massimo 10.000 destinatari per richiesta; eventuali elementi aggiuntivi vengono scartati.

Nota sul credito La risposta può essere positiva anche in assenza di credito sufficiente. Verifica il saldo del tuo account prima dell'invio.

Parametri (JSON)

Parametro Richiesto Tipo Descrizione
account_code SI string (UUID) Codice account — passato nel path URL
default SI object Parametri predefiniti validi per tutti i destinatari
specific SI array<object> Lista di destinatari con override individuali, massimo 10.000 elementi per richiesta

Oggetto default

Parametro Richiesto Tipo Descrizione
sender_id SI string (max 11) Mittente pre-autorizzato associato all'account pre-autorizzato
text SI string Testo del messaggio (può contenere variabili con delimitatori)
sending_time NO string (ISO 8601) Data/ora di invio programmato (es: 2025-01-30T14:13:24.679Z)
validity_time NO string (ISO 8601) Scadenza validità del messaggio
expire_time_rcs NO string (ISO 8601) Scadenza per l'invio RCS
ph_delimiter NO string Delimitatori per le variabili nel testo (es: "# #" → #nome#, o "{{ }}" → {{nome}})
meta NO object Variabili condivise da sostituire nel testo (es: {"azienda": "Acme"})

Oggetti nell'array specific

Parametro Richiesto Tipo Descrizione
phone_number SI string Numero destinatario con prefisso internazionale (es: "+393xxxxxxxxx")
meta NO object Variabili individuali (sovrascrivono quelle di default.meta)
text NO string Testo specifico per questo destinatario (sovrascrive default.text)
ph_delimiter NO string Delimitatore specifico (sovrascrive default.ph_delimiter)
validity_time NO string (ISO 8601) Validità specifica per questo destinatario
expire_time_rcs NO string (ISO 8601) Scadenza RCS specifica per questo destinatario

Link Tracciati

Per ottenere il conteggio dei clic su un link nel testo del messaggio, usa il formato:

Sintassi 
{{ TRACKED_LINK_https://example.com }}

La piattaforma sostituirà automaticamente il link tracciato con uno shortlink. Il prefisso TRACKED_LINK_ deve precedere l'URL e il tutto deve essere incluso tra {{ }}.

Il delimitatore {{ }} per i link tracciati è indipendente dal ph_delimiter usato per le variabili del testo. Puoi usare entrambi nella stessa richiesta.

Esempio Richiesta

JSON 
{
  "default": {
    "sender_id": "MITTENTE",
    "text": "Ciao #nome# #cognome#, hai contattato #azienda#. Clicca qui: {{ TRACKED_LINK_https://example.com }}",
    "sending_time": "2025-01-30T14:13:24.679Z",
    "validity_time": "2025-02-28T14:13:24.679Z",
    "ph_delimiter": "# #",
    "meta": {
      "azienda": "La Mia Azienda"
    }
  },
  "specific": [
    {
      "phone_number": "+393331234567",
      "meta": {
        "nome": "Mario",
        "cognome": "Rossi"
      }
    },
    {
      "phone_number": "+393407654321",
      "ph_delimiter": "{{ }}",
      "text": "Ciao {{nome}} {{cognome}}, benvenuto in {{azienda}}! {{ TRACKED_LINK_https://example.com }}",
      "meta": {
        "azienda": "Altra Azienda",
        "nome": "Carlo",
        "cognome": "Bianchi"
      }
    }
  ]
}

Risposta Successo

200 OK

Un array con un oggetto per ogni destinatario nell'ordine dell'array specific.

JSON 
[
  {
    "success": true,
    "uuid": "9a53f419-6475-a191-9b86-xxxxxxxxxxxx",
    "index": 0,
    "receiver": "393331234567",
    "shortlink": "https://l2l.biz/cgRBB8",
    "error": null
  },
  {
    "success": true,
    "uuid": "a5562ac9-54f7-3c1c-7006-xxxxxxxxxxxx",
    "index": 1,
    "receiver": "393407654321",
    "shortlink": "https://l2l.biz/0vhiZj",
    "error": null
  }
]

Campi Risposta

Campo Tipo Descrizione
success boolean Esito dell'invio per questo destinatario
uuid string Identificatore univoco del messaggio
index integer Posizione nell'array specific (base 0)
receiver string Numero destinatario (senza il +)
shortlink string|null URL breve generato se era presente un link tracciato
error string|null Descrizione dell'errore (se presente)

Ricezione degli aggiornamenti di consegna (DLR)

Il campo uuid presente nella risposta identifica univocamente ogni messaggio inviato. Puoi ricevere gli aggiornamenti di consegna (DLR) — come DELIVERED, UNDELIVERED, EXPIRED — configurando un Http Endpoint sulla piattaforma.

Gli Http Endpoint si configurano nella sezione Http Endpoints della piattaforma. Una volta attivato, la piattaforma invierà una richiesta HTTP al tuo URL ogni volta che lo stato di un messaggio cambia, includendo l'uuid e lo stato aggiornato.
JSON 

    {
        "uuid":"88442951-e8a7-68fb-450c-a28f16xxxxxx",
        "msgId":"e6e53e89-40a8-fa00-8005-c76614xxxxxx",
        "event":"DELIVERED",
        "partNum":1,
        "numParts":1
    }