code examples

Sent logo
Sent TeamMay 3, 2025 / code examples / Article

Schedule SMS Messages with Plivo, Node.js & Express: Complete Guide

Learn how to build an SMS scheduling application with Plivo, Node.js, and Express. Send automated appointment reminders, alerts, and time-sensitive notifications with step-by-step code examples.

.env

Build a production-ready Node.js application using Express to schedule SMS messages for future delivery via the Plivo Messages API. Create an API endpoint that accepts scheduling requests, manages pending messages with node-cron, and sends automated appointment reminders at the specified time.

Project Overview and Goals

What You'll Build:

You'll create a backend API service that enables users to schedule SMS messages. The core functionality includes:

  1. An API endpoint (POST /schedule) that accepts SMS scheduling requests (recipient number, message content, desired send time)
  2. A scheduling mechanism (node-cron) that triggers SMS sending at the correct time
  3. Integration with the Plivo Messages API to send SMS messages
  4. Basic in-memory storage for scheduled jobs (with caveats for production discussed)
  5. Error handling, logging, and security considerations

Problem Solved:

Send automated SMS communications at specific future dates and times – such as appointment reminders, follow-up messages, or time-sensitive alerts – without manual intervention when sending.

Technologies Used:

  • Node.js: JavaScript runtime for building server-side applications
  • Express: Minimal and flexible Node.js web application framework for building APIs
  • Plivo Messages API: Communication API for sending messages across various channels, including SMS (uses plivo SDK)
  • node-cron: Simple cron-like job scheduler for Node.js that triggers tasks at specific times
  • dotenv: Manages environment variables securely
  • uuid: Generates unique identifiers for scheduled jobs

Why Plivo?

Plivo provides reliable and scalable communication APIs with extensive features and global reach. The Messages API offers a unified way to handle multiple channels, though this guide focuses on SMS scheduling and appointment reminders.

System Architecture:

text
+-----------+       +-------------------+      +-----------------+      +-----------------+      +--------------+
|   Client  |------>|  Node.js/Express  |----->| Scheduling Logic|----->|  Plivo Service  |----->| Plivo Cloud  |
| (e.g. curl|       |      API Server   |      |   (node-cron)   |      |   (SDK Wrapper) |      | (Messages API|
|  Postman) |<------| (Listens on Port) |<-----| (In-Memory Store|      +-----------------+      +------|-------+
+-----------+       +-------------------+      +-----------------+                                     |
                                                                                                       | SMS
                                                                                                       v
                                                                                                +---------------+
                                                                                                | SMS Recipient |
                                                                                                +---------------+

Prerequisites:

  • Node.js and npm (or yarn) installed on your system (Download Node.js)
  • Plivo API Account to get API credentials and a virtual number (Sign up for Plivo – free credit available for new accounts)
  • Plivo CLI (optional but recommended) for managing applications and numbers – install via npm: npm install -g plivo-cli
  • ngrok (optional) for testing webhooks locally if you extend the app to handle status updates or replies (ngrok Website)
  • Basic knowledge of JavaScript, Node.js, and REST APIs

Final Outcome:

You'll have a running Node.js Express application with a /schedule endpoint that accepts SMS scheduling requests and sends messages at the specified future time using Plivo.

1. Setting Up the Project

Initialize your Node.js project and install the necessary dependencies.

Step 1: Create Project Directory

Create a new directory for your project and navigate into it:

bash
mkdir plivo-sms-scheduler
cd plivo-sms-scheduler

Step 2: Initialize Node.js Project

Initialize the project using npm (or yarn) – the -y flag accepts default settings:

bash
npm init -y

This creates a package.json file.

Step 3: Install Dependencies

Install Express, the Plivo SDK, node-cron, dotenv, and uuid:

bash
npm install express plivo node-cron dotenv uuid
  • express: Web framework
  • plivo: Official Plivo SDK for Node.js
  • node-cron: Task scheduler
  • dotenv: Loads environment variables from a .env file
  • uuid: Generates unique IDs for tracking jobs

Step 4: Project Structure (Recommended)

Create a basic structure for better organization:

bash
mkdir src
mkdir src/routes
mkdir src/services
mkdir src/config
  • src/: Contains your main application code
  • src/routes/: Holds Express route definitions
  • src/services/: Contains business logic (interacting with Plivo or the scheduler)
  • src/config/: Configuration files (Plivo SDK initialization)

Step 5: Create Basic Express Server (src/app.js)

Create app.js inside the src directory with this basic Express setup:

javascript
// src/app.js
require('dotenv').config(); // Load environment variables early
const express = require('express');

const app = express();
const PORT = process.env.PORT || 3000; // Use port from env or default to 3000

// Middleware
app.use(express.json()); // Parse JSON request bodies
app.use(express.urlencoded({ extended: true })); // Parse URL-encoded bodies

// Simple root route for testing
app.get('/', (req, res) => {
    res.status(200).json({ message: 'Plivo SMS Scheduler API is running!' });
});

// --- Routes will be added here later ---

// Start the server
app.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
});

