How to Build Two-Way SMS Messaging with Vonage API, React & Node.js

[User's Phone] <---- SMS ----> [Vonage Platform] <---- Webhook/API ----> [Node.js Backend (Express)]
      ^                                                                          |
      |-------------------------------- SMS -------------------------------------|
                                                                                 | (WebSocket)
                                                                                 V
                                                                      [React Frontend (Vite)] <----> [Developer/User]

mkdir vonage-sms-app
cd vonage-sms-app
mkdir backend
cd backend

npm init -y

npm install express dotenv @vonage/server-sdk body-parser socket.io cors

// backend/server.js
require('dotenv').config();
const express = require('express');
const http = require('http');
const { Server } = require('socket.io');
const bodyParser = require('body-parser');
const cors = require('cors');
const { Vonage } = require('@vonage/server-sdk');
// Import the specific message type class (adjust path based on SDK version if needed)
const { SMS } = require('@vonage/server-sdk/dist/classes/Messages/SMS');

// -----------------------------------------------------------------------------
// Vonage Configuration
// -----------------------------------------------------------------------------
const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: process.env.VONAGE_PRIVATE_KEY_PATH // Path to your private key file
});

// Validate configuration on startup
if (!process.env.VONAGE_API_KEY || !process.env.VONAGE_API_SECRET) {
  console.error('ERROR: VONAGE_API_KEY and VONAGE_API_SECRET must be set in environment variables.');
  process.exit(1);
}
if (!process.env.VONAGE_APPLICATION_ID || !process.env.VONAGE_PRIVATE_KEY_PATH) {
  console.error('ERROR: VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY_PATH must be set in environment variables.');
  process.exit(1);
}

// -----------------------------------------------------------------------------
// Express App Setup
// -----------------------------------------------------------------------------
const app = express();
const server = http.createServer(app);
const PORT = process.env.PORT || 3001;

// Ensure FRONTEND_URL is set in your .env for CORS
const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:5173'; // Default for Vite dev

app.use(cors({
  origin: frontendUrl, // Allow requests only from your frontend URL
  methods: ['GET', 'POST'],
}));

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

// Enhanced health check endpoint
app.get('/health', (req, res) => {
  const healthCheck = {
    status: 'OK',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    vonageConfigured: !!(process.env.VONAGE_API_KEY && process.env.VONAGE_APPLICATION_ID)
  };
  res.status(200).json(healthCheck);
});

// -----------------------------------------------------------------------------
// WebSocket (Socket.IO) Setup
// -----------------------------------------------------------------------------
const io = new Server(server, {
  cors: {
    origin: frontendUrl, // Allow connections only from your frontend URL
    methods: ['GET', 'POST']
  },
  pingTimeout: 60000, // Increase timeout for unstable connections
  pingInterval: 25000
});

io.on('connection', (socket) => {
  console.log('Client connected:', socket.id);

  socket.on('disconnect', (reason) => {
    console.log('Client disconnected:', socket.id, '– Reason:', reason);
  });

  socket.on('error', (error) => {
    console.error('Socket error:', error);
  });

  // Optional: Handle other events from the client if needed
});

// Handle Socket.IO errors
io.engine.on('connection_error', (err) => {
  console.error('Connection error:', err);
});

// Function to emit messages to all connected clients
// Note: In production, consider using rooms for multi-user scenarios
function broadcastSms(messageData) {
  io.emit('sms_received', messageData); // Event name can be customized
  console.log('Emitted message to clients:', messageData);
}

// -----------------------------------------------------------------------------
// Vonage Webhook Endpoint (Inbound SMS)
// -----------------------------------------------------------------------------
app.post('/webhooks/inbound-sms', (req, res) => {
  console.log('Inbound SMS Webhook Received:');
  console.log('Body:', JSON.stringify(req.body, null, 2)); // Log the full body for debugging

  // Destructure expected fields. Note: Vonage payloads include more fields like type, channel, etc.
  const { msisdn, to, text, messageId, timestamp } = req.body;

  if (!msisdn || !to || !text) {
    console.error('Incomplete SMS data received');
    // Still send 200 OK to Vonage to acknowledge receipt, but log error
    return res.status(200).end();
  }

  const messageData = {
    from: msisdn,       // The sender's number
    to: to,             // Your Vonage number
    text: text,         // The message content
    messageId: messageId, // Unique message ID from Vonage
    timestamp: timestamp, // Timestamp from Vonage
    direction: 'inbound' // Mark message direction
  };

  // Broadcast the received message via WebSocket
  broadcastSms(messageData);

  // IMPORTANT: Always respond to Vonage webhooks with a 200 OK
  res.status(200).end();
});

