Developer Guide: Sending MMS with Vite (React/Vue), Node.js, and AWS Pinpoint/S3

+-----------------+      +----------------------+      +------------------------+      +------------------------+      +-----------+
|  Vite Frontend  |----->| Node.js Backend API  |----->| AWS Credentials (IAM)  |      |                        |      | Recipient |
| (React/Vue)     |      | (Express.js)         |<-----|                        |      |                        |      | (Phone)   |
+-----------------+      +----------------------+      +------------------------+      |                        |      +-----------+
       |                        |                                                     | AWS Pinpoint SMS/Voice |          ^
       | 1. Request Presigned URL| 2. Generate Presigned URL                           | (SendMediaMessage API) |          |
       |                        |    (using S3 SDK & IAM creds)                       |                        |          |
       | 3. Receive URL & Key   |---------------------------------------------------->|                        |----------+
       |                        |                                                     |                        | 6. Send MMS
       | 4. PUT file to S3 <----|                                                     |                        |
       |    (Directly using     |                                      +--------------+                        |
       |     Presigned URL)     |                                      | AWS S3 Bucket|                        |
       |                        | 5. Trigger Send MMS API Call         | (Stores Media|<-----------------------+
       |                        |    (using Pinpoint SDK_ S3 Key_      |  File)       | 4b. Receive & Store File
       +------------------------|    IAM creds_ Phone #_ Message)       +--------------+
                                |                                            |
                                +--------------------------------------------+

# Create project directory and navigate into it
mkdir mms-sender-app
cd mms-sender-app

# Create backend directory and initialize Node.js project
mkdir backend
cd backend
npm init -y

# Install necessary dependencies
npm install express cors dotenv @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @aws-sdk/client-pinpoint-sms-voice-v2

# Install development dependency (optional_ for auto-reloading)
npm install --save-dev nodemon

backend/
├── node_modules/
├── .env                # AWS credentials and config (DO NOT COMMIT)
├── .gitignore          # Node specific ignores
├── package.json
├── package-lock.json
└── server.js           # Main Express application file

node_modules
.env

# AWS Credentials & Config
# !! Replace with your actual IAM User Access Key ID !!
AWS_ACCESS_KEY_ID=YOUR_IAM_USER_ACCESS_KEY_ID
# !! Replace with your actual IAM User Secret Access Key !!
AWS_SECRET_ACCESS_KEY=YOUR_IAM_USER_SECRET_ACCESS_KEY
# !! Replace with the AWS region where your S3 bucket and Pinpoint number exist (e.g._ us-east-1_ eu-west-2) !!
AWS_REGION=us-east-1 # IMPORTANT: Use the SAME region as your S3 bucket and Pinpoint number
# !! Replace with the unique name you gave your S3 bucket !!
S3_BUCKET_NAME=your-unique-mms-media-bucket-name
# !! Replace with your MMS-capable number from AWS in E.164 format !!
PINPOINT_ORIGINATION_NUMBER=+1XXXXXXXXXX # Your MMS-capable number from AWS

# API Server Config
PORT=3001

# Navigate back to the root project directory
cd ..

# Create the frontend project using Vite (React + TypeScript template)
npm create vite@latest frontend -- --template react-ts
cd frontend

# Install frontend dependencies (axios for API calls)
npm install axios

# Start the frontend development server to test later
# This command launches the Vite development server_ typically on http://localhost:5173
npm run dev

frontend/
├── node_modules/
├── public/
├── src/
│   ├── App.css
│   ├── App.tsx       # Main application component
│   ├── main.tsx      # Entry point
│   └── ...           # Other components/assets
├── .gitignore
├── index.html
├── package.json
├── package-lock.json
├── tsconfig.json
└── vite.config.ts

import express from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { PinpointSMSVoiceV2Client, SendMediaMessageCommand } from '@aws-sdk/client-pinpoint-sms-voice-v2';
import crypto from 'crypto'; // For generating unique filenames

dotenv.config();

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

// --- AWS Clients Configuration ---
// Ensure required environment variables are set
if (!process.env.AWS_REGION || !process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY || !process.env.S3_BUCKET_NAME || !process.env.PINPOINT_ORIGINATION_NUMBER) {
    console.error("FATAL ERROR: Missing required AWS environment variables in .env file.");
    process.exit(1); // Stop the server if config is missing
}

const s3Client = new S3Client({
    region: process.env.AWS_REGION,
    credentials: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    },
});

