UC-010 — Scheduled Message Sending

Field	Value
ID	UC-010
Goal	Schedule message sending for a future date and time
Channel	SMS / RCS / WhatsApp
Complexity	Advanced
Estimated time	15 minutes
APIs involved	POST /api/message-server/sms/send, POST /api/message-server/rcs/send, POST /api/message-server/whatsapp/send

Real-world scenarios

• Studio Medico Rossi — Appointment reminder 24h in advance: The clinic schedules an SMS reminder for the day before the visit, at 08:00 in the morning.
• TechStore — Birthday greetings: The e-commerce sends an RCS message with a card and discount code on the morning of the customer's birthday.
• CloudHost Italia — Scheduled maintenance notification: The service provider notifies customers 48h before a maintenance window with a WhatsApp message containing the details.

Prerequisites

Before you begin, make sure you have:

• Active API Key → How to get one
• Sufficient credit → Check in the Qlara Dashboard

:::tip Test without costs Add "simulation": true in the request body to validate the flow without actually sending messages and without consuming credit. :::

Scheduled send timeline

Step-by-step guide

Step 1 — Compose the message with a scheduled date

The scheduledDate field accepts the format yyyy-MM-dd HH:mm:ss.SSSZ (ISO 8601 with timezone offset).

Date format:

Component	Format	Example
Date	yyyy-MM-dd	2026-04-10
Time	HH:mm:ss.SSS	08:00:00.000
Timezone	Z (offset)	+0200 (CEST)
Complete	yyyy-MM-dd HH:mm:ss.SSSZ	2026-04-10 08:00:00.000+0200

Step 2 — Send a scheduled SMS

Schedule a reminder for the following day at 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
  }'

Response:

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

:::info Accepted does not mean sent accepted: true indicates that the message has been accepted and scheduled successfully. The actual sending will occur at the date and time specified in scheduledDate. :::

Step 3 — Check the status

You can check the status of a scheduled message via 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 — Receive the delivery confirmation

At the scheduled send time, you will receive the delivery webhook at your 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"
}

Variants: scheduling on other channels

Schedule RCS

The RCS endpoint supports the same scheduledDate field:

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
  }'

Response:

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

Schedule WhatsApp

WhatsApp also supports 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
  }'

Response:

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

:::warning WhatsApp template For scheduled sending on WhatsApp, using a Meta-approved template is mandatory. Free-form messages (body) cannot be scheduled because the 24-hour window might expire before the send time. See UC-013: WhatsApp Template Workflow. :::

Best practices for scheduling

Aspect	Recommendation
Timezone	Always specify the recipient's timezone. Italy uses +0100 (CET) or +0200 (CEST)
Minimum lead time	Schedule at least 5 minutes ahead of the current time
Send time	Respect regulations: avoid sending between 21:00 and 08:00
Idempotency	Use a custom messageId to avoid duplicates in case of retries
Verification	After scheduling, verify the status with polling or wait for the webhook

Behind the scenes

When you send a message with scheduledDate, the Qlara platform:

1. Validates the message -- Verifies recipient, sender, body, and date format just like an immediate send.
2. Queues the message -- The message is saved in a persistent queue with the scheduled send timestamp.
3. Responds immediately -- You receive 200 OK with accepted: true without waiting for the actual send.
4. Scheduler -- An internal process periodically checks the queue and starts sending when the timestamp matches.
5. Send and notify -- The message is sent to the carrier like a normal message, and you receive the delivery webhook.

If the message cannot be delivered (e.g. invalid number), you will receive a webhook with statusCode: 6 (undeliverable) at the scheduled send time, not at the scheduling time.

Expected result

Aspect	Detail
Action completed	Message scheduled and delivered at the specified date/time
Channel used	SMS / RCS / WhatsApp
Delivery confirmation	Via webhook (statusCode: 3) within 5-60 sec after the scheduled time

Common errors

Problem	Probable cause	Solution
HTTP 401	Missing or invalid API Key	Check X-Api-Key header
accepted: false	Insufficient credit or invalid number	Check credit; verify E.164 format
HTTP 400 — Invalid scheduledDate	Wrong date format or date in the past	Use format yyyy-MM-dd HH:mm:ss.SSSZ; schedule at least 5 minutes ahead
Message not sent at scheduled time	Timezone offset incorrect	Verify the timezone offset matches the intended delivery time (e.g., +0200 for CEST)

Next steps

• Webhooks Guide -- Configure the webhook to receive delivery confirmations
• SMS Legacy API -- Batch scheduled sending with the Legacy format (scheduling)
• RCS API -- Send rich messages with cards and carousels
• WhatsApp API -- Send templates and free-form messages
• UC-009: Two-Way Conversation -- Handle customer replies to scheduled messages