// -----------------------------------------------------------------------------
// API Endpoint to Send Outbound SMS
// -----------------------------------------------------------------------------
app.post('/send-sms', async (req, res) => {
  const { to, text } = req.body;
  const from = process.env.VONAGE_NUMBER; // Your Vonage number

  if (!to || !text) {
    return res.status(400).json({ error: "Missing 'to' or 'text' in request body." });
  }
  if (!from) {
    console.error('VONAGE_NUMBER environment variable not set.');
    return res.status(500).json({ error: 'Server configuration error.' });
  }

  // Basic E.164 format validation
  const e164Regex = /^\+[1-9]\d{1,14}$/;
  if (!e164Regex.test(to)) {
    return res.status(400).json({
      error: 'Invalid phone number format. Use E.164 format: +[country code][number] (e.g., +12015550123).'
    });
  }

  console.log(`Attempting to send SMS from ${from} to ${to}: "${text}"`);

  try {
    const resp = await vonage.messages.send(
      new SMS(
        {
          to: to,
          from: from,
          text: text,
          // clientRef: `my-app-${Date.now()}` // Optional client reference
        }
      )
    );

    console.log('Vonage API Response:', resp); // Includes message_uuid

    // Also broadcast the sent message to update the UI
    const sentMessageData = {
      from: from,
      to: to,
      text: text,
      messageId: resp.messageUuid, // Use the UUID returned by Vonage
      timestamp: new Date().toISOString(),
      direction: 'outbound'
    };
    broadcastSms(sentMessageData);

    res.status(200).json({ success: true, messageUuid: resp.messageUuid });

  } catch (error) {
    console.error('Error sending SMS via Vonage:', error);

    // Log more detailed error if available
    if (error.response && error.response.data) {
        console.error('Vonage Error Details:', error.response.data);
    }

    // Common Vonage error codes:
    // - 1320: Invalid number format
    // - 1330: Number not reachable
    // - 9: Partner quota exceeded
    const errorMessage = error.response?.data?.title || error.message || 'Failed to send SMS.';

    res.status(500).json({ success: false, error: errorMessage, details: error.message });
  }
});

// -----------------------------------------------------------------------------
// Start Server
// -----------------------------------------------------------------------------
server.listen(PORT, () => {
  console.log(`Backend server listening on port ${PORT}`);
  console.log(`CORS enabled for origin: ${frontendUrl}`);
});

# backend/.env

# Vonage Credentials
VONAGE_API_KEY=YOUR_VONAGE_API_KEY
VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID
VONAGE_PRIVATE_KEY_PATH=./private.key # Or the full path to your downloaded key
# Must be in E.164 format: +[country code][number], e.g., +12015550123
VONAGE_NUMBER=YOUR_VONAGE_PHONE_NUMBER

# Server Configuration
PORT=3001

# Frontend URL (Update for development/production)
FRONTEND_URL=http://localhost:5173 # Default Vite dev server URL

# backend/.env.example

# Vonage Credentials
VONAGE_API_KEY=
VONAGE_API_SECRET=
VONAGE_APPLICATION_ID=
VONAGE_PRIVATE_KEY_PATH=
# Must be in E.164 format: +[country code][number], e.g., +12015550123
VONAGE_NUMBER=

# Server Configuration
PORT=3001

# Frontend URL (Update for development/production)
FRONTEND_URL=http://localhost:5173

# backend/.gitignore
node_modules
.env
*.log
private.key # Ensure your private key is not committed

ngrok config add-authtoken <your-auth-token>

# In the backend directory
node server.js

ngrok http 3001 # Use the port your backend is running on

