mkdir whatsapp-broadcast-marketing
cd whatsapp-broadcast-marketing
npm init -y
npm install axios express dotenv csv-parser moment node-cron

RAPIDAPI_KEY=your_rapidapi_key_here
RAPIDAPI_HOST=whatsapp-messaging-bot.p.rapidapi.com
WHATSAPP_SESSION=marketing

DATABASE_URL=postgresql://user:password@localhost:5432/marketing_db

// subscriber-manager.js
const { Sequelize, DataTypes } = require('sequelize');
const sequelize = new Sequelize(process.env.DATABASE_URL);

// Subscriber model
const Subscriber = sequelize.define('Subscriber', {
  id: {
    type: DataTypes.UUID,
    defaultValue: DataTypes.UUIDV4,
    primaryKey: true
  },
  phoneNumber: {
    type: DataTypes.STRING,
    unique: true,
    allowNull: false
  },
  name: {
    type: DataTypes.STRING
  },
  email: {
    type: DataTypes.STRING
  },
  status: {
    type: DataTypes.ENUM('active', 'unsubscribed', 'bounced'),
    defaultValue: 'active'
  },
  source: {
    type: DataTypes.STRING // 'website', 'landing-page', 'store', etc.
  },
  tags: {
    type: DataTypes.ARRAY(DataTypes.STRING), // ['vip', 'new-customer', 'high-spender']
    defaultValue: []
  },
  lastMessageSent: {
    type: DataTypes.DATE
  },
  totalMessagesSent: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  },
  totalMessagesOpened: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  },
  totalClicks: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  },
  subscribedAt: {
    type: DataTypes.DATE,
    defaultValue: DataTypes.NOW
  }
});

// Campaign model
const Campaign = sequelize.define('Campaign', {
  id: {
    type: DataTypes.UUID,
    defaultValue: DataTypes.UUIDV4,
    primaryKey: true
  },
  name: {
    type: DataTypes.STRING,
    allowNull: false
  },
  message: {
    type: DataTypes.TEXT,
    allowNull: false
  },
  imageUrl: {
    type: DataTypes.STRING
  },
  buttonText: {
    type: DataTypes.STRING
  },
  buttonUrl: {
    type: DataTypes.STRING
  },
  targetTags: {
    type: DataTypes.ARRAY(DataTypes.STRING) // Target specific segments
  },
  status: {
    type: DataTypes.ENUM('draft', 'scheduled', 'sending', 'sent', 'cancelled'),
    defaultValue: 'draft'
  },
  scheduledAt: {
    type: DataTypes.DATE
  },
  sentAt: {
    type: DataTypes.DATE
  },
  totalSent: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  },
  totalDelivered: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  },
  totalOpened: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  },
  totalClicks: {
    type: DataTypes.INTEGER,
    defaultValue: 0
  }
});

class SubscriberManager {
  async addSubscriber(phoneNumber, data = {}) {
    try {
      const subscriber = await Subscriber.create({
        phoneNumber: phoneNumber,
        name: data.name,
        email: data.email,
        source: data.source,
        tags: data.tags || []
      });

      console.log(`✅ Subscriber added: ${phoneNumber}`);
      return subscriber;
    } catch (error) {
      if (error.name === 'SequelizeUniqueConstraintError') {
        console.log(`⚠️ Subscriber already exists: ${phoneNumber}`);
        return await Subscriber.findOne({ where: { phoneNumber } });
      }
      throw error;
    }
  }

  async unsubscribe(phoneNumber) {
    await Subscriber.update(
      { status: 'unsubscribed' },
      { where: { phoneNumber } }
    );
    
    console.log(`🚫 Unsubscribed: ${phoneNumber}`);
  }

  async getActiveSubscribers(tags = []) {
    const where = { status: 'active' };
    
    if (tags.length > 0) {
      where.tags = {
        [Sequelize.Op.overlap]: tags // Match any of the tags
      };
    }

    const subscribers = await Subscriber.findAll({ where });
    return subscribers;
  }