const pinpointClient = new PinpointSMSVoiceV2Client({
    region: process.env.AWS_REGION,
    credentials: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    },
});

// --- Middleware ---
app.use(cors({
    // Configure allowed origins based on your frontend setup
    origin: ['http://localhost:5173', 'http://localhost:3000' /* Add production URL */ ],
}));
app.use(express.json()); // To parse JSON request bodies

// --- API Endpoints ---

/**
 * @route POST /api/generate-presigned-url
 * @desc Generate a presigned URL for direct S3 upload
 * @access Public (or protected if auth is added)
 * @body { filename: string, contentType: string }
 */
app.post('/api/generate-presigned-url', async (req, res) => {
    const { filename, contentType } = req.body;

    if (!filename || !contentType) {
        return res.status(400).json({ error: 'Missing filename or contentType' });
    }

    // Generate a unique key for the S3 object
    const randomBytes = crypto.randomBytes(16).toString('hex');
    const fileExtension = filename.split('.').pop();
    const s3Key = `mms-uploads/${randomBytes}.${fileExtension}`; // Store in a subfolder

    const putCommand = new PutObjectCommand({
        Bucket: process.env.S3_BUCKET_NAME,
        Key: s3Key,
        ContentType: contentType,
        // ACL: 'public-read', // Optional: Only if you need the object to be public, usually not needed for MMS
    });

    try {
        const presignedUrl = await getSignedUrl(s3Client, putCommand, { expiresIn: 300 }); // URL expires in 5 minutes
        console.log('Generated presigned URL:', presignedUrl);
        res.status(200).json({ presignedUrl, s3Key }); // Return URL and the key
    } catch (error) {
        console.error('Error generating presigned URL:', error);
        res.status(500).json({ error: 'Could not generate upload URL', details: error.message });
    }
});

/**
 * @route POST /api/send-mms
 * @desc Send the MMS message via Pinpoint
 * @access Public (or protected if auth is added)
 * @body { destinationPhoneNumber: string, messageBody: string, s3Key: string }
 */
app.post('/api/send-mms', async (req, res) => {
    const { destinationPhoneNumber, messageBody, s3Key } = req.body;

    // Basic validation - consider adding more robust checks (e.g., E.164 format)
    if (!destinationPhoneNumber || !s3Key) {
        // messageBody is optional for MMS-only
        return res.status(400).json({ error: 'Missing destinationPhoneNumber or s3Key' });
    }

    // Construct the S3 URL for the media file
    const mediaUrl = `s3://${process.env.S3_BUCKET_NAME}/${s3Key}`;

    const sendCommand = new SendMediaMessageCommand({
        DestinationPhoneNumber: destinationPhoneNumber, // E.164 format expected
        OriginationIdentity: process.env.PINPOINT_ORIGINATION_NUMBER,
        MessageBody: messageBody || '', // Optional text part
        MediaUrls: [mediaUrl],
        // ConfigurationSetName: 'YourOptionalConfigSet', // Optional: For tracking/events
    });

    try {
        console.log('Sending MMS with command input:', sendCommand.input);
        const response = await pinpointClient.send(sendCommand);
        console.log('MMS Send Response:', response);
        res.status(200).json({ success: true, messageId: response.MessageId });
    } catch (error) {
        console.error('Error sending MMS:', error);
        // Provide more context if possible, but avoid leaking sensitive details
        res.status(500).json({ error: 'Failed to send MMS', details: error.message, code: error.name });
    }
});

// --- Start Server ---
app.listen(port, () => {
    console.log(`Backend server running at http://localhost:${port}`);
});

# In the backend directory
npm start # Or use 'nodemon server.js' if you installed nodemon for auto-reload

import React, { useState, useRef, ChangeEvent, FormEvent } from 'react';
import axios from 'axios';
import './App.css'; // Basic styling

