sequenceDiagram
    participant User Phone
    participant Plivo Network
    participant Next.js Webhook API
    participant Database (Prisma)
    participant Admin Dashboard
    participant NextAuth

    User Phone->>Plivo Network: Sends SMS to your Plivo number
    Plivo Network->>Next.js Webhook API: POST /api/sms/webhook (From, To, Text)
    Next.js Webhook API->>Database (Prisma): Store inbound message
    Next.js Webhook API->>Next.js Webhook API: Process message & generate reply
    Next.js Webhook API-->>Plivo Network: Return XML response (auto-reply)
    Plivo Network-->>User Phone: Delivers reply SMS

    Admin Dashboard->>NextAuth: Request access to /dashboard/messages
    NextAuth->>NextAuth: Verify session
    NextAuth-->>Admin Dashboard: Grant access if authenticated
    Admin Dashboard->>Database (Prisma): Fetch conversations
    Database (Prisma)-->>Admin Dashboard: Return message history
    Admin Dashboard->>Next.js Webhook API: Send manual reply via POST /api/sms/send
    Next.js Webhook API->>Plivo Network: Send SMS via Plivo SDK

npx create-next-app@latest plivo-two-way-sms --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd plivo-two-way-sms

npm install plivo next-auth@beta prisma @prisma/client bcryptjs
npm install -D @types/bcryptjs

npx prisma init

# Database Connection (PostgreSQL example)
DATABASE_URL="postgresql://username:password@localhost:5432/plivo_sms_db"

# Plivo Credentials (from console.plivo.com)
PLIVO_AUTH_ID="your_auth_id_here"
PLIVO_AUTH_TOKEN="your_auth_token_here"
PLIVO_PHONE_NUMBER="+14155551234"  # Your Plivo number in E.164 format

# NextAuth Configuration
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="generate-a-random-secret-string-here"  # Run: openssl rand -base64 32

# ngrok Webhook URL (update after starting ngrok)
WEBHOOK_BASE_URL="https://your-ngrok-url.ngrok.io"

openssl rand -base64 32

# Test Plivo credentials
node -e "const plivo=require('plivo');new plivo.Client(process.env.PLIVO_AUTH_ID,process.env.PLIVO_AUTH_TOKEN).account.get().then(r=>console.log('✓ Valid'));"

# Verify phone number format (must start with +)
if [[ ! $PLIVO_PHONE_NUMBER =~ ^\+[1-9][0-9]{1,14}$ ]]; then echo "❌ Invalid phone format"; fi

mkdir -p src/app/api/sms/{webhook,send}
mkdir -p src/app/dashboard/messages
mkdir -p src/lib
touch src/lib/plivo.ts src/lib/db.ts src/auth.ts

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"  // or "mysql"
  url      = env("DATABASE_URL")
}

model User {
  id            String    @id @default(cuid())
  email         String    @unique
  passwordHash  String
  name          String?
  role          String    @default("admin")
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
}

model Message {
  id              String    @id @default(cuid())
  messageUuid     String?   @unique  // Plivo's message UUID
  fromNumber      String                // E.164 format phone number
  toNumber        String                // Your Plivo number
  messageText     String    @db.Text
  direction       String                // "inbound" or "outbound"
  status          String    @default("received")  // received, sent, delivered, failed
  plivoResponse   Json?                 // Store full Plivo webhook payload
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt

  @@index([fromNumber])
  @@index([toNumber])
  @@index([createdAt])
}

model Conversation {
  id              String    @id @default(cuid())
  phoneNumber     String    @unique  // Customer's phone number
  lastMessageAt   DateTime  @default(now())
  messageCount    Int       @default(0)
  status          String    @default("active")  // active, archived, blocked
  metadata        Json?                          // Store custom data
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt

  @@index([lastMessageAt])
}

npx prisma migrate dev --name init
npx prisma generate

# Reset database (⚠️ deletes all data)
npx prisma migrate reset

# Or rollback last migration
npx prisma migrate resolve --rolled-back "migration-name"

import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const db = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
})

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db

import plivo from 'plivo';

if (!process.env.PLIVO_AUTH_ID || !process.env.PLIVO_AUTH_TOKEN) {
  throw new Error('Missing PLIVO_AUTH_ID or PLIVO_AUTH_TOKEN environment variables');
}

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

export const PLIVO_PHONE_NUMBER = process.env.PLIVO_PHONE_NUMBER;

