CloudWave SMS Notifications WHMCS Module Documentation

Overview

Module Name: CloudWave SMS Notifications
Version: 2.5
Author: CloudWave Hosting
Purpose: The CloudWave SMS Notifications module integrates with WHMCS to send SMS notifications to clients and admins for various WHMCS events using the CloudWave BulkSMS API (Bangladesh only). It supports customizable message templates, multiple admin phone numbers, enables/disables options for each event, and admin-only SMS logging. The module is designed to enhance communication by notifying clients and admins of key events such as invoice creation, payment, ticket updates, and more.

Features

  • Supported Events:
    • Client SMS:
      • Invoice Created (InvoiceCreated)
      • Invoice Paid (InvoicePaid)
      • New Client Account Created (ClientAdd)
      • Invoice Cancelled (InvoiceCancelled)
      • Service Suspended (ServiceSuspended)
      • Service Unsuspended (ServiceUnsuspended)
      • Service Terminated (ServiceTerminated)
      • Ticket Opened (TicketOpen)
      • Ticket Closed (TicketClose)
      • Client Ticket Reply (TicketUserReply)
      • Admin Ticket Reply (TicketAdminReply)
    • Admin SMS (sent to two admin phone numbers):
      • Invoice Paid (InvoicePaid)
      • Ticket Opened (TicketOpen)
      • New Order Placed (AddOrder)
  • Enable/Disable Options: Each event (client and admin) has a configurable enable/disable checkbox to control whether SMS notifications are sent.
  • Customizable Templates: Message templates for each event support variables (e.g., {client_name}, {invoice_id}, {company_name}) and include the company name in parentheses at the start of every SMS (e.g., (Your Company)).
  • Multiple Admin Numbers: Supports two admin phone numbers for notifications (admin_phone_number and admin_phone_number_2).
  • Admin SMS Logging: Logs admin SMS (for AdminInvoicePaid, AdminTicketOpen, AdminAddOrder) in the mod_cloudwave_sms_log table, viewable in the WHMCS admin interface.
  • Single SMS Feature: Allows sending one-off SMS to any Bangladesh phone number for testing or manual communication.
  • Phone Number Validation: Ensures phone numbers are valid Bangladesh numbers (e.g., +8801712345678).
  • API Integration: Uses the CloudWave BulkSMS API for reliable SMS delivery.
  • Debug Logging: Optional debug logging for admin SMS to track send status and errors.

System Requirements

  • WHMCS Version: Compatible with WHMCS 7.x and 8.x.
  • PHP Version: PHP 7.2 or higher.
  • Database: MySQL/MariaDB (used by WHMCS).
  • API Access: CloudWave BulkSMS API token and sender ID (Bangladesh-specific).
  • Server Requirements:
    • cURL extension enabled for API requests.
    • Write permissions for module files in /path/to/whmcs/modules/addons/cloudwave_sms/ and /path/to/whmcs/includes/hooks/.
  • Phone Numbers: Valid Bangladesh phone numbers (format: +880 followed by 10 digits).

Installation

  1. Download Module Files:

    • Download Link
    • You will see two module files in the folders: cloudwave_sms.php and cloudwave_sms_hooks.php.

  2. Upload Files:

    • Upload the zip directly to your WHMCS main folder.
    • Unzip it, and the files will be automatically placed in the required folders.
    • Or, Place files manually cloudwave_sms.php in /path/to/whmcs/modules/addons/cloudwave_sms/.
    • and cloudwave_sms_hooks.php in /path/to/whmcs/includes/hooks/

  3. Activate Module:

    • Log in to WHMCS Admin.
    • Navigate to Setup > Addon Modules (or System Settings > Addon Modules in WHMCS 8.x).
    • Locate CloudWave SMS Notifications in the list.
    • Click Activate.

  4. Configure Permissions:

    • After activation, click Configure for the module.
    • Grant access to the appropriate admin roles (e.g., Full Administrator).

  1. Set Up Configuration:

    • Go to Addons > CloudWave SMS Notifications.
    • Configure the settings (see Configuration section below).
    • Save changes.

  1. Verify Database (Optional):

    • The module creates a mod_cloudwave_sms_log table upon activation for admin SMS logging.
    • Run the following SQL to confirm: 
      SHOW TABLES LIKE 'mod_cloudwave_sms_log';
    • Table structure: 
      CREATE TABLE `mod_cloudwave_sms_log` (
    `id` INT AUTO_INCREMENT PRIMARY KEY,
    `event_id` INT,
    `event_type` VARCHAR(50),
    `client_id` INT,
    `phone_number` VARCHAR(20),
    `message` TEXT,
    `status` VARCHAR(20),
    `response` TEXT,
    `sent_at` DATETIME
);