Session Status                online
Account                       Your Name (Plan: Free)
Version                       x.x.x
Region                        United States (us)
Forwarding                    http://xxxxxxxx.ngrok.io -> http://localhost:3001
Forwarding                    https://xxxxxxxx.ngrok.io -> http://localhost:3001

Web Interface                 http://127.0.0.1:4040

# In the vonage-sms-app directory
npm create vite@latest frontend -- --template react
cd frontend
npm install

npm install socket.io-client

/* src/index.css (example additions) */
body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  background-color: #f4f7f6;
}

#root {
  max-width: 800px;
  margin: 40px auto;
  padding: 20px;
  background-color: #fff;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  border-radius: 8px;
}

/* Add more specific styles in App.css */

// frontend/src/App.jsx
import React, { useState, useEffect, useRef, useCallback } from 'react';
import io from 'socket.io-client';
import './App.css'; // Create this file for custom styles

// Ensure this URL matches your backend (adjust for dev/prod)
const BACKEND_URL = import.meta.env.VITE_BACKEND_URL || 'http://localhost:3001';
const socket = io(BACKEND_URL, {
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionAttempts: 5
}); // Connect to the backend WebSocket

function App() {
  const [messages, setMessages] = useState([]);
  const [recipient, setRecipient] = useState(''); // Store the number to reply to
  const [newMessage, setNewMessage] = useState('');
  const [isConnected, setIsConnected] = useState(socket.connected);
  const [isSending, setIsSending] = useState(false);
  const [error, setError] = useState('');
  const messagesEndRef = useRef(null); // To auto-scroll

  // Scroll to bottom whenever messages change
  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [messages]);

  // Handle WebSocket connection events
  useEffect(() => {
    socket.on('connect', () => {
      console.log('WebSocket Connected:', socket.id);
      setIsConnected(true);
      setError(''); // Clear any connection errors
    });

    socket.on('disconnect', (reason) => {
      console.log('WebSocket Disconnected:', reason);
      setIsConnected(false);
      if (reason === 'io server disconnect') {
        // Server disconnected, manual reconnection needed
        socket.connect();
      }
    });

    socket.on('connect_error', (err) => {
      console.error('Connection Error:', err);
      setError('Unable to connect to server. Retrying…');
      setIsConnected(false);
    });

    // Listen for incoming/outgoing SMS messages from the backend
    socket.on('sms_received', (message) => {
      console.log('Received message via WebSocket:', message);
      setMessages((prevMessages) => [...prevMessages, message]);

      // Auto-populate recipient if it's an inbound message
      // and we don't have a recipient set yet, or it's a new conversation
      if (message.direction === 'inbound' && (!recipient || recipient !== message.from)) {
         // Simple logic: reply to the last inbound sender
         setRecipient(message.from);
         console.log(`Recipient auto-set to: ${message.from}`);
      }
    });

    // Clean up listeners on component unmount
    return () => {
      socket.off('connect');
      socket.off('disconnect');
      socket.off('connect_error');
      socket.off('sms_received');
    };
  }, [recipient]); // Re-run effect if recipient changes (for auto-population logic)

  // Handle sending a message
  const handleSendMessage = useCallback(async (e) => {
    e.preventDefault(); // Prevent form submission reload

    if (!newMessage.trim() || !recipient.trim()) {
      setError('Enter a recipient phone number and a message.');
      return;
    }

    // Basic E.164 format validation
    const e164Regex = /^\+[1-9]\d{1,14}$/;
    if (!e164Regex.test(recipient)) {
      setError('Invalid phone number format. Use E.164 format: +[country code][number] (e.g., +12015550123).');
      return;
    }

    setError(''); // Clear previous errors
    setIsSending(true);
    console.log(`Sending message to ${recipient}: "${newMessage}"`);

    try {
      const response = await fetch(`${BACKEND_URL}/send-sms`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          to: recipient,
          text: newMessage,
        }),
      });

      const result = await response.json();

      if (response.ok && result.success) {
        console.log('Message sent successfully via API:', result);
        setNewMessage(''); // Clear the input field
        // Note: The message will appear in the list via the WebSocket 'sms_received' event
      } else {
        console.error('Failed to send message:', result);
        setError(`Failed to send message: ${result.error || 'Unknown error'}`);
      }
    } catch (error) {
      console.error('Network or server error sending message:', error);
      setError(`Error sending message: ${error.message}`);
    } finally {
      setIsSending(false);
    }
  }, [newMessage, recipient]); // Dependencies for useCallback

  // Format timestamp for display
  const formatTimestamp = (isoString) => {
    if (!isoString) return '';
    try {
      return new Date(isoString).toLocaleString();
    } catch (e) {
      return isoString; // Fallback
    }
  };

  // Calculate character count and SMS segments
  const charCount = newMessage.length;
  const segmentSize = 160; // Standard SMS segment size
  const segments = Math.ceil(charCount / segmentSize) || 1;

  return (
    <div className="App">
      <h1>Vonage Two-Way SMS</h1>
      <p>
        Status: <span className={isConnected ? 'connected' : 'disconnected'}>
          {isConnected ? 'Connected' : 'Disconnected'}
        </span>
      </p>

      {error && <div className="error-message">{error}</div>}

      <div className="message-list">
        {messages.length === 0 && <p className="empty-state">No messages yet. Send an SMS to your Vonage number!</p>}
        {messages.map((msg, index) => (
          <div key={msg.messageId || index} className={`message ${msg.direction}`}>
            <span className="sender">
              {msg.direction === 'inbound' ? `From: ${msg.from}` : `To: ${msg.to}`}
            </span>
            <p>{msg.text}</p>
            <span className="timestamp">{formatTimestamp(msg.timestamp)}</span>
          </div>
        ))}
        <div ref={messagesEndRef} /> {/* Anchor for scrolling */}
      </div>

      <form className="message-form" onSubmit={handleSendMessage}>
        <div className="form-group">
          <label htmlFor="recipient">Recipient:</label>
          <input
            type="tel"
            id="recipient"
            value={recipient}
            onChange={(e) => setRecipient(e.target.value)}
            placeholder="Enter phone number (e.g., +12015550124)"
            required
            aria-label="Recipient phone number"
          />
        </div>
        <div className="form-group">
          <label htmlFor="message-text">Message:</label>
          <textarea
            id="message-text"
            value={newMessage}
            onChange={(e) => setNewMessage(e.target.value)}
            placeholder="Type your message…"
            rows={3}
            required
            aria-label="Message content"
          />
          <div className="character-count">
            {charCount} characters | {segments} SMS {segments === 1 ? 'segment' : 'segments'}
          </div>
        </div>
        <button
          type="submit"
          disabled={!isConnected || !recipient || !newMessage || isSending}
          aria-label="Send SMS"
        >
          {isSending ? 'Sending…' : 'Send SMS'}
        </button>
      </form>
    </div>
  );
}