// Define the backend API URL (adjust if your backend runs elsewhere)
// Consider using environment variables for this in production builds (e.g., VITE_API_BASE_URL)
const API_BASE_URL = 'http://localhost:3001/api'; // Use your backend's actual address

function App() {
  const [destinationPhoneNumber, setDestinationPhoneNumber] = useState<string&gt;('');
  const [messageBody, setMessageBody] = useState<string&gt;('');
  const [selectedFile, setSelectedFile] = useState<File | null&gt;(null);
  const [statusMessage, setStatusMessage] = useState<string&gt;('');
  const [isLoading, setIsLoading] = useState<boolean&gt;(false);
  const [uploadedS3Key, setUploadedS3Key] = useState<string | null&gt;(null); // Store key after upload

  const fileInputRef = useRef<HTMLInputElement&gt;(null);

  const handleFileChange = (event: ChangeEvent<HTMLInputElement&gt;) =&gt; {
    if (event.target.files && event.target.files[0]) {
      const file = event.target.files[0];
      // Basic client-side validation
      if (!file.type.startsWith('image/')) {
          setStatusMessage('Error: Please select an image file (JPEG, PNG, GIF).');
          setSelectedFile(null);
          if (fileInputRef.current) fileInputRef.current.value = ''; // Clear input
          return;
      }
       // Optional: Add file size check (e.g., 1MB limit for MMS)
      const maxSizeMB = 1; // Example: 1MB limit (check carrier/Pinpoint limits)
      if (file.size &gt; maxSizeMB * 1024 * 1024) {
        setStatusMessage(`Error: File size exceeds ${maxSizeMB}MB limit.`);
        setSelectedFile(null);
        if (fileInputRef.current) fileInputRef.current.value = ''; // Clear input
        return;
      }

      setSelectedFile(file);
      setStatusMessage(`Selected file: ${file.name}`);
      setUploadedS3Key(null); // Reset S3 key if a new file is selected
    }
  };

  const handleSubmit = async (event: FormEvent<HTMLFormElement&gt;) =&gt; {
    event.preventDefault();
    if (!selectedFile || !destinationPhoneNumber) {
      setStatusMessage('Error: Destination phone number and an image file are required.');
      return;
    }
    // Basic E.164 format check (client-side) - more robust validation needed
    if (!/^\+?[1-9]\d{1,14}$/.test(destinationPhoneNumber)) {
        setStatusMessage('Error: Invalid phone number format. Use E.164 (e.g., +12065550100).');
        return;
    }


    setIsLoading(true);
    setStatusMessage('1/3: Requesting upload URL...');
    setUploadedS3Key(null); // Ensure no stale key is used

    try {
      // --- Step 1: Get Presigned URL from backend ---
      setStatusMessage('1/3: Requesting upload URL...');
      const presignedUrlResponse = await axios.post(`${API_BASE_URL}/generate-presigned-url`, {
        filename: selectedFile.name,
        contentType: selectedFile.type,
      });

      const { presignedUrl, s3Key } = presignedUrlResponse.data;
      console.log('Received presigned URL:', presignedUrl);
      console.log('Received S3 Key:', s3Key);

      if (!presignedUrl || !s3Key) {
        throw new Error(""Backend didn't return a valid presigned URL or S3 key."");
      }

      setStatusMessage('2/3: Uploading file to S3...');

      // --- Step 2: Upload file directly to S3 using the presigned URL ---
      await axios.put(presignedUrl, selectedFile, {
        headers: {
          'Content-Type': selectedFile.type, // Crucial header for S3 PUT
        },
        // Optional: Add progress tracking here using axios config onUploadProgress
      });

      setStatusMessage('3/3: File uploaded. Sending MMS...');
      setUploadedS3Key(s3Key); // Store the key for the send request

      // --- Step 3: Send MMS request to backend ---
      const sendMmsResponse = await axios.post(`${API_BASE_URL}/send-mms`, {
        destinationPhoneNumber: destinationPhoneNumber,
        messageBody: messageBody,
        s3Key: s3Key, // Use the key returned by the first backend call
      });

      console.log('MMS Send Response:', sendMmsResponse.data);
      setStatusMessage(`MMS Sent Successfully! Message ID: ${sendMmsResponse.data.messageId}`);
      // Optionally clear the form after success
      // setDestinationPhoneNumber('');
      // setMessageBody('');
      // setSelectedFile(null);
      // setUploadedS3Key(null);
      // if (fileInputRef.current) fileInputRef.current.value = '';

    } catch (error: any) {
      console.error('MMS Sending Process Error:', error);
      let detailedError = 'An unknown error occurred.';
      if (axios.isAxiosError(error)) {
          if (error.response) {
              // Error from backend API (presigned URL or send-mms)
              detailedError = `Backend Error (${error.response.status}): ${error.response.data?.error || error.response.data?.details || error.message}`;
          } else if (error.request) {
              // Error during S3 upload (network issue, CORS, bad presigned URL, timeout?)
              detailedError = `S3 Upload Error: Could not reach S3 or network issue. Check CORS, presigned URL validity/expiry, and network connection. Original message: ${error.message}`;
          } else {
              // Error setting up the request
              detailedError = `Request Setup Error: ${error.message}`;
          }
      } else if (error instanceof Error) {
         // Error thrown within the try block (e.g., missing URL/key)
         detailedError = `Client-Side Error: ${error.message}`;
      }
      setStatusMessage(`Error: ${detailedError}`);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div className=""App""&gt;
      <h1&gt;Send MMS via AWS Pinpoint & S3</h1&gt;
      <form onSubmit={handleSubmit}&gt;
        <div&gt;
          <label htmlFor=""destination""&gt;Destination Phone Number (E.164):</label&gt;
          <input
            type=""tel""
            id=""destination""
            value={destinationPhoneNumber}
            onChange={(e) =&gt; setDestinationPhoneNumber(e.target.value)}
            placeholder=""+12065550100""
            required
            disabled={isLoading}
          /&gt;
        </div&gt;
        <div&gt;
          <label htmlFor=""message""&gt;Message Body (Optional):</label&gt;
          <textarea
            id=""message""
            value={messageBody}
            onChange={(e) =&gt; setMessageBody(e.target.value)}
            rows={3}
            disabled={isLoading}
          /&gt;
        </div&gt;
        <div&gt;
          <label htmlFor=""file""&gt;Image File:</label&gt;
          <input
            type=""file""
            id=""file""
            ref={fileInputRef}
            onChange={handleFileChange}
            accept=""image/jpeg_ image/png_ image/gif"" // Be specific about accepted types
            required
            disabled={isLoading}
          /&gt;
        </div&gt;
        <button type=""submit"" disabled={isLoading || !selectedFile}&gt;
          {isLoading ? 'Sending...' : 'Send MMS'}
        </button&gt;
      </form&gt;
      {statusMessage && <p className={`status ${statusMessage.startsWith('Error') ? 'error' : ''}`}&gt;{statusMessage}</p&gt;}
    </div&gt;
  );
}

export default App;

.App {
  max-width: 500px;
  margin: 40px auto;
  padding: 20px;
  border: 1px solid #ccc;
  border-radius: 8px;
  font-family: sans-serif;
}

.App h1 {
  text-align: center;
  color: #333;
  margin-bottom: 25px;
}

.App div {
  margin-bottom: 15px;
}

.App label {
  display: block;
  margin-bottom: 5px;
  font-weight: bold;
  color: #555;
}

.App input[type=""tel""],
.App textarea,
.App input[type=""file""] {
  width: 100%;
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
  box-sizing: border-box;
  font-size: 1rem;
}

.App input[type=""file""] {
  padding: 5px;
}

.App textarea {
  resize: vertical;
  min-height: 60px;
}

.App button {
  display: block;
  width: 100%;
  background-color: #007bff;
  color: white;
  padding: 12px 15px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 1rem;
  transition: background-color 0.2s ease;
  margin-top: 20px;
}

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

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

.status {
  margin-top: 20px;
  padding: 12px;
  border-radius: 4px;
  background-color: #e9ecef;
  border: 1px solid #ced4da;
  font-size: 0.9rem;
  word-wrap: break-word;
}

.status.error {
  background-color: #f8d7da;
  color: #721c24;
  border-color: #f5c6cb;
}

# In the frontend directory
npm run dev