// Export app for potential testing
module.exports = app;

Step 6: Create Start Script

Modify the scripts section in your package.json:

json
// package.json
{
  // ... other properties
  "main": "src/app.js", // Point to your entry file
  "scripts": {
    "start": "node src/app.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  // ... other properties
}

Test the basic server by running npm start and navigating to http://localhost:3000 or using curl http://localhost:3000. You should see the JSON message. Stop the server with Ctrl+C.

2. Setting Up Plivo Credentials and SDK

Get credentials and a virtual phone number to interact with the Plivo API. The Plivo SDK uses Auth ID and Auth Token for authentication.

Step 1: Get Your Plivo API Credentials

  1. Sign up or log in to your Plivo Console
  2. Navigate to your Dashboard – you'll see your Auth ID and Auth Token
  3. Copy these credentials (you'll need them for the .env file)

Step 2: Obtain a Plivo Virtual Number

Get a Plivo phone number to send SMS messages from.

Using the Plivo Console:

  1. Navigate to "Phone Numbers" → "Buy Numbers" in your Plivo Console
  2. Select country, capabilities (SMS), and type
  3. Click "Search" and buy a suitable number – note it down in E.164 format (e.g., +12025551234)

Step 3: Configure Environment Variables

Create .env in your project root (same level as package.json). Never commit this file to Git.

ini
# .env

# Plivo credentials
PLIVO_AUTH_ID=YOUR_AUTH_ID
PLIVO_AUTH_TOKEN=YOUR_AUTH_TOKEN

# Plivo number to send SMS from
PLIVO_SMS_FROM_NUMBER=YOUR_PLIVO_NUMBER

# Optional: port for the server
# PORT=3000

Replace YOUR_AUTH_ID, YOUR_AUTH_TOKEN, and YOUR_PLIVO_NUMBER with your actual values from the Plivo Console.

Add .env to your .gitignore:

text
# .gitignore
node_modules
.env
npm-debug.log

Step 4: Initialize Plivo SDK (src/config/plivoClient.js)

Initialize the SDK instance using your Auth ID and Auth Token:

javascript
// src/config/plivoClient.js
const plivo = require('plivo');

// Validate essential environment variables
if (!process.env.PLIVO_AUTH_ID || !process.env.PLIVO_AUTH_TOKEN) {
    console.error('Error: PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN must be set in .env');
    process.exit(1); // Exit if critical config is missing
}

const client = new plivo.Client(
    process.env.PLIVO_AUTH_ID,
    process.env.PLIVO_AUTH_TOKEN
);

console.log('Plivo SDK initialized successfully.');

module.exports = client;

This creates a Plivo client instance using your Auth ID and Token. Basic checks ensure critical environment variables are present.

3. Implementing the SMS Scheduling Logic with Node-Cron

Use node-cron to run tasks at specific times and a simple in-memory object to track scheduled jobs.

Important Caveat: This in-memory storage is not suitable for production. If the server restarts, all scheduled jobs are lost. For production, use a persistent store like Redis or a database with a dedicated job queue library (e.g., BullMQ, Agenda).

Step 1: Create Scheduler Service (src/services/schedulerService.js)

Create a scheduler service to manage job scheduling and storage:

javascript
// src/services/schedulerService.js
const cron = require('node-cron');
const { v4: uuidv4 } = require('uuid');
const smsService = require('./smsService'); // We will create this next

// In-memory store for scheduled jobs { jobId: { task: cronTask, details: {...} } }
const scheduledJobs = {};

/**
 * Schedule an SMS message to be sent at a specific time.
 * @param {string} recipient - The phone number to send the SMS to.
 * @param {string} message - The content of the SMS.
 * @param {Date} sendAt - The Date object representing when to send the message.
 * @returns {string} - The unique ID of the scheduled job.
 * @throws {Error} - If sendAt is in the past or invalid.
 */
const scheduleSms = (recipient, message, sendAt) => {
    const now = new Date();
    if (!(sendAt instanceof Date) || isNaN(sendAt) || sendAt <= now) {
        throw new Error('Invalid or past date provided for scheduling.');
    }

    const jobId = uuidv4();

    // Use node-cron's ability to schedule based on a Date object
    const task = cron.schedule(sendAt, async () => {
        console.log(`[Scheduler] Executing job ${jobId} at ${new Date()}`);
        try {
            await smsService.sendSms(recipient, message);
            console.log(`[Scheduler] Job ${jobId}: SMS sent successfully to ${recipient}.`);
        } catch (error) {
            console.error(`[Scheduler] Job ${jobId}: Failed to send SMS to ${recipient}. Error: ${error.message}`);
            // Optional: implement retry logic or log for manual intervention
        } finally {
            // Clean up the job from memory after execution (or attempted execution)
            delete scheduledJobs[jobId];
            console.log(`[Scheduler] Job ${jobId} removed from memory.`);
        }
    }, {
        scheduled: true,
        timezone: "Etc/UTC" // Explicitly use UTC or your desired timezone
    });

    scheduledJobs[jobId] = {
        task: task,
        details: {
            jobId,
            recipient,
            message, // Storing message in memory; consider security for sensitive data
            sendAt: sendAt.toISOString(),
            createdAt: now.toISOString()
        }
     };

    console.log(`[Scheduler] SMS for ${recipient} scheduled successfully. Job ID: ${jobId}, Send At: ${sendAt.toISOString()}`);

    // Optional: start the task explicitly if needed
    // task.start(); // Usually not needed with `scheduled: true` and a future date

    return jobId;
};

/**
 * Cancel a previously scheduled job.
 * @param {string} jobId - The ID of the job to cancel.
 * @returns {boolean} - True if cancelled, false if job not found.
 */
const cancelSms = (jobId) => {
    const job = scheduledJobs[jobId];
    if (job) {
        job.task.stop(); // Stop the cron task
        delete scheduledJobs[jobId];
        console.log(`[Scheduler] Job ${jobId} cancelled successfully.`);
        return true;
    }
    console.log(`[Scheduler] Job ${jobId} not found for cancellation.`);
    return false;
};

/**
 * List currently scheduled jobs (for debugging/monitoring).
 * @returns {object[]} - An array of job details.
 */
const listScheduledJobs = () => {
    return Object.values(scheduledJobs).map(job => job.details);
};

module.exports = {
    scheduleSms,
    cancelSms,
    listScheduledJobs,
};

Explanation:

  1. scheduledJobs: Simple in-memory database – keys are jobId, values contain the node-cron task object and job details
  2. scheduleSms:
    • Takes recipient, message, and a Date object (sendAt)
    • Validates sendAt is a valid future date
    • Generates a unique jobId using uuid
    • Uses cron.schedule(sendAt, ...) to schedule the task for the specified date and time – provides a Date object, which node-cron supports for one-off tasks
    • The function passed to cron.schedule runs at sendAt and calls smsService.sendSms
    • Includes basic logging and removes the job from scheduledJobs after execution (using finally)
    • Sets timezone explicitly (UTC recommended for servers)
    • Stores the task and details in scheduledJobs
    • Returns the jobId
  3. cancelSms: Finds a job by ID, stops the cron task using task.stop(), and removes it from memory
  4. listScheduledJobs: Returns details of all pending jobs (useful for admin/status endpoints)

4. Implementing the SMS Sending Service with Plivo API

Encapsulate the Plivo SDK interaction to send SMS messages.

Step 1: Create SMS Service (src/services/smsService.js)

javascript
// src/services/smsService.js
const plivoClient = require('../config/plivoClient'); // Import the initialized SDK client

// Ensure the sender number is configured
const fromNumber = process.env.PLIVO_SMS_FROM_NUMBER;
if (!fromNumber) {
    console.error('Error: PLIVO_SMS_FROM_NUMBER must be set in .env');
    process.exit(1);
}

/**
 * Send an SMS message using the Plivo Messages API.
 * @param {string} recipient - The phone number to send the SMS to (E.164 format recommended).
 * @param {string} message - The content of the SMS.
 * @returns {Promise<object>} - The response from the Plivo API.
 * @throws {Error} - If sending fails.
 */
const sendSms = async (recipient, message) => {
    console.log(`[SMS Service] Attempting to send SMS to ${recipient}`);

    try {
        const response = await plivoClient.messages.create({
            src: fromNumber,
            dst: recipient,
            text: message,
        });

        console.log(`[SMS Service] Message sent successfully. Message UUID: ${response.messageUuid}`);
        return response; // Contains messageUuid

    } catch (error) {
        console.error(`[SMS Service] Error sending SMS to ${recipient}:`, error.response ? error.response : error.message);
        // Rethrow the error so the scheduler knows it failed
        throw new Error(`Failed to send SMS via Plivo: ${error.message}`);
    }
};

module.exports = {
    sendSms,
};

Explanation:

  1. Imports the configured plivoClient instance
  2. Retrieves PLIVO_SMS_FROM_NUMBER from environment variables and exits if not set
  3. sendSms function is async – the SDK call is asynchronous (plivoClient.messages.create returns a Promise)
  4. Uses plivoClient.messages.create with required parameters: src, dst, text
  5. Includes try...catch for error handling – logs detailed errors and rethrows a generic error to signal failure to the scheduler
  6. Logs success, including the messageUuid returned by Plivo (useful for tracking)

5. Building the API Layer (Express Routes for SMS Scheduling)

Create the Express route that uses your scheduler service.

Step 1: Create Schedule Route (src/routes/scheduleRoutes.js)

javascript
// src/routes/scheduleRoutes.js
const express = require('express');
const schedulerService = require('../services/schedulerService');

const router = express.Router();

// POST /api/schedule – schedule a new SMS
router.post('/', (req, res, next) => {
    const { recipient, message, sendAt } = req.body;

    // --- Basic input validation ---
    if (!recipient || !message || !sendAt) {
        return res.status(400).json({ error: 'Missing required fields: recipient, message, sendAt (ISO 8601 format string).' });
    }

    let sendAtDate;
    try {
        sendAtDate = new Date(sendAt);
        if (isNaN(sendAtDate)) {
            throw new Error('Invalid date format.');
        }
    } catch (error) {
        return res.status(400).json({ error: 'Invalid date format for sendAt. Please use ISO 8601 format (e.g., YYYY-MM-DDTHH:mm:ssZ).' });
    }

    const now = new Date();
    if (sendAtDate <= now) {
         return res.status(400).json({ error: 'Scheduled time must be in the future.' });
    }
    // --- End basic validation ---

    try {
        const jobId = schedulerService.scheduleSms(recipient, message, sendAtDate);
        res.status(202).json({ // 202 Accepted: request taken, processing will happen later
            message: 'SMS scheduled successfully.',
            jobId: jobId,
            details: {
                recipient: recipient,
                // message: message, // SECURITY NOTE: avoid returning sensitive message content in production APIs
                sendAt: sendAtDate.toISOString(),
            }
        });
    } catch (error) {
         // Catch errors from schedulerService (e.g., invalid date)
         console.error('[API Route /schedule] Error scheduling SMS:', error);
         // Pass to global error handler or send specific response
         // Send 500 for now, but could be 400 if validation error caught in service
         res.status(500).json({ error: 'Failed to schedule SMS.', details: error.message });
         // Alternatively: next(error); // if using global error middleware
    }
});

// GET /api/schedule – list pending jobs (for admin/debug)
router.get('/', (req, res) => {
    const jobs = schedulerService.listScheduledJobs();
    res.status(200).json({ scheduledJobs: jobs });
});

// DELETE /api/schedule/:jobId – cancel a scheduled job
router.delete('/:jobId', (req, res) => {
    const { jobId } = req.params;
    if (!jobId) {
         return res.status(400).json({ error: 'Job ID is required.' });
    }

    const cancelled = schedulerService.cancelSms(jobId);

    if (cancelled) {
        res.status(200).json({ message: `Job ${jobId} cancelled successfully.` });
    } else {
        res.status(404).json({ error: `Job ${jobId} not found or already executed/cancelled.` });
    }
});

module.exports = router;

Explanation:

  1. Imports express.Router and schedulerService
  2. POST / route:
    • Extracts recipient, message, and sendAt from req.body
    • Basic validation: Checks if fields exist and if sendAt is a valid ISO 8601 date string representing a future time (use express-validator or joi for production)
    • Calls schedulerService.scheduleSms with validated data
    • Responds with 202 Accepted (appropriate for tasks accepted for later processing) and the jobId
    • Note: Response omits message field for security – avoid returning sensitive message content in production APIs
    • Includes basic error handling for validation errors and service errors
  3. GET / route: Calls schedulerService.listScheduledJobs to return pending job details
  4. DELETE /:jobId route: Extracts jobId from req.params, calls schedulerService.cancelSms, returns success or 404 if job not found

Step 2: Mount the Router in app.js

Update src/app.js to use this router.

javascript
// src/app.js
require('dotenv').config();
const express = require('express');
const scheduleRoutes = require('./routes/scheduleRoutes'); // Import the router
// Import other routers if you add more features

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get('/', (req, res) => {
    res.status(200).json({ message: 'Plivo SMS Scheduler API is running!' });
});

// --- Mount API Routes ---
app.use('/api/schedule', scheduleRoutes); // Use the schedule router for paths starting with /api/schedule

// --- Global error handler (example) ---
// Add AFTER your routes
app.use((err, req, res, next) => {
    console.error('[Global Error Handler]:', err.stack || err);
    // Avoid sending stack trace in production
    const statusCode = err.statusCode || 500;
    const message = err.message || 'Internal Server Error';
    res.status(statusCode).json({ error: message });
});

app.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
    // Initialize Plivo SDK (if not already done elsewhere)
    require('./config/plivoClient');
    // Initialize Scheduler (though node-cron tasks start automatically)
    console.log('Scheduler service initialized.');
});

