SelfHosted SMS for WooCommerce

Version: 1.0

Send SMS notifications to WooCommerce customers using your own SelfHosted SMS server. This plugin integrates seamlessly with WooCommerce to send order status notifications, and provides hooks for developers to send custom SMS messages.

Features

• Order Notifications: Automatically send SMS when order status changes
• Customizable Templates: Use placeholders to personalize messages
• Admin Notifications: Get SMS alerts for new orders
• SMS Log: Track all sent messages with status
• Developer Friendly: Comprehensive hooks and functions for custom implementations
• Opt-out Support: Allow customers to opt out of SMS notifications
• Custom Order Status: Includes a "Shipped" status out of the box

Requirements

• WordPress 5.8 or higher
• PHP 7.4 or higher
• WooCommerce 5.0 or higher (for order notifications)
• A SelfHosted SMS server instance

Installation

1. Download the plugin and extract it to /wp-content/plugins/api-to-sms/
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to SelfHosted SMS > Settings to configure your API connection
4. Enter your SelfHosted SMS server URL and API token
5. Test the connection to ensure it works
6. Configure your notification preferences and message templates

Configuration

API Settings

Setting	Description
API URL	Your SelfHosted SMS server URL (e.g., https://sms.example.com)
API Token	Your 64-character API token from the SelfHosted SMS dashboard

Notification Settings

• Enable Order Notifications: Toggle SMS notifications on/off
• Notify on Status: Select which order statuses trigger SMS
• SMS Opt-out: Show checkbox at checkout for customers to opt out

Message Templates

Customize the message sent for each order status. Use placeholders like {customer_name} and {order_id} to personalize messages.

Available Placeholders

Order Placeholders

Placeholder	Description
{order_id}	Order ID/Number
{order_number}	Order Number
{order_total}	Order Total (formatted)
{order_date}	Order Date
{order_status}	Order Status
{customer_name}	Customer First Name
{customer_first}	Customer First Name
{customer_last}	Customer Last Name
{customer_full}	Customer Full Name
{customer_email}	Customer Email
{customer_phone}	Customer Phone
{billing_address}	Billing Address
{shipping_address}	Shipping Address
{payment_method}	Payment Method
{shipping_method}	Shipping Method
{item_count}	Number of Items
{first_item}	First Item Name
{tracking_number}	Tracking Number (if available)
{tracking_url}	Tracking URL (if available)
{order_url}	Order View URL

Shop Placeholders

Placeholder	Description
{shop_name}	Shop Name
{shop_url}	Shop URL

User Placeholders

Placeholder	Description
{user_id}	User ID
{username}	Username
{user_email}	User Email
{user_name}	Display Name
{first_name}	First Name
{last_name}	Last Name

Developer API

Functions

Send a single SMS

$result = shsms_send_sms( '+1234567890', 'Hello from WordPress!' );

if ( is_wp_error( $result ) ) {
    echo 'Error: ' . $result->get_error_message();
} else {
    echo 'SMS queued successfully!';
}

Send SMS to WooCommerce order customer

// Send SMS with order placeholders
$result = shsms_send_order_sms(
    $order_id,
    'Hi {customer_name}, your order #{order_id} is ready for pickup!'
);

Send SMS to WordPress user

// Send SMS to user with placeholders
$result = shsms_send_user_sms(
    $user_id,
    'Welcome {first_name}! Your account is ready.',
    '+1234567890' // Optional - uses billing_phone meta if not provided
);

Send bulk SMS

$messages = array(
    array( 'phone' => '+1234567890', 'message' => 'Hello!' ),
    array( 'phone' => '+0987654321', 'message' => 'Hi there!' ),
);
$result = shsms_send_bulk( $messages );

Check if SMS is available

if ( shsms_is_available() ) {
    // SMS is configured and ready
    shsms_send_sms( $phone, $message );
}

Using the Message Class

// Create a message with placeholders
$message = SHSMS_Message::from_template(
    'Hi {customer_name}, your order #{order_id} total is {order_total}'
)
    ->set_from_order( $order )
    ->parse();

// Or set custom placeholders
$message = SHSMS_Message::from_template( 'Hello {name}!' )
    ->set( 'name', 'John' )
    ->parse();

// Set multiple placeholders at once
$message = SHSMS_Message::from_template( 'Hi {first} {last}!' )
    ->set_many( array(
        'first' => 'John',
        'last'  => 'Doe',
    ) )
    ->parse();

Hooks Reference

Actions

Hook	Parameters	Description
shsms_init	$plugin	Fires after plugin is initialized
shsms_activated	-	Fires after plugin is activated
shsms_deactivated	-	Fires after plugin is deactivated
shsms_before_send	$phone, $message	Fires before sending an SMS
shsms_after_send	$phone, $message, $result	Fires after sending an SMS
shsms_send_success	$response, $messages	Fires when SMS is queued successfully
shsms_send_failed	$error, $messages	Fires when SMS sending fails
shsms_before_order_sms	$order, $message	Fires before sending order SMS
shsms_after_order_sms	$order, $message, $result	Fires after sending order SMS
shsms_before_user_sms	$user, $message	Fires before sending user SMS
shsms_after_user_sms	$user, $message, $result	Fires after sending user SMS
shsms_before_send_bulk	$messages	Fires before bulk SMS
shsms_after_send_bulk	$messages, $result	Fires after bulk SMS
shsms_sms_skipped_opt_out	$order, $status	Fires when SMS is skipped due to opt-out
shsms_woocommerce_init	$woocommerce	Fires after WooCommerce hooks are initialized

Filters

Hook	Parameters	Description
shsms_send_phone	$phone, $message	Filter phone number before sending
shsms_send_message	$message, $phone	Filter message text before sending
shsms_prepare_message	$message, $index	Filter individual message before API call
shsms_before_send_bulk	$messages	Filter all messages before sending
shsms_order_placeholders	$placeholders, $order	Filter order placeholders
shsms_user_placeholders	$placeholders, $user	Filter user placeholders
shsms_message_placeholders	$placeholders, $template	Filter placeholders before parsing
shsms_parsed_message	$message, $template, $placeholders	Filter final parsed message
shsms_should_send_order_sms	$send, $order, $old_status, $new_status	Control whether to send order SMS
shsms_order_status_template	$template, $status, $order	Filter message template for order status
shsms_admin_new_order_message	$message, $order	Filter admin notification message
shsms_available_placeholders	$placeholders	Filter available placeholders list
shsms_notification_statuses	$statuses	Filter available notification statuses
shsms_api_request_args	$args, $endpoint, $body	Filter API request arguments
shsms_remaining_sms	$remaining	Filter remaining SMS count

Examples

Add custom placeholder

add_filter( 'shsms_order_placeholders', function( $placeholders, $order ) {
    // Add custom discount placeholder
    $placeholders['discount_total'] = $order->get_discount_total();

    // Add custom meta
    $placeholders['gift_message'] = $order->get_meta( '_gift_message' );

    return $placeholders;
}, 10, 2 );

Modify phone number format

add_filter( 'shsms_send_phone', function( $phone, $message ) {
    // Add country code if missing
    if ( strpos( $phone, '+' ) !== 0 ) {
        $phone = '+1' . $phone; // Add US country code
    }
    return $phone;
}, 10, 2 );

Skip SMS for certain conditions

add_filter( 'shsms_should_send_order_sms', function( $send, $order, $old_status, $new_status ) {
    // Don't send SMS for orders under $10
    if ( $order->get_total() < 10 ) {
        return false;
    }

    // Don't send SMS for local pickup orders
    if ( $order->has_shipping_method( 'local_pickup' ) ) {
        return false;
    }

    return $send;
}, 10, 4 );

Custom order status SMS

// Send custom SMS when order is marked as shipped
add_action( 'woocommerce_order_status_shipped', function( $order_id ) {
    $order = wc_get_order( $order_id );

    // Get tracking info from your shipping plugin
    $tracking_url = $order->get_meta( '_tracking_url' );

    $message = SHSMS_Message::from_template(
        'Hi {customer_name}, your order #{order_id} has shipped! ' .
        'Track at: ' . $tracking_url
    )
        ->set_from_order( $order )
        ->parse();

    shsms_send_sms( $order->get_billing_phone(), $message );
});

Log all SMS to custom table

add_action( 'shsms_after_send', function( $phone, $message, $result ) {
    global $wpdb;

    $wpdb->insert( $wpdb->prefix . 'my_sms_log', array(
        'phone'      => $phone,
        'message'    => $message,
        'success'    => ! is_wp_error( $result ),
        'error'      => is_wp_error( $result ) ? $result->get_error_message() : '',
        'created_at' => current_time( 'mysql' ),
    ) );
}, 10, 3 );

API Reference

Endpoints

The plugin communicates with your SelfHosted SMS server using these endpoints:

Method	Endpoint	Description
POST	/{api_token}/queue	Queue SMS messages for sending
GET	/{api_token}/get_messages	Retrieve pending messages
POST	/{api_token}/status	Update message status (batch)
POST	/{api_token}/status/{hash}	Update single message status

Request Format

Queue Messages

{
    "messages": [
        {
            "phone": "+1234567890",
            "message": "Hello World!"
        }
    ]
}

Response Format

{
    "ok": true,
    "queued": 1,
    "failed": 0,
    "items": [
        {
            "phone": "+1234567890",
            "text": "Hello World!",
            "hash": "abc123def456"
        }
    ],
    "errors": []
}

Phone Number Format

• Must be 6-20 digits
• Can optionally start with +
• Examples: +1234567890, 1234567890

Message Limits

• Maximum message length: 1000 characters
• Messages exceeding the limit will be truncated

Troubleshooting

Connection Failed

1. Verify your API URL is correct and accessible
2. Check that your API token is valid (64 characters)
3. Ensure your server allows outgoing HTTPS connections
4. Check if your SelfHosted SMS server is running

SMS Not Sending

1. Check the SMS Log for error messages
2. Verify the phone number format is correct
3. Ensure you have SMS credits/quota available
4. Check if the customer opted out of SMS

Order Notifications Not Working

1. Verify WooCommerce is active
2. Check that the order status is enabled in settings
3. Ensure the order has a valid billing phone number
4. Check if the customer opted out at checkout

Changelog

1.0.0

• Initial release
• WooCommerce order notifications
• Message templates with placeholders
• Admin notifications for new orders
• SMS log and tracking
• Developer hooks and functions
• Custom "Shipped" order status

License

GPL v2 or later

Author

CODE CODAC WEB SRL

• Country: Romania
• Created by: Dan
• Website: https://codecodac.com

Support

For support, please visit https://apitosms.com or open an issue on GitHub.