  async addTag(phoneNumber, tag) {
    const subscriber = await Subscriber.findOne({ where: { phoneNumber } });
    
    if (subscriber && !subscriber.tags.includes(tag)) {
      const newTags = [...subscriber.tags, tag];
      await subscriber.update({ tags: newTags });
      console.log(`🏷️ Added tag "${tag}" to ${phoneNumber}`);
    }
  }

  async importFromCSV(filepath) {
    const fs = require('fs');
    const csv = require('csv-parser');
    
    const subscribers = [];
    
    return new Promise((resolve, reject) => {
      fs.createReadStream(filepath)
        .pipe(csv())
        .on('data', (row) => {
          subscribers.push(row);
        })
        .on('end', async () => {
          for (const sub of subscribers) {
            await this.addSubscriber(sub.phone, {
              name: sub.name,
              email: sub.email,
              source: 'csv-import'
            });
          }
          
          console.log(`✅ Imported ${subscribers.length} subscribers`);
          resolve(subscribers.length);
        })
        .on('error', reject);
    });
  }
}

module.exports = { SubscriberManager, Subscriber, Campaign, sequelize };

// broadcast-engine.js
const WhatsAppClient = require('./whatsapp-client');
const { SubscriberManager, Campaign } = require('./subscriber-manager');

class BroadcastEngine {
  constructor() {
    this.whatsapp = new WhatsAppClient();
    this.subscriberManager = new SubscriberManager();
    this.rateLimitDelay = 500; // 500ms delay between messages (anti-spam)
  }

  async createCampaign(campaignData) {
    try {
      const campaign = await Campaign.create(campaignData);
      console.log(`✅ Campaign created: ${campaign.name}`);
      return campaign;
    } catch (error) {
      console.error('Campaign creation error:', error);
      throw error;
    }
  }

  async sendBroadcast(campaignId) {
    try {
      const campaign = await Campaign.findByPk(campaignId);
      
      if (!campaign) {
        throw new Error('Campaign not found');
      }

      if (campaign.status === 'sent') {
        throw new Error('Campaign already sent');
      }

      // Update campaign status
      await campaign.update({ status: 'sending' });

      // Get target subscribers
      const subscribers = await this.subscriberManager.getActiveSubscribers(
        campaign.targetTags || []
      );

      console.log(`📤 Sending broadcast to ${subscribers.length} subscribers...`);

      let sentCount = 0;
      let failedCount = 0;

      for (const subscriber of subscribers) {
        try {
          // Send message (with image if provided)
          if (campaign.imageUrl) {
            await this.whatsapp.sendImage(
              subscriber.phoneNumber,
              campaign.imageUrl,
              campaign.message
            );
          } else {
            await this.whatsapp.sendMessage(
              subscriber.phoneNumber,
              campaign.message
            );
          }

          // Update subscriber stats
          await subscriber.update({
            lastMessageSent: new Date(),
            totalMessagesSent: subscriber.totalMessagesSent + 1
          });

          sentCount++;

          // Rate limiting (anti-spam, avoid WhatsApp blocks)
          await this.delay(this.rateLimitDelay);

        } catch (error) {
          console.error(`Failed to send to ${subscriber.phoneNumber}:`, error.message);
          failedCount++;
        }
      }

      // Update campaign stats
      await campaign.update({
        status: 'sent',
        sentAt: new Date(),
        totalSent: sentCount,
        totalDelivered: sentCount // Assume delivered if sent successfully
      });

      console.log(`✅ Broadcast complete: ${sentCount} sent, ${failedCount} failed`);

      return {
        sent: sentCount,
        failed: failedCount,
        campaignId: campaign.id
      };

    } catch (error) {
      console.error('Broadcast error:', error);
      throw error;
    }
  }

