Schedule SMS

Overview

Tuku Pay allows you to schedule both Single SMS and Bulk SMS for future delivery. Scheduled messages will be queued and automatically sent at the specified time by our servers. Time management, including handling different time zones, is managed on our servers to ensure accurate delivery. However, the client can optionally specify their time zone in the request body.

Features of Scheduled SMS:

1. Single or Bulk SMS: You can schedule either type, with all standard requirements such as sender ID, recipient(s), and message body.

2. Time Zone Handling: Clients can include their time zone, or the server defaults to the UTC equivalent.

3. Outbox Tracking: Scheduled SMS entries are stored in the Outbox with a status indicating they are "scheduled." Once sent, their status updates to "delivered," "failed," or "partially delivered" for bulk SMS.

4. Cancelation: Scheduled SMS can be canceled before the scheduled time via a separate endpoint.

---

Endpoint: Schedule SMS

POST /api/sms/schedule

Request Body:

{
  "senderId": "TUKUPAY",                // Sender ID selected by the user  
  "recipients": ["254712345678"],       // Array of phone numbers  
  "message": "Hello, your balance is ...", // Message body  
  "scheduleTime": "2024-12-16T12:00:00", // ISO 8601 format for scheduling time  
  "timeZone": "Africa/Nairobi",         // Optional: Client's time zone  
  "messageName": "Reminder",            // Name of the scheduled message  
  "messageId": "MSG12345",              // Unique ID for the message  
  "type": "single",                     // Options: "single" or "bulk"  
  "bulkRecipients": [                   // Optional: For bulk SMS  
    "254712345678", "254712345679" 
  ]
}

---

Response:

• 201 Created

{
  "status": "success",
  "message": "SMS scheduled successfully.",
  "scheduleId": "SCHD12345",
  "details": {
    "senderId": "TUKUPAY",
    "recipients": ["254712345678"],
    "message": "Hello, your balance is ...",
    "scheduleTime": "2024-12-16T12:00:00",
    "timeZone": "Africa/Nairobi"
  }
}

• 400 Bad Request If the request is malformed or missing required fields.

---

Additional Guidance for Developers

• Time Zones: Always include a time zone in your API requests to ensure precise delivery, especially if your application operates across regions.

• Cancel Scheduled SMS: Use the /api/sms/cancel-schedule endpoint to cancel a scheduled SMS before the scheduled time.

• Custom Messages: For customized bulk SMS where each recipient has a unique message, use a combination of your app's logic and the Single SMS API with a loop before scheduling the messages.

• Validation: Ensure that the scheduleTime provided is in the future; the API will reject requests with past or invalid times.