Send Bulk SMS

Send Millions of SMS at once.

Overview

The Bulk SMS feature supports sending:

1. A single message to multiple recipients through a single request.

2. Different messages to different recipients using Single SMS in a loop.

Outbox functionalities and cost management are included. For different messages, the request initiates a loop internally via the Single SMS endpoint.

---

Endpoint: Send Bulk SMS

• Method: POST

• URL: /api/sms/send-bulk

---

Request Body (Same Message for All Recipients)

{
  "userId": "user123",
  "recipients": [
    "[phone]",
    "[phone]",
    "[phone]"
  ],
  "message": "Dear Customer, your bill is due on 20th Dec. Pay to avoid disconnection.",
  "senderId": "TUKUPAY",
  "messageName": "Bill Reminder",
  "messageId": "bulkMsg123",
  "scheduleTimestamp": "2024-12-20T12:00:00Z", // Optional
  "priority": "normal", // Options: "normal", "high"
  "tags": ["bill-reminder", "bulk"], // Optional
  "customData": {
    "purpose": "Bill Reminder Campaign",
    "linkedTransactionId": "txn456" // Optional
  }
}

Request Body (Different Messages Per Recipient)

For different messages per recipient, call the Single SMS endpoint in a loop.

Example Loop Data:

[
  {
    "recipient": "[phone]",
    "message": "Dear John, your bill is due on 20th Dec.",
    "senderId": "TUKUPAY",
    "messageName": "Bill Reminder"
  },
  {
    "recipient": "[phone]",
    "message": "Dear Jane, your bill is overdue. Pay immediately.",
    "senderId": "TUKUPAY",
    "messageName": "Bill Reminder"
  }
]

Bulk Endpoint Response for Loop Processing:

{
  "status": "success",
  "message": "Bulk SMS sent using Single SMS in a loop.",
  "outboxIds": ["outboxId1", "outboxId2", "outboxId3"]
}

---

Bulk SMS Outbox Structure

Each Bulk Outbox entry tracks the entire bulk SMS transaction. Nested records capture individual SMS details.

Field	Type	Description
outboxId	string	Unique identifier for the bulk outbox entry.
userId	string	The user who initiated the bulk SMS.
senderId	string	The sender ID used for the bulk SMS.
messageId	string	Unique identifier for the bulk message.
messageName	string	Name of the bulk message (for tracking purposes).
message	string	SMS content (if common across all recipients).
recipients	array<string>	List of phone numbers (if common message).
totalSmsUnitsUsed	number	Total SMS units charged for the bulk transaction.
totalCost	number	Total cost for the bulk transaction.
status	string	Status of the bulk SMS (sent, failed, partial).
timestamps	object	Includes createdAt, completedAt, and lastAttemptAt.
retryCount	number	Number of retry attempts for the bulk SMS.
nestedOutbox	array<object>	Individual SMS records (nested) for the bulk SMS.
tags	array<string>	Tags for tracking the bulk SMS (e.g., bill-reminder, bulk).
customData	object	Optional metadata (e.g., purpose, linkedTransactionId).

---

Nested Outbox for Bulk SMS

Each nested record captures individual SMS details:

Field	Type	Description
nestedOutboxId	string	Unique identifier for the nested SMS entry.
recipientPhoneNumber	string	The phone number of the recipient.
smsUnitsUsed	number	Number of SMS units charged for this individual SMS.
costPerUnit	number	Cost of each SMS unit (retrieved from SMS cost model).
totalCost	number	Total cost for this individual SMS.
status	string	Status of the SMS (sent, failed, pending).
timestamps	object	Includes createdAt, sentAt, and lastAttemptAt.
retryCount	number	Number of retry attempts for this SMS.
errorDetails	string	Optional: Reason for failure, if applicable.

---

Workflow

1. Common Message:

   • Handles a single message sent to multiple recipients.

   • Cost calculation:

     • Total SMS units = Total recipients × SMS segments (160 characters per segment).

     • Costs are logged in the Bulk Outbox and nested records.

2. Different Messages:

   • The system processes individual SMS requests internally.

   • Logs each SMS in the Single SMS Outbox but links them to a parent Bulk Outbox.

3. Outbox Management:

   • All sent SMS are recorded in the Bulk Outbox, with nested tracking for each recipient.

   • Retry mechanism for failed messages, with individual or batch retries.

4. Statuses:

   • sent: All SMS in the bulk transaction were successfully delivered.

   • failed: None of the SMS in the bulk transaction were delivered.

   • partial: Some SMS were delivered, others failed.

---

Send Bulk SMS Response

{
  "status": "success",
  "bulkOutboxEntry": {
    "outboxId": "bulkOutbox123",
    "userId": "user123",
    "senderId": "TUKUPAY",
    "messageId": "bulkMsg123",
    "messageName": "Bill Reminder",
    "message": "Dear Customer, your bill is due on 20th Dec.",
    "recipients": [
      "[phone]",
      "[phone]",
      "[phone]"
    ],
    "totalSmsUnitsUsed": 5,
    "totalCost": 3.0,
    "status": "partial",
    "timestamps": {
      "createdAt": "2024-12-15T10:00:00Z",
      "completedAt": "2024-12-15T10:05:00Z",
      "lastAttemptAt": "2024-12-15T10:05:00Z"
    },
    "retryCount": 0,
    "nestedOutbox": [
      {
        "nestedOutboxId": "nested123",
        "recipientPhoneNumber": "[phone]",
        "smsUnitsUsed": 1,
        "costPerUnit": 0.6,
        "totalCost": 0.6,
        "status": "sent",
        "timestamps": {
          "createdAt": "2024-12-15T10:00:00Z",
          "sentAt": "2024-12-15T10:01:00Z",
          "lastAttemptAt": null
        },
        "retryCount": 0
      }
    ],
    "tags": ["bill-reminder", "bulk"],
    "customData": {
      "purpose": "Bill Reminder Campaign",
      "linkedTransactionId": "txn456"
    }
  },
  "message": "Bulk SMS sent partially. Check nested outbox for details."
}

---

Additional Retry Endpoint

Retry failed SMS from Bulk Outbox.

Developer Guidance for Custom SMS Per Recipient

If you want to create a customized SMS for each recipient, you can handle this logic directly within your application. For example, you can design a UI that allows you to define fields such as {name}, {date}, or {balance} as placeholders in your message template (e.g., Dear {name}, your balance as of {date} is Kes {balance}). These placeholders would then be dynamically replaced with actual data fetched from your database. Once the customized messages are generated in your app, you can send them using the Single SMS API in a loop. This method gives you the flexibility of personalization while using the existing Tuku Pay infrastructure for SMS sending.