Twilio WhatsApp Integration with Next.js and Supabase: Complete Guide

npx create-next-app@latest twilio-whatsapp-nextjs --typescript --app --tailwind
cd twilio-whatsapp-nextjs

npm install twilio @supabase/supabase-js @supabase/ssr @supabase/auth-helpers-nextjs

npm install --save-dev ngrok

twilio-whatsapp-nextjs/
├── app/
│   ├── api/
│   │   ├── send-message/
│   │   │   └── route.ts
│   │   └── webhook/
│   │       ├── inbound/
│   │       │   └── route.ts
│   │       └── status/
│   │           └── route.ts
│   ├── dashboard/
│   │   └── page.tsx
│   ├── login/
│   │   └── page.tsx
│   ├── layout.tsx
│   └── page.tsx
├── lib/
│   ├── supabase/
│   │   ├── client.ts
│   │   └── server.ts
│   └── twilio.ts
├── .env.local
├── .gitignore
├── next.config.js
├── package.json
└── tsconfig.json

-- Create messages table for WhatsApp conversation history
CREATE TABLE messages (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  from_number TEXT NOT NULL,
  to_number TEXT NOT NULL,
  message_body TEXT NOT NULL,
  message_sid TEXT UNIQUE,
  status TEXT DEFAULT 'sent',
  direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
  media_url TEXT,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create index for faster queries
CREATE INDEX idx_messages_user_id ON messages(user_id);
CREATE INDEX idx_messages_created_at ON messages(created_at DESC);
CREATE INDEX idx_messages_message_sid ON messages(message_sid);

-- Enable Row Level Security (RLS)
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;

-- Create policy: Users can only see their own messages
CREATE POLICY "Users can view own messages"
  ON messages FOR SELECT
  USING (auth.uid() = user_id);

-- Create policy: Users can insert their own messages
CREATE POLICY "Users can insert own messages"
  ON messages FOR INSERT
  WITH CHECK (auth.uid() = user_id);

-- Create function to update timestamp
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

-- Create trigger to auto-update updated_at
CREATE TRIGGER update_messages_updated_at
  BEFORE UPDATE ON messages
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at_column();

-- Create user_profiles table for extended user information
CREATE TABLE user_profiles (
  id UUID REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  whatsapp_number TEXT,
  display_name TEXT,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

ALTER TABLE user_profiles ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own profile"
  ON user_profiles FOR SELECT
  USING (auth.uid() = id);

CREATE POLICY "Users can update own profile"
  ON user_profiles FOR UPDATE
  USING (auth.uid() = id);

# Twilio Configuration
TWILIO_ACCOUNT_SID=AC################################
TWILIO_AUTH_TOKEN=################################
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ########################
SUPABASE_SERVICE_ROLE_KEY=eyJ########################

# Application Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Webhook Security (generate random string)
WEBHOOK_SECRET=your-secure-random-string-here

// lib/twilio.ts
import twilio from 'twilio';

// Validate environment variables
if (!process.env.TWILIO_ACCOUNT_SID || !process.env.TWILIO_AUTH_TOKEN) {
  throw new Error('Missing Twilio credentials in environment variables');
}

// Initialize Twilio client with credentials
export const twilioClient = twilio(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);

// Twilio WhatsApp number from environment
export const TWILIO_WHATSAPP_NUMBER = process.env.TWILIO_WHATSAPP_NUMBER;

// Helper function to send WhatsApp message
export async function sendWhatsAppMessage(
  to: string,
  body: string,
  mediaUrl?: string
) {
  try {
    const message = await twilioClient.messages.create({
      from: TWILIO_WHATSAPP_NUMBER,
      to: `whatsapp:${to}`, // Ensure whatsapp: prefix
      body: body,
      ...(mediaUrl && { mediaUrl: [mediaUrl] }), // Optional media attachment
    });

    return {
      success: true,
      messageSid: message.sid,
      status: message.status,
    };
  } catch (error) {
    console.error('Twilio send error:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    };
  }
}

// Helper to validate Twilio webhook signature (security)
export function validateTwilioSignature(
  signature: string,
  url: string,
  params: Record<string, any>
): boolean {
  const authToken = process.env.TWILIO_AUTH_TOKEN;
  if (!authToken) return false;

  return twilio.validateRequest(authToken, signature, url, params);
}

// lib/supabase/server.ts
import { createServerClient, type CookieOptions } from '@supabase/ssr';
import { cookies } from 'next/headers';

export function createClient() {
  const cookieStore = cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value;
        },
        set(name: string, value: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value, ...options });
          } catch (error) {
            // Handle cookie setting errors in Server Components
          }
        },
        remove(name: string, options: CookieOptions) {
          try {
            cookieStore.set({ name, value: '', ...options });
          } catch (error) {
            // Handle cookie removal errors
          }
        },
      },
    }
  );
}

