SMS Module Documentation

Overview

The SMS Module is the notification router. It abstracts the complexity of multiple gateways (Hormuud, Somtel, WhatsApp) and provides a unified API for the rest of the system to "Send Message". It features Intelligent Routing to save costs by choosing the correct local carrier.

Architecture

Core Services (app/Domain/Sms)

SmsRouter (SmsRouter.php)

Purpose: Determines which pipe to send the message through.

Key Methods:

route(phone, property)

Returns the SmsChannel.

• Logic:
  1. Normalization: Cleans phone to international format (252...).
  2. International: If not 252 (Somalia), routes to WhatsApp.
  3. Local: Checks prefixes.
     • 61, 68, 77 -> Hormuud.
     • 62 -> Somtel.
     • Critique: This map is currently hardcoded in a protected array $defaultPrefixMap.

SmsService (SmsService.php)

Purpose: Facade for delivery.

Key Methods:

send(templateKey, phone, context)

• Logic:
  1. Locates Template.
  2. Compiles Content (Replace ).
  3. Calls Router.
  4. Dispatches Job to Worker.

---

Integration

Provider Configs

Channels are configured via sms_channels table, but the Driver Factory logic often requires code changes to support new providers.

Provider	Type	API Type
Hormuud	SMS	Bearer Token
Somtel	SMS	REST
Meta	WhatsApp	Graph API

---

Audit Findings & Improvements

Strengths

• Cost Optimization: The automatic routing to Hormuud for Hormuud numbers (On-Net) vs Somtel (Off-Net) can save ~30% in SMS costs.
• International Fallback: Automatically upgrading international numbers to WhatsApp is smart, as international SMS is unreliable and expensive.

Issues Identified

Major

• Hardcoded Prefix Map: The SmsRouter contains a hardcoded array of prefixes. If a carrier releases a new prefix range (e.g. 25263), the code must be deployed to support it.
  • Fix: Move prefix mapping to the database (sms_carriers table).

Minor

• Driver Factory: To add a new Gateway (e.g. Twilio), you must modify the core SmsService class code.

---

Module Version

Version: 1.0 Status: Stable