Medusa Twilio SMS Plugin (v2 Compatible)

A production-ready Twilio SMS notification provider for Medusa v2 that enables sending SMS notifications to customers.

Features

• Send SMS notifications using Twilio's messaging API
• Support for MMS (multimedia messages) via mediaUrl
• Full integration with Medusa v2's notification module architecture
• Type-safe implementation using TypeScript
• Support for both direct phone numbers and messaging service SIDs
• Automatic retry logic with configurable attempts
• Comprehensive error handling and validation
• E.164 phone number format validation
• Production-grade logging
• Media URL validation for MMS

Prerequisites

• Medusa v2 backend
• Twilio account with:
  • Account SID
  • Auth Token
  • Either a phone number for sending SMS OR a Messaging Service SID

Installation

yarn add medusa-twilio-sms

Configuration

Add the following environment variables to your .env file:

Option 1: Using a Phone Number (recommended)

TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_FROM_NUMBER=+1234567890

Option 2: Using a Messaging Service SID

TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_MESSAGE_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

In your medusa-config.ts:

import { defineConfig } from '@medusajs/framework/utils'

export default defineConfig({
  projectConfig: {
    // ... other config
  },
  modules: [
    {
      resolve: "@medusajs/medusa/notification",
      options: {
        providers: [
          {
            resolve: "medusa-twilio-sms",
            id: "twilio-sms",
            options: {
              channels: ["sms"],
              account_sid: process.env.TWILIO_ACCOUNT_SID,
              auth_token: process.env.TWILIO_AUTH_TOKEN,
              // Use either from_number OR messaging_service_sid
              from_number: process.env.TWILIO_FROM_NUMBER,
              // messaging_service_sid: process.env.TWILIO_MESSAGE_SERVICE_SID,
            }
          }
        ]
      }
    }
  ]
})

Usage

In a Workflow

import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk";
import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk";
import { Modules } from "@medusajs/framework/utils";

const sendSmsStep = createStep(
  "send-sms-notification",
  async ({ phoneNumber, message }, { container }) => {
    const notificationModuleService = container.resolve(Modules.NOTIFICATION);

    await notificationModuleService.createNotifications({
      to: phoneNumber,
      channel: "sms",
      content: {
        text: message
      }
    });

    return new StepResponse({ success: true });
  }
);

export const sendSmsWorkflow = createWorkflow(
  "send-sms-workflow",
  ({ phoneNumber, message }) => {
    sendSmsStep({ phoneNumber, message });
    return new WorkflowResponse({ success: true });
  }
);

With Media (MMS)

await notificationModuleService.createNotifications({
  to: "+1234567890",
  channel: "sms",
  content: {
    text: "Check out this image!"
  },
  data: {
    mediaUrl: ["https://example.com/image.jpg"]
  }
});

Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | account_sid | string | Yes | Your Twilio Account SID | | auth_token | string | Yes | Your Twilio Auth Token | | from_number | string | No* | The Twilio phone number to send from | | messaging_service_sid | string | No* | Your Twilio Messaging Service SID | | max_retries | number | No | Maximum retry attempts for failed sends (default: 3) | | retry_delay | number | No | Base delay in ms between retries (default: 1000) |

*Note: You must provide either from_number OR messaging_service_sid, but not both.

Production Considerations

Phone Number Validation

The plugin validates all phone numbers to ensure they're in E.164 format (+1234567890). This helps prevent errors and ensures compatibility with Twilio's API.

Error Handling

The plugin distinguishes between different types of errors:

• Validation errors (20000-20999): These are not retried as they indicate invalid input
• Network/temporary errors: These are automatically retried with exponential backoff

Retry Logic

Failed SMS sends are automatically retried with configurable attempts and delays:

{
  max_retries: 3,        // Default: 3 attempts
  retry_delay: 1000      // Default: 1 second base delay
}

Logging

The plugin provides comprehensive logging at different levels:

• INFO: Successful operations
• DEBUG: Detailed operation flow
• WARN: Non-critical issues (e.g., invalid media URLs)
• ERROR: Failed operations with details

Security Best Practices

1. Environment Variables: Always store sensitive credentials in environment variables
2. Token Security: Never commit auth tokens to version control
3. Phone Number Privacy: Be mindful of logging phone numbers in production
4. Rate Limiting: Consider implementing rate limiting at the application level

Testing

Run the test suite:

npm test
# or
npm run test:coverage

Monitoring

For production environments, monitor:

• SMS delivery rates
• Error rates and types
• Retry patterns
• Response times

Troubleshooting

Common Issues

1. "The requested resource was not found"

   • Verify your Account SID is correct
   • Ensure your account has SMS capabilities enabled

2. "Invalid phone number"

   • Ensure phone numbers are in E.164 format (+1234567890)
   • Verify the recipient's country is supported

3. "Authentication error"

   • Double-check your auth token
   • Ensure no extra spaces in credentials

License

MIT