module.exports = app;

This adds scheduleRoutes under the /api/schedule path and includes a basic global error handler middleware.

6. Error Handling, Logging, and Retries

Production apps need more robust error handling beyond the basics included here.

Consistent Error Strategy: Use the global error handler middleware (in app.js) to catch unhandled errors. Define custom error classes if needed (e.g., ValidationError, NotFoundError).

Logging: Replace console.log/console.error with a structured logger like pino or winston. This enables different log levels (debug, info, warn, error), JSON formatting, and sending logs to files or external services.

Example with pino:

bash
npm install pino pino-pretty
javascript
// src/config/logger.js (Example)
const pino = require('pino');
const logger = pino({
    level: process.env.LOG_LEVEL || 'info',
    transport: {
        target: 'pino-pretty', // Makes logs readable in development
        options: {
            colorize: true
        }
    }
});
module.exports = logger;

// Use it like:
// const logger = require('./config/logger');
// logger.info('Server started');
// logger.error({ err: error }, 'Failed to send SMS');

Retries: The current schedulerService logs errors but doesn't retry. For critical reminders, implement a retry mechanism within the catch block of the cron.schedule task function.

  • Simple retry: Basic for loop with delays
  • Exponential backoff: Increase delay between retries (e.g., 1 second, 2 seconds, 4 seconds, 8 seconds) – libraries like async-retry simplify this
  • Consider: How many retries? What maximum delay? What happens after final failure (log to error queue, notify admin)?

