SMS notifications¶
Applies to: Owner, Administrator and any role with Notifications.Manage; SuperAdmin / server administrator for provider configuration. Last reviewed: 2026-11-18.
SMS is an optional, prepaid channel for the messages the notification engine sends. This page explains what SMS is used for, what a school needs before it works, how credits are counted and what happens when an SMS fails.
1. What SMS is used for¶
SMS is an optional extra channel for the messages the notification engine sends: Student Welcome, Lesson Booking Confirmation, Lesson Reminder, Driving Test Reminder, Lesson Rescheduled, Lesson Cancelled, Lesson Request Declined, Payment Received and Payment Reminder.
SMS is not used for: Invoice Issued, Lesson Completed, quotes, receipts sent manually, account emails, or anything DriveFlow sends to the school.
The SMS text is the plain-text version of the email (greeting, the lines of detail, the school name). It is not shortened, so most messages are longer than one SMS part. See section 5.
2. Provider¶
- The provider registered in the API is
VodacomSmsService(Vodacom Messaging HTTP API). TwilioSmsServiceandAzureSmsServiceexist in the code but are not registered and not used.- One provider account serves every school. A school cannot enter its own SMS account or sender name.
Platform configuration (server administrator)¶
Configuration section VodacomSms:
| Setting | Purpose | Default in code |
|---|---|---|
Enabled |
Master switch for real sending | false |
BaseUrl |
Provider address | Vodacom messaging address |
SendPath |
Path for a send request | api/v1/messages |
ApiKey |
Bearer key, if the account uses one | empty |
Username, Password |
Basic sign-in, used when no API key is set | empty |
SenderId |
Sender name or short code | DriveFlow |
DefaultCountryCode |
Dialling code added to local numbers | 27 |
TimeoutSeconds |
Request timeout | 15 |
There is no page in the application for these settings.
A disabled provider is still logged as Sent
When Enabled is false the service writes "[SMS disabled] Vodacom SMS is not enabled; message to ... was not sent." to the server log and returns normally. The notification engine therefore records the message as Sent, and a credit is still taken. On a test or staging system the Notification Log is not proof that an SMS left the building.
3. What a school needs before SMS works¶
All of the following must be true
- The school's plan includes the SMS feature.
- On a paid plan, the school has SMS credits left. (On a free trial, add-ons work without payment.)
- SMS is switched on under Settings > Notifications > Notification Channels.
- The SMS box is ticked on the message's row, and the row is Enabled.
- The student (or instructor) has a phone number on their record.
- The platform has the provider enabled.
Which plans include SMS is set in the plan data, not in this code; see the subscription documentation.
4. Switching SMS on (school)¶
Who: Notifications.Manage.
- Open Settings, then the Notifications tile. Page title: Notification Settings.
- In Notification Channels, switch SMS on.
- If your plan does not include it, the switch is disabled and the card shows "SMS is not included in your plan. Upgrade under Settings > Subscription to use it."
- If you have run out of credits it shows "You have no SMS credits left. Buy an SMS bundle under Settings > Billing to send SMS."
- In Student Notifications, tick the SMS box on each message you want sent by SMS. The boxes are disabled until the SMS channel switch is on.
- Click Save Changes. You should see "Notification settings saved successfully."
The API checks the plan again on save. Saving with SMS on and no SMS feature is refused.
Screenshot to be added
Screen: Notification Settings. Should show: Notification Channels with SMS switched on and the SMS column ticked for Lesson Reminder.
Staff messages (New Lesson Assigned, Lesson Rescheduled, Lesson Cancelled) have only an on/off switch on the web page, so SMS cannot be ticked for them there. The owner's settings screen in the mobile app does show Email, SMS and WhatsApp boxes for those messages; see Notification settings.
5. Credits and cost¶
SMS is sold as a prepaid add-on: the school buys bundles of credits under Settings > Billing. The Billing page says: "Each SMS uses one credit (a long message uses one per 153 characters). Credits don't expire; SMS stops when they run out."
How credits are counted (SmsCreditService):
| Message content | One part up to | Longer messages |
|---|---|---|
| Standard characters (GSM set) | 160 characters | 1 credit per 153 characters |
| Any other character (for example an accented letter outside the GSM set, an emoji) | 70 characters | 1 credit per 67 characters |
Sequence for each SMS:
flowchart TD
A["Message ready"] --> B["Count parts, then take that many credits<br/>(one database update, so two messages<br/>can never spend the same credit)"]
B -- "not enough credits" --> F1["Log row: Failed<br/>No SMS credits left. Buy an SMS bundle under Settings > Billing."]
B --> C["Send through the provider"]
C -- "provider error" --> F2["Credits given back<br/>Log row: Failed with the provider's text"]
C --> D["Log row: Sent"]
- If a message needs 3 credits and only 2 are left, it is not sent and no credits are taken.
- When the balance reaches 0 the SMS feature switches off for the school until a bundle is bought. The Notifications page then shows the "no SMS credits left" text.
- A bundle is added to the balance when the PayFast payment is confirmed (
SubscriptionPaymentProcessor). The school is emailed the paid invoice. - If the platform has no active prepaid SMS add-on defined at all, SMS is not metered and no credits are taken.
Example¶
A lesson reminder with instructor, vehicle and pickup lines is about 250 standard characters, so it uses 2 credits. A school that reminds 40 students a week uses about 80 credits a week on reminders alone.
Tip
Most messages use 2 or more credits. Tick SMS only for the messages that matter, so your credits last longer.
6. Phone numbers¶
Numbers are sent to the provider in international format without the plus sign. PhoneNumberNormalizer converts what staff typed:
| Stored on the record | Sent as (default country 27) |
|---|---|
0821234567 |
27821234567 |
+27 82 123 4567 |
27821234567 |
0027821234567 |
27821234567 |
27821234567 |
27821234567 |
821234567 |
27821234567 |
A number with no digits fails with "'...' is not a valid destination number." Numbers in another country must be stored with a leading + and country code, otherwise 27 is added.
The Notification Log shows the number exactly as stored on the record, not the converted one.
7. Timing, failures and retries¶
- SMS goes out at the same moment as the email for the same event: immediately for bookings and payments, at the reminder time for reminders.
- Quiet hours apply in the same way as for email (see Notification settings).
- "Sent" means the provider's API accepted the request. DriveFlow does not receive delivery receipts from the network.
- A failure is logged with the provider's response, for example "Vodacom SMS send failed with status 401: ...". Credits are refunded.
- Nothing is retried.
8. Limitations and notes¶
- No delivery receipts; no inbound SMS.
- The school cannot choose the sender name.
- SMS text is not trimmed to one part.
- A disabled provider is logged as Sent and uses a credit (section 2).
- Payment reminder SMS is sent only after the reminder email succeeded, and only for invoices that belong to a student (not walk-in customers).
- The caption "SMS can be enabled when an SMS provider is configured." on the settings page is static text; the page does not check the provider.