Skip to content

📱 WhatsApp Lite Channel - Appgain Notify

Confluence Documentation: WhatsApp Lite Channel

📹 Video Resources: WhatsApp Lite Setup & Tutorials

WhatsApp Lite Setup & Tutorials

🚀 Executive Summary

WhatsApp Lite is a Dockerized microservice within Appgain Notify, designed for scalable, automated WhatsApp messaging. It operates as a containerized Node.js application using whatsapp-web.js, supporting both individual and bulk messaging with advanced features like quota management, random delays, and campaign automation.

Key Capabilities

  • Containerized Architecture - Docker-based deployment per suit
  • High-Volume Messaging - Optimized for bulk campaigns and automation
  • Quota Management - 300 messages per day per suit limit
  • Multi-Media Support - Text, images, documents, videos, audio
  • Campaign Integration - Full Automator and Notify integration
  • Session Persistence - Maintains WhatsApp Web authentication

Technical Stack

  • Runtime: Node.js 16 with whatsapp-web.js
  • Container: Docker with Alpine Linux
  • Storage: Redis for quota management
  • Integration: REST APIs with Notify and Admin Server
  • Monitoring: Prometheus metrics and centralized logging

📊 System Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Appgain       │    │   WhatsApp Lite  │    │   WhatsApp      │
│   Notify        │◄──►│   Container      │◄──►│   Web           │
│   (Main App)    │    │   (Docker)       │    │   (Browser)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌──────────────────┐
│   Automator     │    │   Redis Cache    │
│   (Campaigns)   │    │   (Quota Mgmt)   │
└─────────────────┘    └──────────────────┘

Core Components

  1. WhatsApp Lite Container - Node.js microservice with whatsapp-web.js
  2. Notify Integration Layer - API endpoints for channel management
  3. Admin Server APIs - Container lifecycle management
  4. Redis Quota System - Daily message limits per suit
  5. Automator Integration - Campaign and automation support

🔧 Configuration & Deployment

Container Specifications

FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Environment Variables

PORT=3000
NODE_ENV=production
SUIT_ID=your-suit-id
ACCOUNT_ID=your-account-id
API_KEY=ask your direct manager for the access
ADMIN_SERVER_URL=https://admin-dashboard.instabackend.io
REDIS_HOST=appgaincenteralredis.instabackend.io
REDIS_PASSWORD=ask your direct manager for the access

Channel Configuration Schema

{
  "channels": {
    "uo-whatsapp": {
      "url": "http://container-ip:3000",
      "authenticated": true,
      "authenticatedDate": "2024-01-15T10:30:00Z",
      "container_name": "whatsapp-lite-suit-123",
      "port": 3000,
      "status": "active",
      "quota_limit": 300,
      "quota_reset_time": "00:00:00",
      "random_delay_min": 3,
      "random_string_enabled": true
    }
  }
}

📡 API Reference

Authentication & Status

Get QR Code for Authentication 

GET /whatsapp-login
Response: 
{
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "status": "waiting_for_scan"
}

Check Authentication Status 

GET /whatsapp-status
Response: 
{
  "authenticated": true,
  "status": "ready",
  "lastAuthenticated": "2024-01-15T10:30:00Z"
}

Message Sending

Send Individual Message 

POST /api/send-message
Content-Type: application/json

{
  "number": "1234567890",
  "message": "Hello from WhatsApp Lite!",
  "imageUrl": "https://example.com/image.jpg",
  "documentUrl": "https://example.com/document.pdf",
  "videoUrl": "https://example.com/video.mp4",
  "audioUrl": "https://example.com/audio.mp3"
}

Send via Notify Integration 

POST /{suit_id}/send
Content-Type: application/json
appApiKey: ask your direct manager for the access

{
  "UOWHATSAPP": {
    "message": "Hello from Notify!",
    "receivers": [
      {
        "mobileNum": "1234567890",
        "userID": "user123"
      }
    ],
    "imageUrl": "https://example.com/image.jpg"
  },
  "campaign_name": "Test Campaign",
  "campaign_id": "campaign123"
}

Admin Server APIs

Activate WhatsApp Channel 

POST /admin/whatsapp-lite/activate
Content-Type: application/json

{
  "suit_id": "5ac5c8f838f24a2ade257cdd",
  "container_name": "whatsapp-lite-suit-123",
  "port": 3000
}

Deactivate WhatsApp Channel 

POST /admin/whatsapp-lite/deactivate
Content-Type: application/json

{
  "suit_id": "5ac5c8f838f24a2ade257cdd"
}

🎯 Use Cases & Features