export default App;

/* frontend/src/App.css */
.App {
  display: flex;
  flex-direction: column;
  height: calc(100vh - 80px); /* Adjust based on root padding */
  max-height: 80vh; /* Limit height */
}

h1 {
  text-align: center;
  color: #333;
  margin-bottom: 20px;
}

p {
  text-align: center;
  margin-bottom: 20px;
}

.connected {
  color: green;
  font-weight: bold;
}

.disconnected {
  color: red;
  font-weight: bold;
}

.error-message {
  background-color: #fee;
  border: 1px solid #f66;
  color: #c00;
  padding: 10px;
  border-radius: 4px;
  margin-bottom: 15px;
  text-align: center;
}

.message-list {
  flex-grow: 1;
  overflow-y: auto;
  border: 1px solid #eee;
  padding: 15px;
  margin-bottom: 20px;
  background-color: #fdfdfd;
  border-radius: 4px;
}

.empty-state {
  color: #888;
  text-align: center;
  font-style: italic;
}

.message {
  margin-bottom: 15px;
  padding: 10px 15px;
  border-radius: 18px;
  max-width: 70%;
  word-wrap: break-word;
}

.message.inbound {
  background-color: #e1f5fe; /* Light blue */
  margin-right: auto; /* Align left */
  border-bottom-left-radius: 4px;
}

.message.outbound {
  background-color: #dcedc8; /* Light green */
  margin-left: auto; /* Align right */
  text-align: right;
  border-bottom-right-radius: 4px;
}