/**
 * Send SMS via Plivo API with automatic retry
 * @param to - Recipient phone number (E.164 format)
 * @param text - Message content
 */
export async function sendSMS(to: string, text: string, retries = 2) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      const response = await plivoClient.messages.create({
        src: PLIVO_PHONE_NUMBER!,
        dst: to,
        text: text,
      });

      console.log('✅ SMS sent successfully:', response);
      return { success: true, data: response };
    } catch (error: any) {
      console.error(`❌ Failed to send SMS (attempt ${attempt + 1}):`, error);

      // Don't retry on client errors (400, 401, 404)
      if (error.status >= 400 && error.status < 500) {
        return { success: false, error, fatal: true };
      }

      // Retry on network/server errors with exponential backoff
      if (attempt < retries) {
        await new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)));
      }
    }
  }

  return { success: false, error: new Error('Max retries exceeded') };
}

# Install ngrok
npm install -g ngrok

# Start your Next.js dev server
npm run dev

# In another terminal, start ngrok
ngrok http 3000

import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/lib/db';

/**
 * Plivo Webhook Handler for Inbound SMS
 *
 * Plivo sends POST requests with these parameters:
 * - From: Sender's phone number
 * - To: Your Plivo number
 * - Text: Message content
 * - MessageUUID: Unique message identifier
 * - Type: Message type (usually "sms")
 */
export async function POST(request: NextRequest) {
  try {
    // Parse form data (Plivo sends application/x-www-form-urlencoded)
    const formData = await request.formData();

    const fromNumber = formData.get('From') as string;
    const toNumber = formData.get('To') as string;
    const messageText = formData.get('Text') as string;
    const messageUuid = formData.get('MessageUUID') as string;

    console.log('📨 Inbound SMS received:', { fromNumber, toNumber, messageText, messageUuid });

    // Validate required fields
    if (!fromNumber || !toNumber || !messageText) {
      console.error('❌ Missing required webhook parameters');
      return new NextResponse('Bad Request', { status: 400 });
    }

    // Check for duplicate messages using MessageUUID
    if (messageUuid) {
      const existing = await db.message.findUnique({
        where: { messageUuid },
      });

      if (existing) {
        console.log('⚠️ Duplicate message detected, skipping');
        return new NextResponse('OK', { status: 200 });
      }
    }

    // Store message in database
    const message = await db.message.create({
      data: {
        messageUuid,
        fromNumber,
        toNumber,
        messageText,
        direction: 'inbound',
        status: 'received',
        plivoResponse: Object.fromEntries(formData.entries()),
      },
    });

    console.log('✅ Message stored:', message.id);

    // Update or create conversation
    await db.conversation.upsert({
      where: { phoneNumber: fromNumber },
      update: {
        lastMessageAt: new Date(),
        messageCount: { increment: 1 },
      },
      create: {
        phoneNumber: fromNumber,
        lastMessageAt: new Date(),
        messageCount: 1,
        status: 'active',
      },
    });

    // Generate automated reply based on message content
    const replyText = generateAutoReply(messageText);

    // If automated reply needed, store outbound message
    if (replyText) {
      await db.message.create({
        data: {
          fromNumber: toNumber,
          toNumber: fromNumber,
          messageText: replyText,
          direction: 'outbound',
          status: 'sent',
        },
      });

      // Return XML response to send automated reply
      const xmlResponse = `<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Message src="${toNumber}" dst="${fromNumber}">${escapeXml(replyText)}</Message>
</Response>`;

      return new NextResponse(xmlResponse, {
        status: 200,
        headers: { 'Content-Type': 'application/xml' },
      });
    }

    // No automated reply – just acknowledge receipt
    return new NextResponse('OK', { status: 200 });

  } catch (error) {
    console.error('❌ Webhook processing error:', error);
    return new NextResponse('Internal Server Error', { status: 500 });
  }
}

/**
 * Generate automated reply based on inbound message content
 */
function generateAutoReply(messageText: string): string | null {
  const text = messageText.toLowerCase().trim();

  // Keyword-based automated responses
  if (text === 'hello' || text === 'hi') {
    return "Hello! Thanks for contacting us. How can we help you today?";
  }

  if (text === 'status') {
    return "Your account status is active. Reply HELP for more options.";
  }

  if (text === 'help') {
    return "Available commands: STATUS, HOURS, STOP. Or describe your question and we'll respond shortly.";
  }

  if (text === 'hours') {
    return "We're open Monday–Friday, 9 AM–5 PM EST. We'll respond to your message during business hours.";
  }

  if (text === 'stop' || text === 'unsubscribe') {
    // Mark conversation as opt-out in database (implement separately)
    return "You've been unsubscribed from our messages. Reply START to re-subscribe.";
  }

  // No automated reply for other messages (manual response needed)
  return null;
}

