SMSAPI Notification Provider

A Medusa v2 notification provider plugin for sending SMS messages through SMSAPI.com, enabling automated SMS notifications for orders, shipments, and customer communications.

Overview

This plugin integrates SMSAPI.io with Medusa v2, allowing you to send SMS notifications to customers for various e-commerce events. SMSAPI is a reliable SMS gateway service that provides global SMS delivery capabilities.

Features

SMS Notifications - Send automated SMS messages to customers
Test Mode - Validate SMS functionality without sending actual messages
Flexible Encoding - Support for UTF-8 and other character encodings
Flash SMS - Send flash/class 0 SMS messages
Message Splitting - Automatic handling of long messages
Priority Sending - Configure message delivery priority
Character Normalization - Automatic character normalization for compatibility
Custom API Endpoint - Override default API endpoint if needed
Country Prefix Support - International phone number support
MedusaJS v2 Compatible - Built for Medusa v2.4.0 and later

Requirements

MedusaJS v2.4.0 or later
Node.js 20 or higher
Active SMSAPI account with API credentials
SMS credits in your SMSAPI account

Installation

Install the plugin using npm:

npm install @yanchesky/medusa-smsapi

Configuration

Environment Variables

Add your SMSAPI credentials to your .env file:

SMSAPI_ACCESS_TOKEN=your_smsapi_access_token
SMSAPI_FROM=YourBrandName

Plugin Configuration

Add the plugin to your medusa-config.ts:

import { Modules } from "@medusajs/framework/utils"

module.exports = defineConfig({
  // ... other config
  modules: {
    [Modules.NOTIFICATION]: {
      resolve: "@medusajs/medusa/notification",
      options: {
        providers: [
          {
            resolve: "@yanchesky/medusa-smsapi",
            id: "smsapi",
            options: {
              channels: ["sms"],
              access_token: process.env.SMSAPI_ACCESS_TOKEN,
              from: process.env.SMSAPI_FROM,
              // Optional settings
              encoding: "utf-8", // Default encoding
              test: false, // Enable test mode
              flash: false, // Send as flash SMS
              normalize: true, // Normalize characters
              fast: false, // Priority sending
            },
          },
        ],
      },
    },
  },
})

Usage

Sending SMS Notifications

Use the notification service to send SMS messages:

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const notificationModuleService = req.scope.resolve("notification")

  await notificationModuleService.createNotifications({
    to: "+48123456789", // Phone number with country prefix
    channel: "sms",
    template: "order-placed", // Required but not used by plugin
    data: {
      message: "Your order has been placed successfully!",
    },
  })

  res.json({ success: true })
}

Notification Events

Common use cases for SMS notifications:

Order Confirmation - Notify customers when orders are placed
Shipment Updates - Send tracking information
Delivery Notifications - Alert customers about delivery
Order Status Changes - Update customers on order progress
Authentication - Send OTP codes for verification
Abandoned Cart - Remind customers about incomplete purchases

Configuration Options

Required Options

access_token - Your SMSAPI access token
from - Sender name/number (max 11 characters for alphanumeric)
channels - Array of channels, typically ["sms"]

Optional Options

encoding (string) - Character encoding, default: "utf-8"
test (boolean) - Enable test mode (no actual SMS sent), default: false
flash (boolean) - Send as flash/class 0 SMS, default: false
normalize (boolean) - Normalize characters for compatibility, default: true
fast (boolean) - Enable priority sending, default: false
max_parts (number) - Maximum message parts for long SMS
api_endpoint (string) - Custom API endpoint (advanced)

Test Mode

Enable test mode to validate your integration without sending actual SMS:

{
  resolve: "@yanchesky/medusa-smsapi",
  options: {
    // ... other options
    test: true, // Test mode enabled
  },
}

In test mode:

SMS messages are validated but not sent
No SMS credits are consumed
You can verify message formatting and flow
Check logs for message details

Phone Number Format

Always include the country prefix:

// Correct formats
"+48123456789"  // Poland
"+1234567890"   // USA
"+44123456789"  // UK

// Incorrect (missing country prefix)
"123456789"     // Will fail

Message Types

Standard SMS

Regular SMS messages with standard delivery:

{
  flash: false,
  fast: false,
}

Flash SMS

Display immediately on screen without saving:

{
  flash: true,
}

Priority SMS

Higher priority delivery:

{
  fast: true,
}

Character Encoding

The plugin supports various encodings:

UTF-8 - Unicode support for international characters
ISO-8859-1 - Western European characters
Windows-1252 - Windows encoding

Enable character normalization to automatically convert special characters:

{
  normalize: true, // Converts ą→a, ę→e, etc.
}

Long Messages

SMS messages longer than 160 characters are automatically split:

Standard SMS: 160 characters
Unicode SMS: 70 characters
Multi-part SMS: 153/67 characters per part

Optionally limit the number of parts:

{
  max_parts: 3, // Maximum 3 SMS parts
}

Best Practices

Test First - Always use test mode before production
Message Length - Keep messages concise to avoid multi-part SMS charges
Country Codes - Always include country prefixes
Sender ID - Use recognizable brand name (max 11 characters)
Credits - Monitor SMSAPI account credits
Error Handling - Implement proper error handling for failed deliveries

Links

See all guides