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": "+254712345678",
  "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": "+254712345678",
    "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
  }
}
PreviousBuy SMSNextSend Bulk SMS