Primary Use Cases

  1. Channel Activation - Create and deploy Docker container
  2. Authentication Management - QR code generation and session persistence
  3. Message Sending - Individual and group message delivery
  4. Campaign Management - Bulk messaging with automation
  5. Automation Integration - Trigger-based and scheduled messaging

Key Features

  • Random Delay System - 3-minute minimum intervals between messages
  • Quota Management - 300 messages per day per suit limit
  • Media Support - Images, documents, videos, audio files
  • Group Management - Send to WhatsApp groups
  • Template Engine - Dynamic parameter substitution
  • Session Persistence - Maintains WhatsApp Web sessions
  • Error Handling - Comprehensive error management and retry logic

🔄 Integration Points

Notify Configuration

  • Dynamic channel discovery and registration
  • Template management with pre-approved messages
  • Rate limiting and throttling per channel
  • Webhook support for delivery status updates

Automator Integration

{
  "channel": "UOWHATSAPP",
  "message": "Hello {{user.name}}!",
  "receivers": "{{segment.users}}",
  "random_delay": true,
  "min_delay": 3,
  "random_string": true,
  "template_variables": {
    "user.name": "string",
    "campaign.id": "string"
  }
}

Redis Quota System

  • Quota Key Pattern: uo_whatsapp:{suit_id}:{YYYYMMDD}
  • Daily Limit: 300 messages per suit
  • TTL: 24 hours (automatic expiration)
  • Atomic Operations: Thread-safe quota management

🛠️ Deployment & Management

Deployment Steps

  1. Build Container Image - Docker build and registry push
  2. Deploy via Admin Server - Container creation and initialization
  3. Configure Notify - Channel registration and settings
  4. Authenticate WhatsApp - QR code scanning and verification

Production Setup

  • Load Balancer - Multiple container support
  • Health Checks - Container monitoring
  • Auto-scaling - Volume-based scaling
  • Backup Strategy - Regular state backups

Monitoring & Logging

  • Prometheus Metrics - Performance tracking
  • ELK Stack - Centralized logging
  • Alerting - Failure notifications
  • Dashboard - Real-time monitoring

🔧 Troubleshooting

Common Issues & Solutions

Container Won't Start

# Check container logs
docker logs whatsapp-lite-suit-123

# Verify environment variables
docker exec whatsapp-lite-suit-123 env

# Check port availability
netstat -tulpn | grep 3000

Authentication Issues

# Reset authentication
curl -X POST https://admin-dashboard.instabackend.io/admin/whatsapp-lite/reset-auth/{suit_id}

# Check authentication status
curl https://container-ip:3000/whatsapp-status

# Restart container
docker restart whatsapp-lite-suit-123

Message Sending Failures

# Check quota status
redis-cli get "uo_whatsapp:{suit_id}:{YYYYMMDD}"

# Verify container connectivity
curl https://container-ip:3000/whatsapp-status

# Check message logs
docker logs whatsapp-lite-suit-123 --tail 100

Debug Commands

# Container management
docker ps -a | grep whatsapp-lite
docker logs -f whatsapp-lite-suit-123
docker exec -it whatsapp-lite-suit-123 sh

# Network connectivity
curl -v https://container-ip:3000/whatsapp-status
telnet container-ip 3000

# Redis quota check
redis-cli keys "uo_whatsapp:*"
redis-cli get "uo_whatsapp:{suit_id}:{YYYYMMDD}"

# Notify configuration
curl -H "appApiKey: ask your direct manager for the access" \
  https://notify.appgain.io/{suit_id}/config

🔒 Security & Compliance

Security Measures

  • Container Security - Non-root execution, read-only filesystem
  • Network Security - Internal isolation, HTTPS/TLS encryption
  • Data Protection - Message encryption, secure session management
  • Access Control - API key authentication, rate limiting

Compliance

  • WhatsApp Business API - Content guidelines, rate limiting
  • GDPR Compliance - Data minimization, user consent
  • Security Standards - OWASP guidelines, regular audits

📈 Performance & Scalability

Performance Metrics

  • Throughput: 10,000+ messages per minute
  • Delivery Rate: 95%+ successful delivery
  • Latency: < 5 seconds average delivery time
  • Uptime: 99.9% service availability

Scalability Features

  • Container Isolation - Per-suit container deployment
  • Load Balancing - Multiple container support
  • Auto-scaling - Volume-based scaling
  • Resource Management - Memory and CPU limits

🚀 Roadmap & Future Enhancements

Planned Features

  1. Multi-Instance Support - Multiple WhatsApp accounts per suit
  2. Advanced Analytics - Detailed message analytics and reporting
  3. Template Engine - Rich media templates with dynamic content
  4. Webhook Integration - Real-time event notifications
  5. Scheduled Messages - Advanced scheduling capabilities
  6. A/B Testing - Message optimization features