7. Adding Security Features

Input Validation: Use a dedicated library (express-validator, joi) for robust validation of recipient (E.164 format), message (length, content), and sendAt. Sanitize inputs to prevent injection attacks.

Rate Limiting: Protect the /api/schedule endpoint from abuse using express-rate-limit:

bash
npm install express-rate-limit
javascript
// src/app.js (add before routes)
const rateLimit = require('express-rate-limit');

const apiLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // Limit each IP to 100 requests per 15 minutes
    message: 'Too many requests from this IP, try again after 15 minutes'
});

// Apply to all API routes or specific ones
app.use('/api/', apiLimiter);

API Key/Authentication: Currently the API is open. For production, protect it with API keys, JWT tokens, or other authentication mechanisms.

Secure Headers: Use middleware like helmet to set HTTP headers for security (XSS protection, content sniffing prevention, etc.):

bash
npm install helmet
javascript
// src/app.js
const helmet = require('helmet');
app.use(helmet());

8. Database Schema and Persistence (Production Consideration)

The in-memory scheduledJobs store is not persistent. For production:

Choose a Database:

  • Redis: Excellent for caching and simple key-value storage – good for job queues when combined with libraries like BullMQ
  • PostgreSQL/MongoDB: More robust for storing job details, status, results, and retry counts

