The SMS Addon + Admin Secure Documentation

Back up your WHMCS files and database before installing or upgrading.

1. Extract the download and upload its contents into the WHMCS root, preserving the directory structure. The package includes modules/addons/sms_addon, modules/widgets/sms_addon.php, modules/security/sms2fact/sms2fact.php and includes/whmcsnowcore.php.
2. Open System Settings > Addon Modules (Setup > Addon Modules on older installations), activate The SMS Addon and allow the administrator roles that should access it.
3. Open Addons > The SMS Addon and activate your licence. Admin Secure features require the corresponding licence entitlement.
4. Open Settings > All Gateways, enable a gateway, enter its credentials under Active Gateways and save. Assign the countries it should handle, including a default route.
5. Review General Settings and enable only the notification actions you want. Personalise each message using its available tags.
6. Verify a test message before enabling customer notifications. The Debugger gateway can test the workflow without sending a real SMS.

Use the PHP version supported by your WHMCS installation and a compatible ionCube Loader. cURL, JSON, OpenSSL and database support must be available. Allow outbound HTTPS to your gateway and WHMCSnow licensing server.

Upgrading
Back up your files and database, then upload the new package over the existing addon files. Do not deactivate and delete the addon to upgrade it.
The addon applies its storage upgrades when required. Existing gateway settings, custom messages and deliberately blank templates are preserved. New notification types start disabled. Review them in Settings after upgrading.
The new queue stores scheduled send times and avoids automatic retries when provider acceptance is uncertain. Check the Queue page after upgrading. Keep your normal WHMCS system cron working.
Automatic updates use your existing WHMCSnow licensing and update system. Do not run an automatic update on a development installation that must retain unencoded source files.

Enable a gateway under All Gateways. Configure its credentials and country routing under Active Gateways, then save settings. Gateway credentials are encrypted in the database and masked after saving.
Assign country-specific routes as needed and choose one default gateway for all other destinations. A manual send can explicitly select a gateway; automatic routing uses the client’s country where available. Avoid assigning the same country to several gateways.
Check Connection is available where the gateway supports a balance or account check. A successful check does not guarantee delivery to every country or sender ID. Send one test to an authorised number and check the result.
Scheduling is handled by the addon queue, so it does not depend on a gateway’s own scheduling feature.

Under Settings > General Settings, choose the field containing the client mobile number. You can use WHMCS’ phone-number field or a suitable client custom field.
Store numbers in international format, for example +447700900123. Automatic Country Code Prefix can help with national-format numbers when the client country is correct.
To respect client preferences, select your notification custom field and the value that means the client has agreed to receive SMS. The “Just Send” option bypasses this field filter; use it only where appropriate for your notification setup.
If you require a client custom field during registration, mark it Required Field in WHMCS. Test with a client who has both a saved mobile number and the expected preference value. Changing these settings does not collect consent on your behalf.

Open Settings to configure gateway accounts, country routing and general preferences. Client Actions and Admin Actions control which events send messages. Admin Secure contains licensed authentication, IP monitoring and directory-rotation features.

Choose the mobile number and notification preference fields carefully. Set a signature, history retention and domain renewal reminder intervals. Safe Times limits ordinary client notifications to the chosen hours; security alerts send immediately. Click Save Settings after making changes.

The administration interface follows the administrator’s WHMCS My Account > Language setting. English, Arabic, French, German and Spanish interface files are included. Missing translations fall back to English. Arabic uses a right-to-left addon layout.
The mobile-verification page follows the client page language. Provider-specific settings and gateway responses may remain in the provider’s original wording.
SMS templates are separate from the interface language. In Client Actions, use Languages to edit the templates for the client languages you use. Changing an administrator’s language does not translate or overwrite saved SMS messages. Keep placeholder names, such as {firstname}, unchanged.

Normal outgoing notifications and campaigns are processed through the existing WHMCS system cron using the addon’s AfterCronJob hook. Keep the normal WHMCS cron running at the interval recommended for your WHMCS version; no additional SMS cron is required for normal operation.
Future scheduled messages remain waiting until due. Queue health shows due messages, scheduled messages, the oldest due message and the last completed check. It warns when no check has completed for 24 hours, messages are overdue or uncertain/interrupted sends require review.
Security notifications, including verification/2FA codes, password changes and new administrator IP alerts, send immediately and bypass the normal queue and quiet hours. They still require the corresponding action, licence entitlement and gateway configuration.
An interrupted or uncertain send is not automatically retried. Check the provider first to avoid duplicate SMS charges.

Tags are a new feature of the addon, This allow you to personalise the SMS even more with client details.
The following tags are included in the module, each action has there own tags assigned to them.