Technical Improvements

  1. Performance Optimization - Faster message delivery
  2. Scalability Enhancements - Better handling of high message volumes
  3. Reliability Improvements - Enhanced error handling and recovery
  4. Monitoring Enhancements - Better observability and alerting

📚 Support & Resources

Getting Help

  • Technical Support: Contact the development team
  • Documentation: Refer to this page and API documentation
  • Issue Tracking: Report bugs via GitLab issues
  • Community: Join the Appgain developer community

Additional Resources

Overview

The WhatsApp Lite Channel is a specialized component within the Appgain Notify service that provides lightweight, efficient WhatsApp Business API integration for sending notifications, marketing messages, and automated communications to customers. This channel is optimized for high-volume messaging with minimal resource consumption.

Key Features

Lite Architecture

  • Minimal Resource Usage - Optimized for high-volume messaging
  • Fast Message Delivery - Reduced latency for better user experience
  • Scalable Design - Handles thousands of messages per minute
  • Cost-Effective - Lower operational costs compared to full WhatsApp Business API

Message Types Supported

  • Text Messages - Simple text notifications
  • Media Messages - Images, documents, and audio files
  • Template Messages - Pre-approved message templates
  • Interactive Messages - Buttons and quick replies
  • Location Messages - Share location information

Integration Capabilities

  • REST API - Simple HTTP-based integration
  • Webhook Support - Real-time delivery status updates
  • Batch Processing - Send multiple messages efficiently
  • Rate Limiting - Built-in compliance with WhatsApp limits

Technical Architecture

Component Structure

WhatsApp Lite Channel
├── Message Queue
├── Template Manager
├── Rate Limiter
├── Delivery Tracker
├── Error Handler
└── Webhook Processor

Data Flow

  1. Message Reception - Messages received from Appgain Notify
  2. Template Processing - Apply approved message templates
  3. Rate Limiting - Ensure compliance with WhatsApp limits
  4. Message Sending - Deliver via WhatsApp Business API
  5. Status Tracking - Monitor delivery and read receipts
  6. Webhook Processing - Handle delivery confirmations

Configuration

Environment Variables

# WhatsApp Business API Configuration
WHATSAPP_API_URL=https://graph.facebook.com/v17.0
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_VERIFY_TOKEN=your_verify_token

# Channel Configuration
WHATSAPP_LITE_MAX_RETRIES=3
WHATSAPP_LITE_RATE_LIMIT=1000
WHATSAPP_LITE_BATCH_SIZE=50
WHATSAPP_LITE_TIMEOUT=30000

API Endpoints

  • POST /a../whatsapp/send - Send single message
  • POST /a../whatsapp/send-batch - Send multiple messages
  • GET /a../whatsapp/status/:messageId - Check message status
  • POST /a../whatsapp/webhook - Receive delivery updates

Message Templates

Pre-approved Templates

  • Welcome Messages - New customer onboarding
  • Order Updates - Order status notifications
  • Promotional Offers - Marketing campaigns
  • Appointment Reminders - Schedule confirmations
  • Support Messages - Customer service communications

Template Variables

{
  "template_name": "order_update",
  "language": "en",
  "variables": {
    "customer_name": "{{customer_name}}",
    "order_number": "{{order_number}}",
    "order_status": "{{order_status}}",
    "tracking_url": "{{tracking_url}}"
  }
}

Integration with Appgain Notify

Channel Registration

// Register WhatsApp Lite Channel
const whatsappChannel = {
  name: 'whatsapp_lite',
  type: 'whatsapp',
  config: {
    apiUrl: process.env.WHATSAPP_API_URL,
    phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
    accessToken: process.env.WHATSAPP_ACCESS_TOKEN
  },
  capabilities: ['text', 'media', 'template', 'interactive']
};

notifyService.registerChannel(whatsappChannel);

Message Sending

// Send message via WhatsApp Lite Channel
const message = {
  channel: 'whatsapp_lite',
  recipient: '+1234567890',
  template: 'order_update',
  variables: {
    customer_name: 'John Doe',
    order_number: 'ORD-12345',
    order_status: 'Shipped',
    tracking_url: 'https://track.example.com/12345'
  }
};

const result = await notifyService.send(message);

Error Handling

Common Error Types

  • Rate Limit Exceeded - Too many messages sent
  • Invalid Template - Template not approved or expired
  • Invalid Phone Number - Recipient number format error
  • API Authentication - Invalid access token
  • Network Timeout - Connection issues

Retry Logic

const retryConfig = {
  maxRetries: 3,
  backoffMultiplier: 2,
  initialDelay: 1000,
  maxDelay: 30000
};