// Admin client with service role (for webhook handlers)
export function createAdminClient() {
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.SUPABASE_SERVICE_ROLE_KEY!, // Service role for admin access
    {
      cookies: {
        get() { return undefined; },
        set() {},
        remove() {},
      },
    }
  );
}

// lib/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr';

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

// app/api/send-message/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';
import { sendWhatsAppMessage } from '@/lib/twilio';

export async function POST(request: NextRequest) {
  try {
    // Get authenticated user from Supabase
    const supabase = createClient();
    const { data: { user }, error: authError } = await supabase.auth.getUser();

    if (authError || !user) {
      return NextResponse.json(
        { error: 'Unauthorized - Please log in' },
        { status: 401 }
      );
    }

    // Parse request body
    const body = await request.json();
    const { to, message, mediaUrl } = body;

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

    // Validate phone number format (basic E.164 validation)
    const phoneRegex = /^\+?[1-9]\d{1,14}$/;
    if (!phoneRegex.test(to)) {
      return NextResponse.json(
        { error: 'Invalid phone number format. Use E.164 format (e.g., +1234567890)' },
        { status: 400 }
      );
    }

    // Send WhatsApp message via Twilio
    const result = await sendWhatsAppMessage(to, message, mediaUrl);

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

    // Store message in Supabase database
    const { data: messageData, error: dbError } = await supabase
      .from('messages')
      .insert({
        user_id: user.id,
        from_number: process.env.TWILIO_WHATSAPP_NUMBER || '',
        to_number: `whatsapp:${to}`,
        message_body: message,
        message_sid: result.messageSid,
        status: result.status || 'sent',
        direction: 'outbound',
        ...(mediaUrl && { media_url: mediaUrl }),
      })
      .select()
      .single();

    if (dbError) {
      console.error('Database insert error:', dbError);
      // Message sent successfully but failed to save to DB
      return NextResponse.json(
        {
          success: true,
          messageSid: result.messageSid,
          warning: 'Message sent but failed to save to database'
        },
        { status: 200 }
      );
    }

    return NextResponse.json({
      success: true,
      messageSid: result.messageSid,
      message: messageData,
    });

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

// app/api/webhook/inbound/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createAdminClient } from '@/lib/supabase/server';
import { validateTwilioSignature } from '@/lib/twilio';

export async function POST(request: NextRequest) {
  try {
    // Get webhook data from Twilio
    const formData = await request.formData();
    const params: Record<string, any> = {};

    formData.forEach((value, key) => {
      params[key] = value.toString();
    });

    // Validate Twilio webhook signature for security
    const signature = request.headers.get('x-twilio-signature') || '';
    const url = request.url;

    if (!validateTwilioSignature(signature, url, params)) {
      console.error('Invalid Twilio webhook signature');
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 403 }
      );
    }

    // Extract message data
    const {
      MessageSid,
      From,
      To,
      Body,
      NumMedia,
      MediaUrl0,
    } = params;

    console.log('Inbound WhatsApp message:', { From, Body });

    // Store inbound message in database using admin client
    // (no user authentication required for webhooks)
    const supabase = createAdminClient();

    const { error: dbError } = await supabase
      .from('messages')
      .insert({
        from_number: From,
        to_number: To,
        message_body: Body || '',
        message_sid: MessageSid,
        status: 'received',
        direction: 'inbound',
        media_url: NumMedia && parseInt(NumMedia) > 0 ? MediaUrl0 : null,
        // Note: user_id is null for inbound messages from unknown users
        // You can implement logic to match phone numbers to users if needed
      });

    if (dbError) {
      console.error('Database insert error:', dbError);
      // Still return 200 to Twilio to avoid retries
    }

    // Optional: Implement auto-reply logic here
    // const autoReply = `Thank you for your message! We'll get back to you soon.`;
    // await sendWhatsAppMessage(From.replace('whatsapp:', ''), autoReply);

    // Always return 200 OK to Twilio to acknowledge receipt
    // Otherwise Twilio will retry sending the webhook
    return new NextResponse('Message received', { status: 200 });

  } catch (error) {
    console.error('Inbound webhook error:', error);
    // Return 200 even on error to prevent Twilio retries
    return new NextResponse('Error processed', { status: 200 });
  }
}

