Frequently Asked Questions
Use the Plivo Node.js SDK and Express.js to create a server with an endpoint that accepts recipient details, message text, and media URL. The server then uses the Plivo SDK to send the MMS message via the Plivo API. This setup allows you to create a robust MMS sending service within your Node.js application.
You'll need Node.js and npm installed, a Plivo account, an MMS-enabled Plivo phone number (US or Canadian), and a basic understanding of Node.js, Express, and REST APIs. The Plivo number is essential for sending MMS, and you can purchase one through the Plivo console.
The /health
endpoint is a best practice for monitoring service availability. It allows for easy verification that your MMS sending service is running and responding to requests. This aids in troubleshooting and ensures the application is operational.
Implement a try...catch block around the client.messages.create
call to handle errors returned by the Plivo API. Use the error.statusCode
property to customize the error response sent back to the client and implement appropriate logging using a structured logger like Winston or Pino. More advanced strategies include retries for specific error codes.
Use the E.164 format, which includes a plus sign (+) followed by the country code and national number (e.g., +14155551212). While basic regex validation is shown, it's recommended to use a library like libphonenumber-js
in a production environment for better handling of international phone numbers and format variations.
Plivo supports sending multiple images or GIFs within one MMS message. Provide an array of media URLs using the media_urls
option when calling client.messages.create()
. Remember that each file has size limits and the total message size should be kept under carrier limits, typically around 1MB.
Environment variables (.env file) store sensitive information like Plivo Auth ID, Auth Token, and sender number securely. Never hardcode these credentials. The dotenv
library helps load these variables into your application's environment, protecting them from exposure in version control.
Several methods are available, including input validation (discussed earlier), rate limiting using express-rate-limit
to prevent abuse, authentication (API keys, JWT) to restrict access, and validating Plivo webhook signatures for callbacks to ensure they are authentic.
The mediaUrl
field provides the URL of the image, GIF, or video you want to include in your MMS message. This URL must be publicly accessible by Plivo's servers to fetch and include in the message. Ensure the URL is valid and points to the correct file.
Use media_ids
if you pre-upload your media to Plivo's servers. Obtain the media_id
from the Plivo console under Messaging > MMS Media Upload after the upload is complete. This can be useful when dealing with media that is not publicly accessible via URL.
Plivo primarily supports MMS sending to US and Canadian numbers via long codes. MMS to other countries may not be supported or could fall back to SMS. Refer to Plivo's documentation for the most up-to-date list of supported countries and regions.
Implement a webhook endpoint (e.g., /plivo-status-callback
) in your Express app. Configure this webhook URL either in the url
parameter during the client.messages.create()
call or on the Plivo Application settings. Plivo will then send updates to your webhook for various message statuses.
A MessageLog
model should store message details like plivoMessageUuid
, sender, recipient, text, media URLs, status (queued, sent, delivered, failed), Plivo status callback info, error codes, timestamps, and optionally user IDs.
The .gitignore
file is crucial for preventing sensitive information (like API credentials in the .env file) and unnecessary files (like the node_modules folder) from being tracked by version control. This protects your credentials and keeps your repository clean.
Send MMS with Plivo Node.js SDK: Complete Next.js + Supabase Tutorial
Learn how to send MMS messages using Plivo's Node.js SDK with Next.js and Supabase. Multimedia Messaging Service (MMS) enables you to send rich media content like images, GIFs, and videos alongside text messages. This comprehensive tutorial guides you through building a production-ready Node.js application that sends MMS messages via the Plivo API while tracking delivery status in Supabase.
When to Send MMS vs. SMS Messages
MMS achieves higher engagement rates due to multimedia content but costs more per message than SMS. Source: SMS vs MMS Marketing Comparison 2025
This tutorial shows you how to build a Next.js API route that accepts recipient details, message text, and media URLs, then uses the Plivo Node.js SDK to send MMS messages programmatically. You'll also learn to track message delivery status in Supabase for monitoring and historical records.
What You'll Learn:
System Architecture:
Prerequisites:
1. Setting Up Your Next.js Project to Send MMS with Plivo
Initialize your Next.js project and install the necessary dependencies for sending MMS with Plivo and storing data in Supabase.
Create Next.js Project: Open your terminal and create a new Next.js application with TypeScript support.
When prompted, select:
src/
directory: YesInstall Dependencies: Install
plivo
for the Plivo Node.js SDK (version 4.74.0 as of January 2025) and@supabase/supabase-js
for the Supabase client. The Plivo SDK requires Node.js 5.5 or higher and is fully compatible with Node.js 18.18+ used by Next.js 15. Sources: Plivo Node.js SDK Documentation; Plivo SDK Version CompatibilitySet Up Environment Variables: Create
.env.local
in your project root to store sensitive credentials. Never commit this file to version control.Filename:
.env.local
PLIVO_AUTH_ID
&PLIVO_AUTH_TOKEN
: Find these on your Plivo console dashboard overview page.PLIVO_SENDER_NUMBER
: Your MMS-enabled Plivo phone number with country code (e.g.,+14151234567
).Update
.gitignore
File: Next.js automatically includes.env.local
in.gitignore
, ensuring your credentials aren't tracked by Git.Basic Project Structure: Your Next.js project structure should look like:
2. Creating Supabase Database Schema for MMS Tracking
Create a Supabase table to track MMS message logs with proper Row Level Security policies.
Create Messages Table: In your Supabase dashboard, navigate to the SQL Editor and run this SQL:
Verify Table Creation: Navigate to the Table Editor in Supabase and confirm the
message_logs
table exists with proper columns and indexes.3. Initializing Plivo and Supabase Clients in Node.js
Create utility modules for initializing Supabase and Plivo clients.
src/lib/supabase.ts
:src/lib/plivo.ts
:4. Building the Next.js API Route to Send MMS via Plivo
Create the API endpoint that receives requests to send MMS messages via Plivo and logs them to Supabase.
src/app/api/send-mms/route.ts
:Key Features:
OPTIONS
handler enables Cross-Origin Resource Sharing for browser requests5. Implementing Plivo Webhook Handler for MMS Delivery Status
Create an API route to receive delivery status callbacks from Plivo and update Supabase.
src/app/api/plivo-callback/route.ts
:Webhook Security: This implementation validates Plivo webhook signatures using V2 signature method with HMAC-SHA256 and nonce validation. For SMS/MMS webhooks_ Plivo uses
X-Plivo-Signature-V2
andX-Plivo-Signature-V2-Nonce
headers. Calculate the signature by concatenating the full callback URL with the nonce value_ then sign with HMAC-SHA256 using your Auth Token. Sources: Plivo Webhook Signature Validation; Plivo V3 Signature Documentation6. Testing Your Plivo MMS API Endpoint
Test your API endpoint using curl or Postman.
Using
curl
:Success Response (Status 202):
Verify in Supabase: Check your
message_logs
table to confirm the message was logged with status "sent".7. Production-Ready Error Handling and Retry Logic for MMS
Production applications require robust error handling strategies.
Structured Logging: Replace
console.log
andconsole.error
with Pino or Winston.Retry Mechanisms: Implement retry logic for transient errors (5xx status codes) using
async-retry
. Only retry network errors or Plivo 5xx responses – never 4xx client errors.Validation Enhancement: Use
libphonenumber-js
for phone number validation andzod
for request schema validation.Media File Validation: Validate media file size and type before sending to Plivo using a HEAD request:
8. Understanding Plivo MMS Limitations and Media Requirements
Understand media files and carrier-specific requirements for reliable MMS delivery.
Supported Countries: Plivo supports sending MMS via long codes to the US and Canada only. Messages to other countries may fail or fall back to SMS without media. Source: Plivo MMS Documentation, 2025.
Media File Types and Size Limits:
Supported Formats: JPEG, PNG, GIF, and some video/audio formats.
Carrier-Specific Recommendations:
Sources: Plivo MMS Size Limits Support Article; Plivo Send Message API Documentation
Media URL Accessibility: The
mediaUrl
must be publicly accessible without authentication. Plivo servers fetch this URL to attach media. Private or localhost URLs will fail.Multiple Media Files: Send up to 10 images/GIFs in one MMS by providing an array of URLs in
media_urls
. Keep total size under 5 MB.Fallback to SMS: Implement fallback logic to send SMS if MMS fails (e.g., non-MMS-capable number, destination outside US/Canada, or specific error codes).
9. Security Best Practices for Production MMS APIs
Protect your MMS application with these essential security measures.
Secure Credentials: Use
.env.local
for development and Vercel Environment Variables or AWS Secrets Manager for production. Never commit secrets to version control.Input Validation and Sanitization:
libphonenumber-js
for E.164 validationzod
for request body schema validationRate Limiting: Implement rate limiting using Next.js middleware or edge functions:
CORS Configuration: The API route includes CORS headers in the
OPTIONS
handler. In production, replace*
with specific domains inAccess-Control-Allow-Origin
.Authentication/Authorization: For production APIs, implement JWT-based authentication using NextAuth.js or Supabase Auth:
Webhook Security: Always validate Plivo webhook signatures using HMAC-SHA256 with V2 headers before processing data.
10. Deploying Your Plivo MMS Application to Production
Deploy your MMS application to production:
Vercel Deployment (Recommended for Next.js):
Environment Variables:
.env.local
in your hosting platformSupabase Configuration:
Webhook URL Configuration:
url
parameter when sendingMonitoring and Logging:
Frequently Asked Questions (FAQ)
How do I send MMS messages using Plivo Node.js SDK in Next.js?
To send MMS with Plivo in Node.js, use the Plivo SDK's
client.messages.create()
method withtype: 'mms'
andmedia_urls
parameters. First, install the SDK withnpm install plivo
, then initialize the client with your Auth ID and Token. Create a Next.js API route that calls this method with your sender number, recipient number, message text, and media URLs to send MMS programmatically.Which countries support MMS messaging with Plivo?
Plivo supports MMS in the United States and Canada only. MMS to other countries may fail or fall back to SMS without media.
What are Plivo's MMS file size and attachment limits?
Plivo MMS limits: 5 MB total for sending, 7 MB total for receiving, 2 MB per attachment, up to 10 attachments per message, and 1,600 characters for message text. Keep individual files under 600 KB for best delivery.
How do I enable CORS for Next.js API routes when sending MMS?
Add an
OPTIONS
handler that returns CORS headers. SetAccess-Control-Allow-Origin
to your frontend domains, specify allowed methods (POST, OPTIONS
), and include headers (Content-Type, Authorization
).How do I validate Plivo webhook signatures for MMS delivery status?
Plivo uses V2 signatures for SMS/MMS webhooks with
X-Plivo-Signature-V2
andX-Plivo-Signature-V2-Nonce
headers. Concatenate your callback URL with the nonce, then sign with HMAC-SHA256 using your Auth Token. Compare the result with the signature header to validate authenticity.How do I store MMS logs in Supabase with Row Level Security?
Create a table with RLS enabled and appropriate policies. Use the Supabase service role key for server-side operations that need to bypass RLS. Create policies that allow the service role full access while restricting client access based on your authentication requirements.
Why is my Plivo MMS message failing or not being delivered?
Common issues: invalid or non-MMS-enabled sender number, media URL not publicly accessible, file size exceeding limits, unsupported format, destination outside US/Canada, or insufficient balance. Check Plivo Debug Logs for details.
Can I send multiple images or media files in one MMS message?
Yes. Send up to 10 media attachments in one MMS by providing an array of URLs in
media_urls
. Keep total size under 5 MB.What Node.js version is required for Next.js 15?
Next.js 15 requires Node.js 18.18 or later. The Plivo Node.js SDK is compatible with Node.js 5.5 and higher, making it fully compatible with Next.js 15 requirements.
How do I deploy a Next.js MMS application with Plivo to Vercel?
Push your code to a Git repository, connect it to Vercel, configure environment variables in the Vercel dashboard (including Plivo and Supabase credentials), and deploy. Vercel automatically handles HTTPS, edge functions, and provides webhook URLs for Plivo callbacks.
Related Resources