.message .sender {
  display: block;
  font-size: 0.8em;
  font-weight: bold;
  color: #555;
  margin-bottom: 4px;
}

.message p {
  margin: 0;
  padding: 0;
  text-align: left; /* Keep text aligned left regardless of bubble position */
}

.message .timestamp {
  display: block;
  font-size: 0.75em;
  color: #888;
  margin-top: 5px;
}

/* Anchor for scrolling */
.message-list div[ref] {
  height: 0;
}

.message-form {
  display: flex;
  flex-direction: column;
  gap: 15px; /* Spacing between elements */
  border-top: 1px solid #eee;
  padding-top: 20px;
}

.form-group {
    display: flex;
    flex-direction: column;
}

.form-group label {
    margin-bottom: 5px;
    font-weight: bold;
    font-size: 0.9em;
    color: #333;
}

.message-form input[type="tel"],
.message-form textarea {
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
  font-size: 1em;
}

.message-form textarea {
  resize: vertical; /* Allow vertical resize */
}

.character-count {
  font-size: 0.85em;
  color: #666;
  margin-top: 5px;
  text-align: right;
}

.message-form button {
  padding: 12px 20px;
  background-color: #007bff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 1em;
  transition: background-color 0.2s ease;
}

.message-form button:hover:not(:disabled) {
  background-color: #0056b3;
}

.message-form button:disabled {
  background-color: #cccccc;
  cursor: not-allowed;
}

# frontend/.env
VITE_BACKEND_URL=http://localhost:3001 # Your local backend URL

# frontend/.env.example
VITE_BACKEND_URL=http://localhost:3001

# In the frontend directory
npm run dev

// Example with express-validator
const { body, validationResult } = require('express-validator');

app.post('/send-sms', [
  body('to').matches(/^\+[1-9]\d{1,14}$/).withMessage('Invalid E.164 phone number'),
  body('text').trim().isLength({ min: 1, max: 1600 }).withMessage('Message must be 1-1600 characters'),
], async (req, res) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({ errors: errors.array() });
  }
  // ... rest of handler
});

const rateLimit = require('express-rate-limit');

const sendSmsLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 10, // Limit each IP to 10 requests per minute
  message: 'Too many SMS requests, please try again later.',
  standardHeaders: true,
  legacyHeaders: false,
});

app.post('/send-sms', sendSmsLimiter, async (req, res) => {
  // ... handler
});

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
  ],
});

// Replace console.log with logger.info, console.error with logger.error
logger.info('Backend server listening on port ' + PORT);

# render.yaml (in root directory)
services:
  # Backend Service (Node.js)
  - type: web
    name: sms-backend
    env: node
    rootDir: backend # Specify the subdirectory
    plan: free # Or your desired plan (note: free tier has inactivity shutdowns)
    buildCommand: npm install
    startCommand: npm run start
    envVars:
      # Use Node.js 22 (20.19+ or 22.12+ required for Vite 7.0)
      - key: NODE_VERSION
        value: 22
      # Reference secrets stored in Render Dashboard
      - key: VONAGE_API_KEY
        fromSecret: vonage_api_key
      - key: VONAGE_API_SECRET
        fromSecret: vonage_api_secret
      - key: VONAGE_APPLICATION_ID
        fromSecret: vonage_app_id
      - key: VONAGE_NUMBER
        fromSecret: vonage_number
      # Store private key as a secret file in Render
      - key: VONAGE_PRIVATE_KEY_PATH
        value: /etc/secrets/private.key # Path for Render secret file
      # Automatically use the deployed frontend URL
      - key: FRONTEND_URL
        fromService:
          type: web
          name: sms-frontend
          property: url

  # Frontend Service (Static Site)
  - type: web
    name: sms-frontend
    env: static
    rootDir: frontend # Specify the subdirectory
    plan: free # Or your desired plan
    buildCommand: npm install && npm run build
    staticPublishPath: dist # Directory containing build output
    envVars:
      # Automatically use the deployed backend URL
      - key: VITE_BACKEND_URL
        fromService:
          type: web
          name: sms-backend
          property: url
    routes:
      # Standard SPA rewrite rule for client-side routing
      - type: rewrite
        source: /*
        destination: /index.html