Monitoring & Analytics

Key Metrics

  • Message Delivery Rate - Percentage of successful deliveries
  • Response Time - Average time to deliver messages
  • Error Rate - Percentage of failed messages
  • Template Usage - Most used message templates
  • Peak Usage Times - High-volume periods

Dashboard Integration

  • Grafana Dashboards - Real-time monitoring
  • Prometheus Metrics - Performance tracking
  • Alert Rules - Automated notifications
  • Log Aggregation - Centralized logging

Best Practices

Message Optimization

  • Keep Messages Concise - WhatsApp has character limits
  • Use Templates Wisely - Pre-approved templates for consistency
  • Include Clear CTAs - Call-to-action buttons when appropriate
  • Personalize Content - Use customer-specific variables
  • Test Before Sending - Verify template formatting

Rate Limiting

  • Respect WhatsApp Limits - 1000 messages per second per phone number
  • Implement Backoff - Exponential backoff for retries
  • Monitor Usage - Track API usage and limits
  • Queue Management - Handle message queuing efficiently

Security Considerations

  • Token Management - Secure storage of access tokens
  • Webhook Validation - Verify webhook authenticity
  • Data Encryption - Encrypt sensitive message content
  • Access Control - Restrict channel access to authorized users

Troubleshooting

Common Issues

Message Not Delivered

  1. Check phone number format (international format required)
  2. Verify template approval status
  3. Review rate limiting configuration
  4. Check API authentication credentials

Template Errors

  1. Ensure template is approved by WhatsApp
  2. Verify template variables match exactly
  3. Check template language settings
  4. Review template expiration dates

Rate Limiting Issues

  1. Monitor current usage rates
  2. Implement proper queuing mechanisms
  3. Use multiple phone numbers if needed
  4. Optimize message sending patterns

Debug Mode

// Enable debug logging
const debugConfig = {
  enableDebug: true,
  logLevel: 'debug',
  logWebhooks: true,
  logAPIRequests: true
};

Development & Testing

Local Development

# Start WhatsApp Lite Channel locally
npm run dev:whatsapp-lite

# Run tests
npm test:whatsapp-lite

# Test webhook locally
ngrok http 3000

Testing Templates

// Test template rendering
const testTemplate = {
  name: 'test_template',
  language: 'en',
  variables: {
    test_var: 'Test Value'
  }
};

const rendered = await whatsappLite.renderTemplate(testTemplate);
console.log(rendered);

API Reference

Send Message

POST /a../whatsapp/send
Content-Type: application/json

{
  "recipient": "+1234567890",
  "template": "order_update",
  "variables": {
    "customer_name": "John Doe",
    "order_number": "ORD-12345"
  }
}

Send Batch

POST /a../whatsapp/send-batch
Content-Type: application/json

{
  "messages": [
    {
      "recipient": "+1234567890",
      "template": "welcome",
      "variables": {"name": "John"}
    },
    {
      "recipient": "+0987654321",
      "template": "promotion",
      "variables": {"offer": "20% off"}
    }
  ]
}

Check Status

GET /a../whatsapp/status/msg_123456789

📹 Video Resources & Tutorials

Available Video Content

Video Description File
UOWa with Notify AdminServer Automator Complete setup and integration tutorial 📹 UOWa_with_notriy_adminServer_automator.mp4
WhatsApp Code Examples Code samples and implementation guides 📁 UOWhatsapp_Code
Webhook Examples Webhook configuration and testing 🖼️ webhookExamples.jpg

Video Topics Covered

  • Setup & Installation - Initial WhatsApp Lite Channel deployment
  • Integration with Notify - Connecting to the main notification service
  • Admin Server Configuration - Container management and monitoring
  • Automator Integration - Campaign automation setup
  • Webhook Configuration - Event handling and callbacks
  • Code Examples - Implementation patterns and best practices

How to Use These Videos

  1. Start with the main tutorial - UOWa_with_notriy_adminServer_automator.mp4
  2. Review code examples - Check the UOWhatsapp_Code folder
  3. Study webhook setup - Use webhookExamples.jpg as reference
  4. Follow along - Pause and rewind as needed for your setup

Support & Maintenance

Regular Maintenance

  • Template Review - Monthly template approval checks
  • Rate Limit Monitoring - Daily usage monitoring
  • Error Log Analysis - Weekly error pattern analysis
  • Performance Optimization - Quarterly performance reviews

Emergency Contacts

The WhatsApp Lite Channel provides efficient, scalable WhatsApp messaging capabilities for the Appgain Notify service, enabling businesses to communicate effectively with their customers through one of the world's most popular messaging platforms.

Ask Chehab GPT