Schema/Data Model: Create a table/collection for ScheduledJobs with fields:

  • jobId (Primary Key, UUID)
  • recipient (String)
  • message (Text)
  • sendAt (Timestamp/DateTime)
  • status (Enum: "PENDING", "SENT", "FAILED", "CANCELLED")
  • createdAt (Timestamp)
  • updatedAt (Timestamp)
  • plivoMessageUuid (String, nullable – store after successful send)
  • failureReason (Text, nullable)
  • retryCount (Integer, default 0)

Job Queue Library: Libraries like BullMQ (Redis-based) or Agenda (MongoDB-based) handle job persistence, scheduling, retries, concurrency, and worker processes more reliably than node-cron with manual persistence logic.

9. Verification and Testing

Step 1: Manual Verification (curl / Postman)

  1. Start the server: npm start
  2. Schedule an SMS: Send a POST request to http://localhost:3000/api/schedule

Using curl:

bash
curl -X POST http://localhost:3000/api/schedule \
-H "Content-Type: application/json" \
-d '{
      "recipient": "YOUR_PERSONAL_PHONE_NUMBER",
      "message": "Hello from the Plivo Scheduler! Testing 123.",
      "sendAt": "2025-04-20T18:30:00Z"
    }'

Replace YOUR_PERSONAL_PHONE_NUMBER and adjust sendAt to be a minute or two in the future using ISO 8601 format (UTC "Z" or specify offset).