// app/api/webhook/status/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createAdminClient } from '@/lib/supabase/server';
import { validateTwilioSignature } from '@/lib/twilio';

export async function POST(request: NextRequest) {
  try {
    // Parse Twilio webhook data
    const formData = await request.formData();
    const params: Record<string, any> = {};

    formData.forEach((value, key) => {
      params[key] = value.toString();
    });

    // Validate webhook signature
    const signature = request.headers.get('x-twilio-signature') || '';
    const url = request.url;

    if (!validateTwilioSignature(signature, url, params)) {
      console.error('Invalid status webhook signature');
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 403 }
      );
    }

    // Extract status update data
    const {
      MessageSid,
      MessageStatus,
      ErrorCode,
      ErrorMessage,
    } = params;

    console.log('Message status update:', { MessageSid, MessageStatus });

    // Update message status in database
    const supabase = createAdminClient();

    const updateData: Record<string, any> = {
      status: MessageStatus,
    };

    // Add error information if present
    if (ErrorCode) {
      updateData.error_code = ErrorCode;
      updateData.error_message = ErrorMessage;
    }

    const { error: dbError } = await supabase
      .from('messages')
      .update(updateData)
      .eq('message_sid', MessageSid);

    if (dbError) {
      console.error('Database update error:', dbError);
    }

    // Return 200 OK to acknowledge status update
    return new NextResponse('Status updated', { status: 200 });

  } catch (error) {
    console.error('Status webhook error:', error);
    return new NextResponse('Error processed', { status: 200 });
  }
}

ngrok http 3000

npm run dev

curl -X POST http://localhost:3000/api/send-message \
  -H "Content-Type: application/json" \
  -H "Cookie: your-auth-cookie" \
  -d '{
    "to": "+1234567890",
    "message": "Hello from my Next.js WhatsApp app!"
  }'

// Already implemented in our webhook handlers
if (!validateTwilioSignature(signature, url, params)) {
  return NextResponse.json({ error: 'Invalid signature' }, { status: 403 });
}

// Check user authentication before sending messages
const { data: { user }, error } = await supabase.auth.getUser();
if (error || !user) {
  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const rateLimit = new Map<string, { count: number; resetTime: number }>();

export function middleware(request: NextRequest) {
  const ip = request.ip || 'unknown';
  const now = Date.now();
  const limit = 10; // 10 requests
  const window = 60000; // per minute

  const userLimit = rateLimit.get(ip);

  if (!userLimit || now > userLimit.resetTime) {
    rateLimit.set(ip, { count: 1, resetTime: now + window });
    return NextResponse.next();
  }

  if (userLimit.count >= limit) {
    return NextResponse.json(
      { error: 'Rate limit exceeded' },
      { status: 429 }
    );
  }

  userLimit.count++;
  return NextResponse.next();
}

export const config = {
  matcher: '/api/send-message/:path*',
};

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

// Sanitize message content (prevent injection attacks)
const sanitizedMessage = message.trim().slice(0, 1600); // WhatsApp limit

npm install -g vercel

vercel

npm run build
netlify deploy --prod

railway login
railway up