Send Single SMS

This end points allows users and apps to send a single SMS and outbox feature.

Overview

This endpoint sends a single SMS and logs all SMS activities in an Outbox. If an SMS fails to send, the user can resend it from the outbox. Each outbox entry contains timestamps, statuses, and SMS cost details for reconciliation and auditing.

---

Endpoint: Send Single SMS

• Method: POST

• URL: /api/sms/send

---

Request Body

{
  "userId": "user123",
  "recipientPhoneNumber": "[phone]",
  "message": "Your OTP is 123456. Please use this code to verify your account.",
  "senderId": "TUKUPAY",
  "messageName": "OTP Verification",
  "messageId": "msg123",
  "scheduleTimestamp": "2024-12-20T12:00:00Z", // Optional for scheduling SMS
  "priority": "normal", // Options: "normal", "high"
  "tags": ["notification", "OTP"], // Optional tags for tracking
  "customData": {
    "purpose": "Account Verification",
    "linkedTransactionId": "txn789" // Optional metadata
  }
}

---

Outbox Data Structure

The Outbox will store all sent SMS with the following fields:

Field	Type	Description
outboxId	string	Unique identifier for the outbox entry.
userId	string	The user who initiated the SMS.
recipientPhoneNumber	string	The phone number of the recipient.
message	string	The SMS content.
senderId	string	The sender ID used for the SMS.
messageId	string	Unique identifier for the message.
smsUnitsUsed	number	Number of SMS units charged for the message.
costPerUnit	number	Cost of each SMS unit (retrieved from SMS cost model).
totalCost	number	Total cost for sending the SMS.
status	string	Status of the SMS (sent, failed, pending).
timestamps	object	Includes createdAt, sentAt, and lastAttemptAt.
retryCount	number	Number of retry attempts for the SMS.
errorDetails	string	Optional: Reason for failure, if applicable.
tags	array<string>	Tags for tracking the SMS (e.g., notification, OTP).
customData	object	Optional metadata (e.g., purpose, linkedTransactionId).

---

SMS Status Management

• Statuses:

  • sent: The SMS was successfully delivered to the recipient.

  • failed: The SMS could not be sent (e.g., network error).

  • pending: The SMS is scheduled or queued for sending.

• Retries:

  • Users can resend failed SMS directly from the outbox using a separate endpoint.

  • The system caps retries at a configurable limit (e.g., 3 attempts).

• Timestamps:

  • createdAt: When the SMS was logged in the outbox.

  • sentAt: When the SMS was successfully sent.

  • lastAttemptAt: The timestamp of the most recent attempt to send the SMS.

---

Send SMS Response

The response now includes the Outbox entry details.

{
  "status": "success",
  "outboxEntry": {
    "outboxId": "outbox456",
    "userId": "user123",
    "recipientPhoneNumber": "[phone]",
    "message": "Your OTP is 123456. Please use this code to verify your account.",
    "senderId": "TUKUPAY",
    "messageId": "msg123",
    "smsUnitsUsed": 1,
    "costPerUnit": 0.6,
    "totalCost": 0.6,
    "status": "sent",
    "timestamps": {
      "createdAt": "2024-12-15T08:00:00Z",
      "sentAt": "2024-12-15T08:01:00Z",
      "lastAttemptAt": null
    },
    "retryCount": 0,
    "tags": ["notification", "OTP"],
    "customData": {
      "purpose": "Account Verification",
      "linkedTransactionId": "txn789"
    }
  },
  "message": "SMS sent successfully."
}

---

Features and Enhancements

1. Outbox Tracking:

   • All SMS are logged in the Outbox, regardless of status (sent, failed, pending).

   • Each log includes the SMS details, costs, status, and timestamps.

2. Retry Mechanism:

   • Failed SMS can be retried via the Outbox Resend Endpoint.

   • Maximum retry attempts are configurable to prevent abuse.

3. Cost Tracking:

   • Costs are calculated per unit and stored in the Outbox for each SMS transaction.

   • This ensures reconciliation and transparency for both users and admins.

4. Alerts and Notifications:

   • Users receive notifications for failed SMS or low SMS balances.

   • Configurable alert thresholds and retry limits.

5. Detailed Metadata:

   • Optional fields (tags, customData) allow for flexible tracking and categorization of SMS.

---

Resend SMS Endpoint

• Method: POST

• URL: /api/sms/outbox/resend

Request Body:

{
  "outboxId": "outbox456"
}

Response:

{
  "status": "success",
  "message": "SMS resent successfully.",
  "updatedOutboxEntry": {
    "outboxId": "outbox456",
    "status": "sent",
    "timestamps": {
      "createdAt": "2024-12-15T08:00:00Z",
      "sentAt": "2024-12-15T08:05:00Z",
      "lastAttemptAt": "2024-12-15T08:05:00Z"
    },
    "retryCount": 1
  }
}