  async scheduleBroadcast(campaignId, sendAt) {
    const campaign = await Campaign.findByPk(campaignId);
    
    await campaign.update({
      status: 'scheduled',
      scheduledAt: sendAt
    });

    console.log(`📅 Campaign scheduled for ${sendAt}`);
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

module.exports = BroadcastEngine;

// message-templates.js
class MessageTemplates {
  // Product launch announcement
  static productLaunch(product) {
    return `
🎉 *NEW PRODUCT LAUNCH* 🎉

Introducing: *${product.name}*

${product.description}

💰 *Special Launch Price:* ~~${product.regularPrice}~~ *${product.launchPrice}*

⏰ *48-hour early access* for subscribers only!

👉 Shop now: ${product.url}

Reply "INTERESTED" to learn more! 💬
    `.trim();
  }

  // Weekly newsletter
  static newsletter(content) {
    return `
📰 *This Week's Highlights*

${content.headline}

${content.summary}

*Top picks this week:*
• ${content.pick1}
• ${content.pick2}
• ${content.pick3}

Read the full newsletter: ${content.url}

Reply with questions anytime! 💬
    `.trim();
  }

  // Flash sale alert
  static flashSale(sale) {
    return `
⚡ *FLASH SALE ALERT* ⚡

*${sale.discount}% OFF* ${sale.category}

⏰ *${sale.hoursLeft} HOURS LEFT*

*Featured deals:*
• ${sale.deal1}
• ${sale.deal2}
• ${sale.deal3}

🛍️ Shop now: ${sale.url}

Use code: *${sale.promoCode}*

Ends ${sale.endsAt}! ⏰
    `.trim();
  }

  // Event invitation
  static eventInvite(event) {
    return `
🎟️ *You're Invited!*

*${event.name}*

📅 ${event.date}
🕐 ${event.time}
📍 ${event.location}

${event.description}

*Special perks for you:*
• ${event.perk1}
• ${event.perk2}

RSVP here: ${event.rsvpUrl}

Limited spots available! 🎫

Reply "YES" to confirm attendance! 😊
    `.trim();
  }

  // Abandoned cart reminder
  static abandonedCart(cart) {
    return `
🛒 *You left something behind!*

Hi ${cart.customerName}! 👋

You have *${cart.itemCount} item(s)* waiting in your cart:

${cart.items.map(i => `• ${i.name} - ${i.price}`).join('\\n')}

*Total:* ${cart.total}

💡 *Complete your purchase now and get:*
✅ Free shipping
✅ ${cart.discount}% off with code ${cart.discountCode}

👉 Complete order: ${cart.checkoutUrl}

Expires in ${cart.hoursLeft} hours! ⏰
    `.trim();
  }

  // Customer win-back
  static winBack(customer) {
    return `
👋 *We miss you, ${customer.name}!*

It's been ${customer.daysSinceLastPurchase} days since your last order.

*Come back and get:*
🎁 ${customer.discount}% OFF your next order
📦 FREE shipping on orders $50+
⭐ Early access to new products

Use code: *${customer.couponCode}*

👉 Shop now: ${customer.shopUrl}

Valid for ${customer.daysValid} days only!

Reply if you need help! 💬
    `.trim();
  }

  // VIP exclusive offer
  static vipExclusive(offer) {
    return `
👑 *VIP EXCLUSIVE*

Hi ${offer.customerName}!

As one of our top customers, you get *exclusive early access* to:

*${offer.productName}*

${offer.description}

💎 *VIP Price:* ${offer.vipPrice} (${offer.discount}% off retail)

⏰ *24-hour exclusive window*

This is available ONLY to our VIP members before public launch.

🛍️ Claim yours: ${offer.url}

You're one of ${offer.totalVips} VIPs getting this! 🌟
    `.trim();
  }
}

module.exports = MessageTemplates;

// scheduler.js
const cron = require('node-cron');
const BroadcastEngine = require('./broadcast-engine');
const { Campaign } = require('./subscriber-manager');

class BroadcastScheduler {
  constructor() {
    this.broadcastEngine = new BroadcastEngine();
    this.isRunning = false;
  }

  start() {
    if (this.isRunning) {
      console.log('⚠️ Scheduler already running');
      return;
    }

    // Check for scheduled campaigns every minute
    this.job = cron.schedule('* * * * *', async () => {
      await this.checkScheduledCampaigns();
    });

    this.isRunning = true;
    console.log('✅ Broadcast scheduler started');
  }

  async checkScheduledCampaigns() {
    const now = new Date();

    // Find campaigns scheduled to send now (within last minute)
    const campaigns = await Campaign.findAll({
      where: {
        status: 'scheduled',
        scheduledAt: {
          [Sequelize.Op.lte]: now // Scheduled time passed
        }
      }
    });

    for (const campaign of campaigns) {
      console.log(`📤 Sending scheduled campaign: ${campaign.name}`);
      
      try {
        await this.broadcastEngine.sendBroadcast(campaign.id);
      } catch (error) {
        console.error(`Failed to send scheduled campaign ${campaign.id}:`, error);
        
        // Mark as failed
        await campaign.update({ status: 'cancelled' });
      }
    }
  }

  stop() {
    if (this.job) {
      this.job.stop();
      this.isRunning = false;
      console.log('🛑 Scheduler stopped');
    }
  }
}

module.exports = BroadcastScheduler;

const engine = new BroadcastEngine();
const templates = require('./message-templates');

// Create product launch campaign
const product = {
  name: 'Premium Wireless Earbuds',
  description: 'Noise-canceling, 30-hour battery, waterproof design.',
  regularPrice: 149.99,
  launchPrice: 99.99,
  url: 'https://shop.example.com/earbuds'
};

const campaign = await engine.createCampaign({
  name: 'Earbuds Launch - March 2026',
  message: templates.productLaunch(product),
  imageUrl: 'https://shop.example.com/images/earbuds.jpg',
  targetTags: ['newsletter', 'tech-enthusiast'], // Segment by tags
  scheduledAt: new Date('2026-03-15 09:00:00')
});

await engine.scheduleBroadcast(campaign.id, campaign.scheduledAt);

// Send flash sale to all active subscribers
const sale = {
  discount: 30,
  category: 'Electronics',
  hoursLeft: 6,
  deal1: 'Headphones $49 (reg. $99)',
  deal2: 'Smart Watch $79 (reg. $129)',
  deal3: 'Tablet $199 (reg. $299)',
  url: 'https://shop.example.com/flash-sale',
  promoCode: 'FLASH30',
  endsAt: 'Tonight at midnight'
};

await engine.createCampaign({
  name: 'Flash Sale - 30% Off Electronics',
  message: templates.flashSale(sale),
  targetTags: [], // Send to all subscribers
  status: 'draft'
});

// Send immediately
await engine.sendBroadcast(campaign.id);

// Automated abandoned cart broadcast (triggered by cart abandonment event)
async function sendAbandonedCartReminder(cart) {
  const engine = new BroadcastEngine();
  
  const message = templates.abandonedCart({
    customerName: cart.customer.name,
    itemCount: cart.items.length,
    items: cart.items,
    total: cart.total,
    discount: 10,
    discountCode: 'COMPLETE10',
    checkoutUrl: cart.checkoutUrl,
    hoursLeft: 24
  });

  // Send to single customer (not broadcast)
  await whatsapp.sendMessage(cart.customer.phone, message);
}

// Trigger 4 hours after cart abandonment
setTimeout(() => {
  sendAbandonedCartReminder(cart);
}, 4 * 60 * 60 * 1000); // 4 hours

// Segment by purchase behavior
await subscriberManager.addTag(customer.phone, 'high-spender'); // Spent $500+
await subscriberManager.addTag(customer.phone, 'frequent-buyer'); // 5+ purchases
await subscriberManager.addTag(customer.phone, 'new-customer'); // First purchase
await subscriberManager.addTag(customer.phone, 'inactive'); // No purchase in 90 days

// Send targeted campaigns
const vipCampaign = await engine.createCampaign({
  name: 'VIP Exclusive Offer',
  message: templates.vipExclusive(offer),
  targetTags: ['high-spender', 'frequent-buyer'] // Target big spenders only
});

// Tag by product interests
await subscriberManager.addTag(customer.phone, 'tech-enthusiast');
await subscriberManager.addTag(customer.phone, 'fashion-lover');
await subscriberManager.addTag(customer.phone, 'fitness-fan');

// Send relevant campaigns only
const techCampaign = await engine.createCampaign({
  name: 'New Tech Gadgets',
  message: '...',
  targetTags: ['tech-enthusiast'] // Only tech lovers get this
});

// Tag by location
await subscriberManager.addTag(customer.phone, 'us-east');
await subscriberManager.addTag(customer.phone, 'uk');
await subscriberManager.addTag(customer.phone, 'india');

// Send location-specific offers
const regionalCampaign = await engine.createCampaign({
  name: 'UK Flash Sale',
  message: '🇬🇧 UK-only flash sale! ...',
  targetTags: ['uk']
});

// Get campaign analytics
async function getCampaignAnalytics(campaignId) {
  const campaign = await Campaign.findByPk(campaignId);
  
  const openRate = ((campaign.totalOpened / campaign.totalSent) * 100).toFixed(1);
  const clickRate = ((campaign.totalClicks / campaign.totalOpened) * 100).toFixed(1);
  const ctr = ((campaign.totalClicks / campaign.totalSent) * 100).toFixed(1);
  
  return {
    campaignName: campaign.name,
    totalSent: campaign.totalSent,
    openRate: `${openRate}%`,
    clickRate: `${clickRate}%`, // Clicks / Opens
    ctr: `${ctr}%`, // Clicks / Sent
    revenue: await calculateCampaignRevenue(campaignId),
    roi: await calculateCampaignROI(campaignId)
  };
}

// Compare to email marketing benchmarks
function compareToBenchmarks(analytics) {
  return {
    ...analytics,
    vsEmail: {
      openRate: '+73%', // 98% WhatsApp vs 25% email
      clickRate: '+40%', // 45% WhatsApp vs 5% email
      roi: '+400%' // 5x better ROI
    }
  };
}

// Don't spam subscribers
const BROADCAST_RULES = {
  maxPerWeek: 3, // No more than 3 broadcasts/week
  minHoursBetween: 48, // Wait 48 hours between campaigns
  optimalTimes: ['09:00', '12:00', '18:00'], // Best send times
  avoidDays: ['Sunday'] // Don't send on Sundays
};

// Check if subscriber was messaged recently
async function canSendToSubscriber(subscriber) {
  const hoursSinceLastMessage = (Date.now() - subscriber.lastMessageSent) / (1000 * 60 * 60);
  
  return hoursSinceLastMessage >= BROADCAST_RULES.minHoursBetween;
}

// Handle unsubscribe requests
async function handleUnsubscribe(phoneNumber, message) {
  if (message.toLowerCase().includes('stop') || 
      message.toLowerCase().includes('unsubscribe')) {
    
    await subscriberManager.unsubscribe(phoneNumber);
    
    await whatsapp.sendMessage(
      phoneNumber,
      `You've been unsubscribed from our marketing messages. You won't receive promotional messages anymore.\n\nTo resubscribe, visit: ${process.env.APP_URL}/subscribe`
    );
    
    console.log(`🚫 Unsubscribed: ${phoneNumber}`);
  }
}

// Test two message variants
async function abTestCampaign(variantA, variantB, targetSubscribers) {
  const halfIndex = Math.floor(targetSubscribers.length / 2);
  
  const groupA = targetSubscribers.slice(0, halfIndex);
  const groupB = targetSubscribers.slice(halfIndex);
  
  // Send variant A
  const campaignA = await engine.createCampaign({
    name: 'Test A',
    message: variantA,
    targetTags: []
  });
  
  // Send variant B
  const campaignB = await engine.createCampaign({
    name: 'Test B',
    message: variantB,
    targetTags: []
  });
  
  // Compare results after 24 hours
  setTimeout(async () => {
    const analyticsA = await getCampaignAnalytics(campaignA.id);
    const analyticsB = await getCampaignAnalytics(campaignB.id);
    
    const winner = analyticsA.ctr > analyticsB.ctr ? 'A' : 'B';
    console.log(`🏆 Winner: Variant ${winner}`);
  }, 24 * 60 * 60 * 1000);
}