Overview
SMSAPI
Send SMS with optional test mode for safe messaging
Medusa v2 SMSAPI Plugin
A notification provider plugin that enables SMS notifications via SMSAPI.com and service for Medusa v2 projects.
Table of Contents
- Features
- Prerequisites
- Installation
- Configuration
- Environment Variables
- Usage
- Configuration Options
- Development
- Contributing
- Support
- License
Features
- SMS Notifications: Send SMS via SMSAPI.io service
- Test Mode: Safe testing without sending actual SMS
Prerequisites
- Medusa v2.4.0+
- Node.js 20+
- SMSAPI.io Account with API access token
- Active SMS credits in your SMSAPI account
Installation
123npm install @yanchesky/medusa-smsapi# oryarn add @yanchesky/medusa-smsapi
Configuration
1. Environment Variables
Create or update your Copy to clipboard.env
file:
12SMSAPI_ACCESS_TOKEN=your_smsapi_access_token_hereSMSAPI_FROM=YourBrand
2. Medusa Configuration
Add the plugin to your Copy to clipboardmedusa-config.ts
:
1234567891011121314151617import { SMSAPIOptions } from '@yanchesky/medusa-smsapi';// ...module.exports = {// ... other configurationsmodules: [// ... other modules{resolve: '@yanchesky/medusa-smsapi/providers/smsapi',dependencies: ['logger'] // Optional in test mode to log sent messagesoptions: {channels: ['sms'], // Required: notification channelsaccess_token: process.env.SMSAPI_ACCESS_TOKEN,from: process.env.SMSAPI_FROM,} satisfies SMSAPIOptions,},],}
Usage
Basic SMS Sending
1234567891011import { Modules } from '@medusajs/framework/utils';// ...const notificationService = container.resolve(Modules.NOTIFICATION);await notificationService.createNotifications([{channel: 'sms',to: '48123456789', // Country prefix is requiredtemplate: 'confrimation' // This is required by Medusa but is not used by the plugin.content: {text: "An SMS message"}}])
Configuration Options
SMSAPIOptions Interface
123456789101112131415161718interface SMSAPIOptions {// Requiredaccess_token: string // Your SMSAPI access tokenfrom: string // Sender name verified by SMSAPIchannels: string[] // Notification channels// Optional Basic Settingsencoding?: string // Message encoding (default: "UTF-8")test?: boolean // Test mode (default: false)api_url?: string // API endpoint (default: "https://smsapi.io/api")// Optional Advanced Settingsflash?: boolean // Flash SMS (default: false)max_parts?: 1-10 // Maximum number of parts a message can be split intonounicode?: boolean // Prevents from sending messages containing special characters.normalize?: boolean // Converts special characters to regular ones. ฤ -> e; ฤ -> cfast?: boolean // Send SMS with the highest priority (default: false)}
Test Mode
Enable test mode to validate your setup without sending actual SMS. In test mode a request to API endpoint will be executed validating credentials and logging sent message.
Local Development
12345678# Run type checkingyarn typecheck# Run lintingyarn lint# Format codeyarn format# Build pluginyarn build
Contributing
All contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (Copy to clipboard
git checkout -b feature/amazing-feature
) - Make your changes
- Run quality checks (Copy to clipboard
yarn typecheck && yarn lint && yarn format:check
) - Commit your changes (Copy to clipboard
git commit -m 'Add amazing feature'
) - Push to the branch (Copy to clipboard
git push origin feature/amazing-feature
) - Open a Pull Request
Development Guidelines
- Follow existing code style and conventions
- Add TypeScript types for all new features
- Include comprehensive error handling
- Update documentation for new features
Support
- ๐ Documentation: Medusa Documentation
- ๐ SMSAPI Docs: SMSAPI.io Documentation
- ๐ Issues: GitHub Issues
License
MIT License
Compatibility
- โ Medusa: v2.4.0+
- โ Node.js: 20+
- โ TypeScript: 5+
- โ OPEN API: Latest API version