Action	Tags
Global Tags	{fullname} {firstname} {lastname} {clientemail}
Client Registration	{password}
Password Change	{newpassword}
Invoice Created	{invoiceid} {total} {datecreated} {datedue} {currency_prefix} {currency_suffix}
Invoice Paid	{invoiceid} {paymentmethod} {total} {datecreated} {datepaid} {currency_prefix} {currency_suffix}
Invoice Reminder Invoice Overdue	{invoiceid} {datecreated} {datedue} {total} {currency_prefix} {currency_suffix}
Module Created Module Unsuspend Module Password Change	{serviceid} {domain} {username} {password}
Module Suspend	{serviceid} {domain} {username} {password} {suspendreason}
Domain Registration Domain Transfer Domain Renewal	{domain} {registrar} {regperiod}
Domain Renewal Notices	{domain} {expiredays} {duedate}
Support Ticket Opened Support Ticket Reply	{ticketid} {ticketref} {subject} {message} {deptname} {priority} {status}
New Order Received	{orderid} {ordernumber} {totaldue}
Fraud Order	{orderid}
Cancellation Request Admin Cancellation Request	{type} {reason}
Affiliate Activation	{affiliatelink}
Two-Factor Authentication	{twofactor}
Domain Registration Failed Domain Transfer Failed Domain Renewal Failed	{domain} {registrar} {regperiod} {error}
Admin Secure-New Admin IP	{ip} {admin}
Admin Secure-New Admin Directory	{newadmindir}
Support Ticket Flagged	{ticketid} {ticketref} {subject} {priority} {status}

SMS Addon 6.0.0 additions
Enable each action you want under Client Actions or Admin Actions, then edit its message. Available tags lists placeholders supported by that action; click a tag to insert it into the selected message field.
Invoice messages include {balance} for the remaining invoice balance. Payment-failure and card-expiry actions can be configured independently. Service-termination notifications are available alongside creation, suspension and unsuspension actions.
Client templates can be configured for multiple languages. English defaults are supplied for supported actions, but existing customised or deliberately blank templates are preserved on upgrade. Newly added actions start disabled.
Do not assume a tag from one action is available in another. Avoid including secrets in messages unless you deliberately require that legacy action.

New and updated tags

• Invoice events: {balance} is the remaining invoice balance.
• Service termination: {serviceid} and {domain}, alongside the shared client name/email tags.
• Campaigns: {firstname}, {lastname}, {fullname}, {clientemail}.

Enable Client Mobile verification in General Settings to show a notice at the top of client pages until the saved number is verified. The verification page is index.php?m=sms_addon within your WHMCS installation and requires the client to sign in.
The client requests a code, receives it immediately by SMS and enters it on the page. Codes expire, are single-use and allow a limited number of attempts. Requests have a five-minute cooldown and daily limit.
Verification applies to the saved number. Changing it requires verification again. Disabling the setting hides the notice and the administration-profile verification badge; it does not erase the existing verification record.
Verification proves access to a mobile number. It is separate from permission to send marketing or optional notifications.

Administrators can also send a message from the client summary page. The saved mobile number and verification state are shown when client mobile verification is enabled.

The administration interface follows the administrator’s WHMCS My Account > Language setting. English, Arabic, French, German and Spanish interface files are included. Missing translations fall back to English. Arabic uses a right-to-left addon layout.
The mobile-verification page follows the client page language. Provider-specific settings and gateway responses may remain in the provider’s original wording.
SMS templates are separate from the interface language. In Client Actions, use Languages to edit the templates for the client languages you use. Changing an administrator’s language does not translate or overwrite saved SMS messages. Keep placeholder names, such as {firstname}, unchanged.

Use Send SMS to search for a client or enter international mobile numbers. Choose automatic routing or a specific active gateway. Review the segment count before queueing the message.
Messages provides search, period and status filters. View message opens the saved body, gateway response and provider reference. Resend message queues the saved message to the same recipient using current routing and preserves the original signature once.
Authentication and password-bearing messages cannot be resent from history. Authentication message contents are omitted from the saved log. History retention controls how long message records are kept; choose Keep history if you do not want automatic removal.

Choose Clients, Product or service, Product addon or Domain, then set your filters. Recipient matches update while you change the filters. Leave a selection empty where the page allows all values.
Write the message and insert the available name/email placeholders. The preview and segment estimates help you review the audience; personalisation can change the final length.
Choose As soon as possible or a scheduled date and time in the website/server timezone shown on the page. Review the campaign before queueing it. The addon rechecks eligible recipients and excludes invalid numbers or clients who have opted out.
Queue shows campaign progress. Cancel campaign cancels messages still waiting. Messages already being sent or accepted by a provider cannot be recalled. Duplicate-submission protection prevents the same review request from queueing the campaign twice.

A long text can be billed as several SMS parts. GSM messages usually allow 160 characters in one part or 153 per part when combined. Unicode messages usually allow 70 characters in one part or 67 per combined part. Some GSM extension characters take two character positions.
The addon estimates parts including your configured signature. Personalised client details can change the final length, and the provider determines billing. Confirm the provider’s limits and pricing.
The signature is added to new messages. Resending a saved message preserves its saved text and does not append the signature a second time.

Use Clickatell for a current Clickatell Portal account and Clickatell Legacy only for the older username/password/API-ID integration. The current driver uses Basic HTTP API, not One API.

