UC-010 — Invio Programmato di Messaggi

Campo	Valore
ID	UC-010
Obiettivo	Programmare l'invio di messaggi per una data e ora futura
Canale	SMS / RCS / WhatsApp
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	15 minuti
API coinvolte	POST /api/message-server/sms/send, POST /api/message-server/rcs/send, POST /api/message-server/whatsapp/send

Scenari reali

• Studio Medico Rossi — Promemoria appuntamento 24h prima: L'ambulatorio programma un SMS di promemoria per il giorno prima della visita, alle 08:00 del mattino.
• TechStore — Auguri di compleanno: L'e-commerce invia un messaggio RCS con card e codice sconto la mattina del compleanno del cliente.
• CloudHost Italia — Notifica manutenzione programmata: Il provider di servizi avvisa i clienti 48h prima di una finestra di manutenzione con un messaggio WhatsApp contenente i dettagli.

Timeline dell'invio programmato

Guida passo-passo

Step 1 — Comporre il messaggio con data programmata

Il campo scheduledDate accetta il formato yyyy-MM-dd HH:mm:ss.SSSZ (ISO 8601 con offset di fuso orario).

Formato data:

Componente	Formato	Esempio
Data	yyyy-MM-dd	2026-04-10
Ora	HH:mm:ss.SSS	08:00:00.000
Timezone	Z (offset)	+0200 (CEST)
Completo	yyyy-MM-dd HH:mm:ss.SSSZ	2026-04-10 08:00:00.000+0200

Step 2 — Inviare un SMS programmato

Programma un promemoria per il giorno seguente alle 08:00:

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/sms/send" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+393471234567",
    "sender": "DrRossi",
    "body": "Gentile Sig. Bianchi, le ricordiamo l'\''appuntamento di domani 11/04 alle ore 10:30 presso lo Studio Medico Rossi, Via Manzoni 15, Milano. Per disdire risponda ANNULLA.",
    "scheduledDate": "2026-04-10 08:00:00.000+0200",
    "messageId": "reminder-apt-2026-04-11-bianchi",
    "enableNotification": true
  }'

Risposta:

{
  "messageId": "reminder-apt-2026-04-11-bianchi",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 2,
      "reasons": []
    }
  }
}

:::info Accepted non significa inviato accepted: true indica che il messaggio e' stato accettato e schedulato con successo. L'invio effettivo avverra' alla data e ora indicata in scheduledDate. :::

Step 3 — Verificare lo stato

Puoi verificare lo stato di un messaggio programmato tramite polling:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status/reminder-apt-2026-04-11-bianchi" \
  -H "X-Api-Key: YOUR_API_KEY"

Step 4 — Ricevere la conferma di consegna

Al momento dell'invio programmato, riceverai il webhook di delivery al tuo callback URL:

{
  "channel": "SMS",
  "eventType": "DELIVERY",
  "messageId": "reminder-apt-2026-04-11-bianchi",
  "destination": "+393471234567",
  "statusCode": 3,
  "description": "delivered",
  "eventDate": "2026-04-10T06:00:03Z"
}

Varianti: schedule su altri canali

Schedule RCS

L'endpoint RCS supporta lo stesso campo scheduledDate:

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/rcs/send" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+393471234567",
    "agentId": 1,
    "body": {
      "type": "CARD",
      "title": "Buon compleanno, Laura!",
      "description": "Tanti auguri da TechStore! Usa il codice BDAY20 per il 20% di sconto sul prossimo acquisto. Valido fino al 30 aprile.",
      "mediaUrl": "https://cdn.techstore.it/img/birthday-card.jpg",
      "mediaHeight": "MEDIUM",
      "suggestions": [
        {
          "type": "url",
          "text": "Usa lo sconto",
          "url": "https://techstore.it/promo/BDAY20"
        }
      ]
    },
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "enableNotification": true
  }'

Risposta:

{
  "messageId": "a3f7c901-2b4e-48d1-9e5a-1234567890ab",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": true,
      "reasons": []
    },
    "sms": null
  }
}

Schedule WhatsApp

Anche WhatsApp supporta scheduledDate:

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/whatsapp/send" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+393471234567",
    "phoneNumberId": 5,
    "template": {
      "id": 87
    },
    "placeholders": {
      "nome": "Marco",
      "data_manutenzione": "12 aprile 2026",
      "orario": "02:00 - 06:00"
    },
    "scheduledDate": "2026-04-10 18:00:00.000+0200",
    "enableNotification": true
  }'

Risposta:

{
  "messageId": "d82e91f4-c5a3-4f67-b012-abcdef123456",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": true
    },
    "rcs": null,
    "sms": null
  }
}

:::warning Template WhatsApp Per l'invio programmato su WhatsApp, e' obbligatorio usare un template approvato da Meta. I messaggi free-form (body) non possono essere schedulati perché' la finestra 24h potrebbe scadere prima dell'orario di invio. Vedi UC-013: WhatsApp Template Workflow. :::

Best practice per la schedulazione

Aspetto	Raccomandazione
Timezone	Specifica sempre il fuso orario del destinatario. L'Italia usa +0100 (CET) o +0200 (CEST)
Anticipo minimo	Programma con almeno 5 minuti di anticipo rispetto all'ora corrente
Orario di invio	Rispetta le normative: evita invii tra le 21:00 e le 08:00
Idempotenza	Usa un messageId personalizzato per evitare duplicati in caso di retry
Verifica	Dopo la schedulazione, verifica lo stato con polling o attendi il webhook

Dietro le quinte

Quando invii un messaggio con scheduledDate, la piattaforma Qlara:

1. Valida il messaggio -- Verifica destinatario, sender, body e formato della data come per un invio immediato.
2. Accoda il messaggio -- Il messaggio viene salvato in una coda persistente con il timestamp di invio programmato.
3. Risponde immediatamente -- Ricevi 200 OK con accepted: true senza attendere l'invio effettivo.
4. Scheduler -- Un processo interno verifica periodicamente la coda e avvia l'invio quando il timestamp corrisponde.
5. Invio e notifica -- Il messaggio viene inviato al carrier come un normale messaggio, e ricevi il webhook di delivery.

Se il messaggio non puo' essere recapitato (es. numero non valido), riceverai un webhook con statusCode: 6 (undeliverable) al momento dell'invio programmato, non al momento della schedulazione.

Prossimi passi

• Guida Webhooks -- Configura il webhook per ricevere le conferme di delivery
• SMS Legacy API -- Invio schedulato batch con il formato Legacy (scheduling)
• RCS API -- Invio di messaggi rich con card e carousel
• WhatsApp API -- Invio template e messaggi free-form
• UC-009: Two-Way Conversation -- Gestisci le risposte dei clienti ai messaggi programmati