Using Postman: Create a POST request, set the URL, select Body → raw → JSON, and paste the JSON payload.

  1. Check response: You should get a 202 Accepted response with a jobId
  2. Check logs: Monitor the console output where npm start is running – you should see logs for scheduling, then later for execution and sending (or failure)
  3. Check phone: Verify you receive the SMS on YOUR_PERSONAL_PHONE_NUMBER at approximately the scheduled time

Step 2: List Pending Jobs

Send a GET request to http://localhost:3000/api/schedule – you should see your scheduled job (until it executes):

bash
curl http://localhost:3000/api/schedule

Step 3: Cancel a Job

  1. Schedule another job far in the future – note its jobId from the response
  2. Send a DELETE request to http://localhost:3000/api/schedule/YOUR_JOB_ID:
bash
curl -X DELETE http://localhost:3000/api/schedule/paste_job_id_here
  1. Check the response (should be 200 OK)
  2. List jobs again (GET /api/schedule) – the cancelled job should be gone

Step 4: Unit & Integration Tests (Recommended)

For robust applications, write automated tests:

  • Unit tests (jest, mocha): Test individual functions in isolation – mock dependencies like node-cron and the plivo SDK, test validation logic, date parsing, error handling
  • Integration tests (supertest): Test API endpoints – start the Express server, send HTTP requests using supertest, assert responses, mock external dependencies to avoid actual API calls

10. Best Practices for SMS Appointment Reminders

Timing Considerations:

  • Appointment reminders should be sent 24-48 hours before the appointment, with an optional follow-up reminder 2-4 hours before
  • Time zone handling: Always store and process times in UTC, then convert to recipient's local time zone when scheduling
  • Compliance: Follow TCPA regulations – send SMS only between 8 AM and 9 PM in the recipient's local time zone

Message Content Best Practices:

  • Keep messages concise (under 160 characters when possible to fit in a single SMS segment)
  • Include key details: date, time, location, and opt-out instructions
  • Provide a callback number or link for rescheduling
  • Personalize with recipient name when available