/**
 * Escape XML special characters for safe inclusion in XML responses
 */
function escapeXml(unsafe: string): string {
  return unsafe
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&apos;');
}

import NextAuth from 'next-auth';
import Credentials from 'next-auth/providers/credentials';
import bcrypt from 'bcryptjs';
import { db } from '@/lib/db';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    Credentials({
      credentials: {
        email: { label: 'Email', type: 'email' },
        password: { label: 'Password', type: 'password' },
      },
      async authorize(credentials) {
        if (!credentials?.email || !credentials?.password) {
          return null;
        }

        const user = await db.user.findUnique({
          where: { email: credentials.email as string },
        });

        if (!user) {
          return null;
        }

        const passwordValid = await bcrypt.compare(
          credentials.password as string,
          user.passwordHash
        );

        if (!passwordValid) {
          return null;
        }

        return {
          id: user.id,
          email: user.email,
          name: user.name,
        };
      },
    }),
  ],
  pages: {
    signIn: '/login',
  },
  session: {
    strategy: 'jwt',
    maxAge: 30 * 24 * 60 * 60, // 30 days
  },
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id;
      }
      return token;
    },
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.id as string;
      }
      return session;
    },
  },
});

import { handlers } from '@/auth';

export const { GET, POST } = handlers;

import { PrismaClient } from '@prisma/client';
import bcrypt from 'bcryptjs';

const prisma = new PrismaClient();