1. In Clickatell Portal, open My Workspace > SMS > New SMS Setup. Choose API, then the appropriate one-way or two-way setup for your destinations. A one-way setup does not support US recipients.
2. Choose Basic HTTP API and create an HTTP API integration. Start in Sandbox. Standard is suitable for general notifications and campaigns; do not use a priority transactional route for marketing.
3. Enable account fraud protection and allow the hosting server’s actual outbound public IP. This can differ from your website IP or home/VPN address.
4. Enable Delivery Notifications, choose POST, and paste the full private Delivery callback URL shown under SMS Addon > Settings > Active Gateways > Clickatell. Keep the callback token private.
5. Allow enough message parts for your templates. Parts are separately billable SMS segments. Leave phone-number conversion disabled when submitting full international numbers.
6. Copy the API Key into Clickatell’s API Key field in the addon. Leave From blank unless your sender has been approved for the destination.
7. Add and verify a sandbox test number in Clickatell. Keep a positive balance if the portal requires it. Send a test through the addon and confirm handset receipt and Delivered status.
8. When ready for paid traffic, change the integration to Production and save. Assign the default/country routes in the addon and remove overlapping routes from the old gateway.

The internal gateway and callback filenames remain clickatell_new for compatibility. “Accepted” means the provider accepted the request; “Delivered” requires a delivery receipt. Provider account requirements and destination restrictions can change; check the current Clickatell portal guidance.

1. Register for an account at SMS Global - Click here

These gateways use the same single-file gateway interface as the existing integrations, with shared transport and callback helpers. No separate gateway SDK folder is required.

• Plivo: enter your Auth ID, Auth Token and permitted sender. The authenticated callback URL is included automatically when sending.
• Telnyx: enter your API key, sender and messaging profile where required. The authenticated callback URL is included automatically when sending.
• BulkSMS: enter your API token ID and secret. Configure the private addon callback URL in your provider’s webhook settings for sent-message status reports.
• FireText: enter your API key and sender. Configure the private addon callback URL in your FireText delivery-report settings.

Copy callback URLs from Active Gateways rather than constructing them yourself. Your WHMCS System URL must use HTTPS and be reachable by the provider. Sender registration, number ownership, destination permissions and account approval remain provider requirements.
Use a real provider test to confirm end-to-end delivery. Debugger results test addon behaviour, not carrier delivery.

The gateway must support delivery reports and have them configured for the addon to receive final delivery status. Keep the full authenticated callback URL private.

• Queued: waiting for the local worker or provider processing.
• Accepted: the provider accepted the send request; this does not prove handset delivery.
• Delivered: an explicit delivery receipt was received.
• Failed: the request or delivery failed.
• Unknown: acceptance could not be confirmed. Check the provider before sending again, because the message may already have been accepted.

New callback handlers match both gateway and provider reference and protect final receipts against late progress updates. Callbacks do not automatically resend messages. A firewall, invalid callback URL or restrictive security rule can prevent delivery reports even when the SMS arrives.

Admin Secure requires its licence entitlement. Configure the administrator mobile numbers and an active gateway before enabling SMS authentication.
Open WHMCS authentication settings from Settings > Admin Secure > Manage authentication. Make the SMS authentication module available for administrators and/or clients as appropriate. Each user then enrols through their own account’s security settings.
Save the WHMCS backup code privately during enrolment. To recover access without the phone, use Login using Backup Code and save the replacement code shown by WHMCS. Backup codes are single-use.
SMS codes send immediately, expire and have attempt limits. Refreshing the challenge does not send a new code automatically. Test login and recovery before requiring 2FA for other users.

Admin Secure can notify you about new administrator IP addresses and changes to the administration directory. Review trusted administrator IPs and CIDR ranges before enabling monitoring. Security alerts send immediately.
Automatic directory rotation requires the WHMCS configuration file to be writable and a suitable word pack. Set the interval and word-use preference carefully, and keep a backup and server access available.
Review any web-server restrictions, bookmarks, integrations or monitoring tied to the admin URL before using directory rotation. If a change cannot be completed safely, the addon attempts to retain or restore the previous directory configuration.

Debugger simulates gateway outcomes and sends a diagnostic email through WHMCS instead of contacting an SMS carrier. Configure its recipient address, select it explicitly and use a test client/number.
It can exercise accepted, delivered, rejected and uncertain outcomes, along with queue processing, templates and signatures. Use isolated tests when checking expiry, incorrect codes or changing numbers.
A successful Debugger email verifies the addon workflow and mail handoff. It does not prove that a real provider accepts your credentials, that a sender is approved, or that carrier callbacks reach your site. Always finish gateway setup with an authorised real SMS test.

Open the message details and compare its reference and response with your provider dashboard. Check credentials, balance, sender approval, destination permissions, international number format and country routing.
For queued messages, check the WHMCS cron and Queue health. For a missing Delivered status, check provider callback settings, HTTPS reachability and firewall rules.
If status is Unknown or sending was interrupted, check the provider before resending. The addon avoids automatically retrying a request that may already have been accepted.
Support diagnostics in the message dialog can send the selected message and redacted diagnostics to an existing WHMCSnow support ticket. Review what you are sharing and never publish API keys or private callback URLs.