Example reminder message:

text
Hi John, reminder: Your appointment is tomorrow, Apr 20 at 2:30 PM at City Dental (123 Main St). Reply CONFIRM or call 555-0123. Reply STOP to opt out.

Production Enhancements:

  • Persistent storage: Use PostgreSQL or MongoDB to store scheduled jobs
  • Job queue: Implement BullMQ or Agenda for reliable job processing
  • Status webhooks: Set up Plivo delivery receipts to track message status
  • Retry logic: Implement exponential backoff for failed deliveries
  • Monitoring: Add health checks and alerting for failed jobs

Conclusion

You've built a complete SMS scheduling application with Plivo, Node.js, and Express. This foundation supports appointment reminders, time-sensitive alerts, and automated notification systems. For production deployment, implement persistent storage, robust error handling, and monitoring to ensure reliable message delivery.

Ready to scale your SMS capabilities? Sign up for Plivo and start building enterprise-grade communication solutions.

Frequently Asked Questions

How to schedule SMS messages with Node.js and Express?

Use the `/schedule` endpoint of the Node.js Express app, sending a POST request with recipient, message, and sendAt (ISO 8601 format) in the body. The app uses `node-cron` to schedule and the Vonage Messages API to send the SMS at the specified time. A unique job ID is returned for tracking.

What is the Vonage Messages API used for?

The Vonage Messages API is a versatile communication API that allows sending messages across various channels, including SMS. This Node.js app utilizes it to deliver the scheduled SMS messages reliably and efficiently.

Why use Vonage for sending scheduled SMS?

Vonage offers reliable, scalable communication APIs with global reach and various features. The Messages API provides a unified approach for different communication channels, though this guide focuses on SMS capabilities.

When should I use a persistent data store for scheduled SMS?

A persistent store like Redis or a database is essential in production. The in-memory storage used in this guide is only for development; server restarts will clear scheduled jobs. Production apps need persistence and ideally a queue manager (BullMQ, Agenda).

Can I cancel a scheduled SMS message?

Yes, send a DELETE request to `/api/schedule/{jobId}`, providing the job ID you received when scheduling. This will stop the scheduled task if it hasn't executed yet and remove it from the system.

How to set up Vonage credentials for this project?

Create a Vonage Application, get a virtual number, and link them. Put API keys, Application ID, private key path, and Vonage number in a `.env` file (never commit to Git). The Node.js app loads these for Vonage API interaction.

What is node-cron used for in SMS scheduling?

Node-cron is a task scheduler for Node.js. It allows you to trigger functions at specific intervals or times. The provided example uses it to execute the SMS sending function at the user-defined 'sendAt' time.

How to handle errors and retries in the SMS scheduler?

The guide includes basic error handling and logging. For production, enhance this with a structured logger, retry logic within the scheduler, and custom error classes. Exponential backoff is a good practice for retries.

What is the purpose of the /schedule API endpoint?

The `/schedule` endpoint is a POST endpoint that accepts the SMS scheduling requests. It takes the recipient number, the message content, and the desired sending time as input and schedules the SMS message accordingly.

How to test the SMS scheduler application?

Use tools like `curl` or Postman to send requests to the local server after starting it with `npm start`. Verify the responses, check your phone for the SMS, and monitor server logs. Automated unit and integration tests are recommended.

What are the security considerations for a production SMS scheduler?

Implement input validation, rate limiting, proper authentication (API keys, JWTs), and secure headers. The provided code includes examples of rate limiting and helmet.js for header security.

What are the technology dependencies for this Node.js app?

The project uses Node.js, Express, the Vonage Messages API and Server SDK, `node-cron` for scheduling, `dotenv` for environment variables, and `uuid` for unique identifiers.

How does the system architecture of the Node.js SMS scheduler work?

The client interacts with the Node.js/Express API server, which uses scheduling logic (`node-cron`) and interacts with the Vonage API via the SDK. Messages are then sent from the Vonage cloud to the recipient.

What is the project structure recommended for this SMS scheduler?

The guide recommends creating directories for `src`, `src/routes`, `src/services`, and `src/config` for organizing application code, route definitions, service logic, and configuration respectively.