async function main() {
  const passwordHash = await bcrypt.hash('admin123', 10);

  const admin = await prisma.user.upsert({
    where: { email: 'admin@example.com' },
    update: {},
    create: {
      email: 'admin@example.com',
      passwordHash,
      name: 'Admin User',
      role: 'admin',
    },
  });

  console.log('✅ Admin user created:', admin.email);
  console.log('⚠️ IMPORTANT: Change password immediately in production');
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

{
  "prisma": {
    "seed": "ts-node --compiler-options {\"module\":\"CommonJS\"} prisma/seed.ts"
  }
}

npm install -D ts-node
npx prisma db seed

import { auth } from '@/auth';
import { NextResponse } from 'next/server';

export default auth((req) => {
  const isLoggedIn = !!req.auth;
  const isAuthPage = req.nextUrl.pathname.startsWith('/login');
  const isDashboard = req.nextUrl.pathname.startsWith('/dashboard');

  if (isDashboard && !isLoggedIn) {
    return NextResponse.redirect(new URL('/login', req.url));
  }

  if (isAuthPage && isLoggedIn) {
    return NextResponse.redirect(new URL('/dashboard/messages', req.url));
  }

  return NextResponse.next();
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

import { auth } from '@/auth';
import { db } from '@/lib/db';
import { redirect } from 'next/navigation';
import MessageList from './MessageList';

export default async function MessagesPage() {
  const session = await auth();

  if (!session) {
    redirect('/login');
  }

  // Fetch recent conversations with message counts
  const conversations = await db.conversation.findMany({
    where: { status: 'active' },
    orderBy: { lastMessageAt: 'desc' },
    take: 50,
  });

  // Fetch all messages for display
  const messages = await db.message.findMany({
    orderBy: { createdAt: 'desc' },
    take: 100,
  });

  return (
    <div className="container mx-auto p-6">
      <h1 className="text-3xl font-bold mb-6">SMS Conversations</h1>

      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
        {/* Conversation List */}
        <div className="lg:col-span-1 bg-white rounded-lg shadow p-4">
          <h2 className="text-xl font-semibold mb-4">Active Conversations ({conversations.length})</h2>
          <div className="space-y-2">
            {conversations.map((conv) => (
              <a
                key={conv.id}
                href={`/dashboard/messages/${conv.phoneNumber}`}
                className="block p-3 border rounded hover:bg-gray-50"
              >
                <p className="font-medium">{conv.phoneNumber}</p>
                <p className="text-sm text-gray-600">
                  {conv.messageCount} messages • {new Date(conv.lastMessageAt).toLocaleDateString()}
                </p>
              </a>
            ))}
          </div>
        </div>

        {/* Message Thread */}
        <div className="lg:col-span-2 bg-white rounded-lg shadow p-4">
          <h2 className="text-xl font-semibold mb-4">Recent Messages</h2>
          <MessageList messages={messages} />
        </div>
      </div>
    </div>
  );
}

'use client';

import { Message } from '@prisma/client';

interface MessageListProps {
  messages: Message[];
}

export default function MessageList({ messages }: MessageListProps) {
  return (
    <div className="space-y-3 max-h-[600px] overflow-y-auto">
      {messages.map((msg) => (
        <div
          key={msg.id}
          className={`p-4 rounded-lg ${
            msg.direction === 'inbound'
              ? 'bg-blue-50 ml-8'
              : 'bg-green-50 mr-8'
          }`}
        >
          <div className="flex justify-between text-sm text-gray-600 mb-1">
            <span className="font-medium">
              {msg.direction === 'inbound' ? msg.fromNumber : 'You'}
            </span>
            <span>{new Date(msg.createdAt).toLocaleString()}</span>
          </div>
          <p className="text-gray-900">{msg.messageText}</p>
          <span className={`text-xs ${
            msg.status === 'received' || msg.status === 'sent'
              ? 'text-green-600'
              : 'text-gray-500'
          }`}>
            {msg.status}
          </span>
        </div>
      ))}
    </div>
  );
}

import { NextRequest, NextResponse } from 'next/server';
import { auth } from '@/auth';
import { sendSMS } from '@/lib/plivo';
import { db } from '@/lib/db';

export async function POST(request: NextRequest) {
  try {
    const session = await auth();

    if (!session) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
    }

    const { to, text } = await request.json();

    if (!to || !text) {
      return NextResponse.json({ error: 'Missing required fields' }, { status: 400 });
    }

    // Validate phone number format (basic E.164 check)
    if (!/^\+[1-9]\d{1,14}$/.test(to)) {
      return NextResponse.json({ error: 'Invalid phone number format' }, { status: 400 });
    }

    // Check if recipient has opted out
    const conversation = await db.conversation.findUnique({
      where: { phoneNumber: to },
    });

    if (conversation?.status === 'opted_out') {
      return NextResponse.json({ error: 'Recipient has opted out' }, { status: 403 });
    }

    // Send SMS via Plivo
    const result = await sendSMS(to, text);

    if (!result.success) {
      return NextResponse.json({ error: 'Failed to send SMS' }, { status: 500 });
    }

    // Store outbound message in database
    await db.message.create({
      data: {
        fromNumber: process.env.PLIVO_PHONE_NUMBER!,
        toNumber: to,
        messageText: text,
        direction: 'outbound',
        status: 'sent',
        messageUuid: result.data?.message_uuid?.[0],
      },
    });

    // Update conversation
    await db.conversation.upsert({
      where: { phoneNumber: to },
      update: {
        lastMessageAt: new Date(),
        messageCount: { increment: 1 },
      },
      create: {
        phoneNumber: to,
        lastMessageAt: new Date(),
        messageCount: 1,
      },
    });

    return NextResponse.json({ success: true, data: result.data });

  } catch (error) {
    console.error('❌ Send SMS error:', error);
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

'use client';

import { useState } from 'react';

interface ReplyFormProps {
  phoneNumber: string;
}

export default function ReplyForm({ phoneNumber }: ReplyFormProps) {
  const [message, setMessage] = useState('');
  const [sending, setSending] = useState(false);
  const [status, setStatus] = useState<'idle' | 'success' | 'error'>('idle');

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setSending(true);
    setStatus('idle');

    try {
      const response = await fetch('/api/sms/send', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ to: phoneNumber, text: message }),
      });

      if (response.ok) {
        setStatus('success');
        setMessage('');
        setTimeout(() => window.location.reload(), 1000);
      } else {
        setStatus('error');
      }
    } catch (error) {
      setStatus('error');
    } finally {
      setSending(false);
    }
  }

  return (
    <form onSubmit={handleSubmit} className="mt-6">
      <label htmlFor="message" className="block text-sm font-medium text-gray-700 mb-2">
        Send Reply to {phoneNumber}
      </label>
      <textarea
        id="message"
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        className="w-full border rounded-lg p-3 min-h-[100px]"
        placeholder="Type your message…"
        required
        disabled={sending}
      />
      <div className="flex justify-between items-center mt-3">
        <button
          type="submit"
          disabled={sending || !message.trim()}
          className="bg-blue-600 text-white px-6 py-2 rounded-lg hover:bg-blue-700 disabled:bg-gray-400"
        >
          {sending ? 'Sending…' : 'Send Reply'}
        </button>
        {status === 'success' && <span className="text-green-600">✓ Message sent</span>}
        {status === 'error' && <span className="text-red-600">✗ Failed to send</span>}
      </div>
      <p className="text-sm text-gray-500 mt-2">
        Character count: {message.length} / 1600
      </p>
    </form>
  );
}