Configuration

The module is configured via the WHMCS Admin interface under Addons > CloudWave SMS Notifications.

Configuration Fields

  1. API Settings:

    • API Token: Your CloudWave BulkSMS API token (required).
    • Sender ID: Your approved sender ID (max 11 characters, required).

  2. Admin Phone Numbers:

    • Admin Phone Number 1: Primary admin phone number (e.g., +8801712345678).
    • Admin Phone Number 2: Secondary admin phone number for InvoicePaid, TicketOpen, and AddOrder notifications (e.g., +8801712345679).
    • Note: Both must be valid Bangladesh numbers (+880 followed by 10 digits).

  3. Enable/Disable Options:

    • Checkboxes to enable/disable SMS for each event (default: enabled):
      • Client SMS:
        • Enable Invoice Created SMS (Client)
        • Enable Invoice Paid SMS (Client)
        • Enable New Client SMS (Client)
        • Enable Invoice Cancelled SMS (Client)
        • Enable Service Suspended SMS (Client)
        • Enable Service Unsuspended SMS (Client)
        • Enable Service Terminated SMS (Client)
        • Enable Ticket Opened SMS (Client)
        • Enable Ticket Closed SMS (Client)
        • Enable Ticket User Reply SMS (Client)
        • Enable Ticket Admin Reply SMS (Client)
      • Admin SMS:
        • Enable Invoice Paid SMS (Admin)
        • Enable Ticket Opened SMS (Admin)
        • Enable New Order SMS (Admin)

  4. Message Templates:

    • Each event has a customizable template with the following defaults (all start with ({company_name})):
      • Invoice Created: ({company_name}) Dear {client_name}, your invoice #{invoice_id} for {invoice_total} is due on {due_date}. Please pay by the due date.
      • Invoice Paid (Client): ({company_name}) Dear {client_name}, your invoice #{invoice_id} for {invoice_total} has been paid successfully. Thank you!
      • Invoice Paid (Admin): ({company_name}) Invoice #{invoice_id} for {invoice_total} paid by {client_name}.
      • New Client: ({company_name}) Dear {client_name}, welcome to {company_name}! Your account #{client_id} has been created successfully.
      • Invoice Cancelled: ({company_name}) Dear {client_name}, your invoice #{invoice_id} for {invoice_total} has been cancelled.
      • New Order (Admin): ({company_name}) New order #{order_id} for {product_name} by {client_name} has been placed.
      • Service Suspended: ({company_name}) Dear {client_name}, your service {product_name} (#{service_id}) has been suspended. Contact {company_name} for details.
      • Service Unsuspended: ({company_name}) Dear {client_name}, your service {product_name} (#{service_id}) has been reactivated by {company_name}.
      • Service Terminated: ({company_name}) Dear {client_name}, your service {product_name} (#{service_id}) has been terminated by {company_name}.
      • Ticket Opened (Client): ({company_name}) Dear {client_name}, your support ticket #{ticket_id} ({ticket_subject}) has been opened with {company_name}.
      • Ticket Opened (Admin): ({company_name}) New ticket #{ticket_id} ({ticket_subject}) opened by {client_name}.
      • Ticket Closed: ({company_name}) Dear {client_name}, your support ticket #{ticket_id} ({ticket_subject}) has been closed by {company_name}.
      • Ticket User Reply: ({company_name}) Dear {client_name}, you have replied to ticket #{ticket_id} ({ticket_subject}) with {company_name}.
      • Ticket Admin Reply: ({company_name}) Dear {client_name}, {company_name} has replied to your ticket #{ticket_id} ({ticket_subject}).
    • Supported Variables:
      • {client_name}: Client's full name.
      • {invoice_id}: Invoice ID.
      • {invoice_total}: Invoice amount.
      • {due_date}: Invoice due date (YYYY-MM-DD).
      • {client_id}: Client ID.
      • {order_id}: Order ID.
      • {product_name}: Product/service name.
      • {service_id}: Service ID.
      • {ticket_id}: Ticket ID.
      • {ticket_subject}: Ticket subject.
      • {company_name}: WHMCS company name (prepended in parentheses).

  5. Debug Logging:

    • Enable Debug Logging: A Checkbox to enable logging for admin SMS in mod_cloudwave_sms_log.

Usage

Sending Automated SMS

  • The module automatically sends SMS for enabled events when triggered in WHMCS.
  • Client SMS: Sent to the client’s phone number (tblclients.phonenumber) for enabled events.
  • Admin SMS: Sent to admin_phone_number and admin_phone_number_2 for InvoicePaid, TicketOpen, and AddOrder if enabled.
  • Example Scenarios:
    • Invoice Created: When an invoice is generated, the client receives an SMS like: (Your Company) Dear John Doe, your invoice #123 for 1000.00 is due on 2025-07-10. Please pay by the due date.
    • Invoice Paid (Admin): When an invoice is paid, admins receive: (Your Company) Invoice #123 for 1000.00 paid by John Doe.
    • Ticket Opened: Both client and admins receive SMS if enabled, with the company name prepended.

Sending Single SMS

  • Navigate to Addons > CloudWave SMS Notifications.
  • Use the Send Single SMS section to send a one-off SMS.
  • Fields:
    • Phone Number: Enter a valid Bangladesh number (e.g., +8801712345678).
    • Message: Enter the message content (company name will be prepended in parentheses).
  • Click Send SMS.
  • The module validates the phone number and sends the SMS via the CloudWave API.

Viewing Admin SMS Logs

  • In Addons > CloudWave SMS Notifications, view the Recent Admin SMS Logs table.
  • Displays logs for admin SMS (AdminInvoicePaid, AdminTicketOpen, AdminAddOrder) with:
    • Date
    • Event Type
    • Event ID
    • Phone Number
    • Message (truncated)
    • Status (Success/Error)
    • Response (API response or error message)

Testing

  1. Verify Configuration:

    • Ensure API Token, Sender ID & Admin phone numbers are set.
    • Check enable/disable settings and templates in Addons > CloudWave SMS Notifications.
    • Run SQL to verify settings: 
      SELECT setting, value FROM tbladdonmodules WHERE module = 'cloudwave_sms';

  2. Test Single SMS:

    • Use the Send Single SMS feature to send a test SMS.
    • Verify that the SMS is received and starts with (Your Company Name).
    • Check mod_cloudwave_sms_log for SingleSMS entries if sent to an admin number.

  3. Test Event-Based SMS:

    • Trigger each event:
      • Create an invoice (InvoiceCreated).
      • Pay an invoice (InvoicePaid).
      • Create a new client (ClientAdd).
      • Cancel an invoice (InvoiceCancelled).
      • Place a new order (AddOrder, admin only).
      • Suspend/unsuspend/terminate a service (ServiceSuspended, ServiceUnsuspended, ServiceTerminated).
      • Open/close/reply to a ticket (TicketOpen, TicketClose, TicketUserReply, TicketAdminReply).
    • Confirm SMS are sent only for enabled events.
    • Verify the admin SMS for InvoicePaid, TicketOpen, and AddOrder are sent to both admin numbers.
    • Check that all SMS start with (Your Company Name).

  4. Test Enable/Disable:

    • Disable specific events (e.g., uncheck Enable Invoice Created SMS (Client)).
    • Trigger the event and confirm that no SMS is sent.
    • Re-enable and verify SMS delivery.

  5. Check Logs:

    • Query mod_cloudwave_sms_log: 
      SELECT * FROM mod_cloudwave_sms_log WHERE event_type LIKE 'Admin%';
    • Confirm only AdminInvoicePaid, AdminTicketOpen, and AdminAddOrder are logged.

Troubleshooting

Common Issues and Solutions

  1. No SMS Sent:

    • Cause: Invalid phone number.
      • Solution: Verify client/admin phone numbers in WHMCS (tblclients.phonenumber, admin_phone_number, admin_phone_number_2). Must be +880 followed by 10 digits.
      • SQL Check: 
        SELECT phonenumber FROM tblclients WHERE id = <client_id>;
SELECT setting, value FROM tbladdonmodules WHERE module = 'cloudwave_sms' AND setting IN ('admin_phone_number', 'admin_phone_number_2');
    • Cause: Event disabled.
      • Solution: Check enable/disable settings in Addons > CloudWave SMS Notifications.
      • SQL Check: 
        SELECT setting, value FROM tbladdonmodules WHERE module = 'cloudwave_sms' AND setting LIKE 'enable%';
    • Cause: API configuration issue.
      • Solution: Verify API Token and Sender ID. Test with Send Single SMS.
      • Log Check: 
        SELECT * FROM mod_cloudwave_sms_log WHERE event_type LIKE 'Admin%' AND status = 'error';

  2. SMS Missing Company Name:

    • Cause: Template missing ({company_name}).
      • Solution: Ensure all templates in Addons > CloudWave SMS Notifications start with ({company_name}).
      • SQL Check: 
        SELECT setting, value FROM tbladdonmodules WHERE module = 'cloudwave_sms' AND setting LIKE '%_template';
    • Cause: The WHMCS company name is not set.
      • Solution: Set the company name in Setup > General Settings > General.
      • SQL Check: 
        SELECT value FROM tblconfiguration WHERE setting = 'CompanyName';

  3. Unexpected SMS:

    • Cause: Incorrect enable/disable settings or an outdated hooks file.
      • Solution: Verify cloudwave_sms_hooks.php version is 2.5 and enable/disable settings are correct.
      • File Check: Confirm file content matches the provided version.
      • SQL Check: 
        SELECT setting, value FROM tbladdonmodules WHERE module = 'cloudwave_sms' AND setting LIKE 'enable%';

  4. API Errors:

    • Cause: Invalid API Token or Sender ID.
      • Solution: Verify credentials in Addons > CloudWave SMS Notifications. Test with Send Single SMS.
    • Cause: API server issues.
      • Solution: Check mod_cloudwave_sms_log for errors like HTTP 401: Unauthorized or cURL Error.
      • SQL Check: 
        SELECT response FROM mod_cloudwave_sms_log WHERE status = 'error';

  5. Logs Not Appearing:

    • Cause: Debug logging disabled or no admin SMS sent.
      • Solution: Enable Debug Logging in settings. Trigger admin SMS events (InvoicePaid, TicketOpen, AddOrder).
      • SQL Check: 
        SELECT * FROM mod_cloudwave_sms_log WHERE event_type LIKE 'Admin%';

Debugging Steps

  • Check Logs: Use the WHMCS Admin interface or SQL query to review mod_cloudwave_sms_log.
  • Test API: Use Send Single SMS to isolate API issues.
  • Verify Hooks: Ensure it cloudwave_sms_hooks.php is correctly deployed and version 2.5.
  • Monitor Events: Use the WHMCS System Activity Log to confirm events are triggered.

Changelog

  • Version 2.5 (2025-06-29):

    • Added enable/disable checkboxes for all client and admin SMS events.
    • Prepended company name in parentheses ({company_name}) to all SMS messages.
    • Removed unused admin templates (e.g., admin_invoice_created_template).
    • Maintained admin SMS for InvoicePaid, TicketOpen, AddOrder only.
    • Updated version in both cloudwave_sms.php and cloudwave_sms_hooks.php.

  • Version 2.4 (Previous):

    • Limited admin SMS to InvoicePaid, TicketOpen, and AddOrder.
    • Removed admin SMS for other events (e.g., InvoiceCreated, ClientAdd).
    • Supported two admin phone numbers.

  • Version 2.3 (Previous):

    • Added support for second admin phone number (admin_phone_number_2).
    • Improved phone number normalisation and validation.

Support

  • Contact: Contact the module author or CloudWave support for assistance.
  • API Support: For API-related issues, contact CloudWave BulkSMS support with your API token.
  • Logs: Provide relevant log entries from mod_cloudwave_sms_log when reporting issues.

Notes

  • The module is designed for Bangladesh phone numbers only (+880 format).
  • Ensure the WHMCS company name is set for proper template substitution.
  • Regularly back up module files and database before updates.
War diese Antwort hilfreich? 0 Benutzer fanden dies hilfreich (0 Stimmen)

Populärste

HetznerCloud Module

HetznerCloud WHMCS Module Documentation Version 1.15 Table of Contents Introduction...