Skip to main content

SMS Integration (BulkSMS)

The backend uses BulkSMS API for sending SMS messages, primarily for OTP verification codes.

Configuration​

Environment Variables​

BULKSMS_TOKEN_ID=your-token-id
BULKSMS_TOKEN_SECRET=your-token-secret
BULKSMS_BASIC_AUTH=Authorization: Basic base64encoded

The BULKSMS_BASIC_AUTH should contain the full Authorization header value.

Rate Limiting​

The SMS sending is rate-limited to prevent abuse:

  • Per User: 1 SMS per minute
  • Daily Limit: 30 SMS per user per day
  • Daily limit resets at midnight UTC

Rate limits are tracked in the SmsRateLimit database table.

Usage​

Sending OTP​

When a user requests an OTP code, the system:

  1. Checks rate limits for the phone number
  2. Generates a 5-digit OTP code
  3. Sends SMS via BulkSMS API
  4. Records the SMS in the rate limit tracker
  5. Returns success/failure response

API Endpoint​

POST /api/auth/send-otp

See API Endpoints for details.

SMS Service​

The SMS service is located at:

src/services/bulksms.service.ts

Functions:

  • sendSMS(phoneNumber, message) - Generic SMS sending
  • sendOTPviaSMS(phoneNumber, otpCode) - OTP-specific wrapper

Rate Limit Service​

Rate limiting logic is in:

src/services/sms-rate-limit.service.ts

Functions:

  • checkSmsRateLimit(phone) - Check if SMS can be sent
  • recordSmsSent(phone) - Record SMS after sending
  • getRemainingSmsCount(phone) - Get remaining SMS count for today

Error Handling​

If SMS sending fails:

  • OTP is still saved to database (for development/testing)
  • Error is logged to console
  • In production, OTP code is not logged
  • User receives appropriate error message

Testing​

In development, if SMS sending fails, the OTP code is logged to console for testing purposes:

📱 OTP for +264812345678: 12345

In production, OTP codes are never logged.