import crypto from 'crypto';

function verifyPlivoSignature(
  url: string,
  nonce: string,
  signature: string,
  authToken: string
): boolean {
  const uri = url.replace(/\/$/, ''); // Remove trailing slash
  const message = uri + nonce;
  const expectedSignature = crypto
    .createHmac('sha256', authToken)
    .update(message)
    .digest('base64');

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

export async function POST(request: NextRequest) {
  // Verify Plivo signature
  const signature = request.headers.get('X-Plivo-Signature-V3');
  const nonce = request.headers.get('X-Plivo-Signature-V3-Nonce');
  const url = request.url;

  if (signature && nonce) {
    const isValid = verifyPlivoSignature(
      url,
      nonce,
      signature,
      process.env.PLIVO_AUTH_TOKEN!
    );

    if (!isValid) {
      console.error('❌ Invalid Plivo signature');
      return new NextResponse('Forbidden', { status: 403 });
    }
  }

  // ... rest of webhook handler
}

npm install @upstash/ratelimit @upstash/redis

import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '1 h'), // 10 requests per hour
  analytics: true,
});

export async function POST(request: NextRequest) {
  const session = await auth();
  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  const identifier = session.user.id;
  const { success } = await ratelimit.limit(identifier);

  if (!success) {
    return NextResponse.json({ error: 'Rate limit exceeded' }, { status: 429 });
  }

  // ... rest of send logic
}

import { z } from 'zod';

const sendSmsSchema = z.object({
  to: z.string().regex(/^\+[1-9]\d{1,14}$/, 'Invalid E.164 phone number'),
  text: z.string().min(1).max(1600, 'Message too long'),
});

export async function POST(request: NextRequest) {
  // ... auth check

  const body = await request.json();
  const validation = sendSmsSchema.safeParse(body);

  if (!validation.success) {
    return NextResponse.json(
      { error: 'Invalid input', details: validation.error.errors },
      { status: 400 }
    );
  }

  const { to, text } = validation.data;
  // ... send SMS
}

.env
.env.local
.env.production

curl -X POST http://localhost:3000/api/sms/webhook \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "From=+14155551234" \
  -d "To=+14155556789" \
  -d "Text=status" \
  -d "MessageUUID=test-uuid-123"

import { generateAutoReply } from '@/app/api/sms/webhook/route';

describe('Auto-reply logic', () => {
  it('responds to HELP keyword', () => {
    expect(generateAutoReply('help')).toContain('Available commands');
  });

  it('returns null for unknown keywords', () => {
    expect(generateAutoReply('random text')).toBeNull();
  });
});

# Install Vercel CLI
npm i -g vercel

# Deploy to Vercel
vercel

# Set production environment variables
vercel env add PLIVO_AUTH_ID production
vercel env add PLIVO_AUTH_TOKEN production
vercel env add PLIVO_PHONE_NUMBER production
vercel env add DATABASE_URL production
vercel env add NEXTAUTH_SECRET production
vercel env add NEXTAUTH_URL production  # https://your-domain.vercel.app

# Set DATABASE_URL to production
export DATABASE_URL="your-production-db-url"

# Run migrations
npx prisma migrate deploy

# Seed admin user
npx prisma db seed

export async function POST(request: NextRequest) {
  const formData = await request.formData();
  const messageUuid = formData.get('MessageUUID') as string;
  const status = formData.get('Status') as string; // delivered, failed, undelivered

  await db.message.update({
    where: { messageUuid },
    data: { status: status.toLowerCase() },
  });

  return new NextResponse('OK', { status: 200 });
}

await db.conversation.update({
  where: { phoneNumber: fromNumber },
  data: { status: 'opted_out' },
});

npm install libphonenumber-js

import { parsePhoneNumber } from 'libphonenumber-js';

const phone = parsePhoneNumber(userInput, 'US');
const e164 = phone.format('E.164'); // "+14155551234"