setupautomatizado/whatsapp-flows-server

•Updated 11 months ago

WhatsApp Flow Server

Image

2.4K

setupautomatizado/whatsapp-flows-server repository overview

⁠WhatsApp Flows Server

Production-ready Node.js server for WhatsApp Flows with automated CI/CD, multi-arch Docker support, and DDD architecture

Features⁠ • Quick Start⁠ • Documentation⁠ • Architecture⁠ • Contributing⁠

⁠📖 Overview

WhatsApp Flow Server is a robust, production-ready TypeScript server that implements the WhatsApp Flows API⁠ using Domain-Driven Design (DDD) principles. It provides a complete solution for handling WhatsApp Flow interactions with built-in encryption, webhook processing, and comprehensive CI/CD automation.

⁠🎯 What Problem Does It Solve?

WhatsApp Flows enable rich, interactive experiences within WhatsApp, but implementing them requires:

Complex encryption (RSA-2048 + AES-128-GCM with mandatory IV flip)
Dual endpoint architecture (Flow Data API + Webhooks)
Strict performance requirements (<3s response time)
Secure key management and Meta API integration
Production-ready infrastructure with monitoring and scaling

This server solves all these challenges with:

✅ Pre-configured encryption with IV flip pattern
✅ Dual endpoint architecture out-of-the-box
✅ Automatic database migrations
✅ Multi-architecture Docker support (AMD64 + ARM64)
✅ Complete CI/CD pipeline with semantic versioning
✅ Production-ready with health checks and logging

⁠✨ Features

⁠Core Capabilities

🏗️ Domain-Driven Design - Clean architecture with separated layers (Domain, Application, Infrastructure)
🔐 WhatsApp Flow Encryption - Complete RSA-2048 + AES-128-GCM implementation with mandatory IV flip
🔄 Dual Endpoint System - Flow Data API + Webhook receiver with signature validation
📊 PostgreSQL Storage - Persistent storage for Flows, Sessions, and Responses
✅ Schema Validation - Type-safe with Zod v4
📝 Structured Logging - Winston with rotation and multiple transports

⁠DevOps & Deployment

🐳 Multi-Arch Docker - Native support for AMD64 (Intel/AMD) and ARM64 (Apple Silicon, AWS Graviton)
🚀 Automated CI/CD - GitHub Actions with semantic release and Docker Hub publishing
📦 Conventional Commits - Automated versioning and changelog generation
🔄 Auto Migrations - Database migrations run automatically on container startup
💪 Production Ready - Health checks, monitoring, and graceful shutdown

⁠Developer Experience

🛠️ TypeScript 5.9 - Full type safety with strict mode
🎨 Modern Stack - Express 5.x, PostgreSQL 18, Node.js 20+
🔧 Developer Tools - ESLint, Prettier, Husky, Commitlint
📖 Comprehensive Docs - Complete guides for setup, deployment, and troubleshooting
🧪 Testing Ready - Structure prepared for unit and integration tests

⁠🏛️ Architecture

⁠System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        WhatsApp Platform                         │
└────────────┬──────────────────────────────────────┬─────────────┘
             │                                      │
             │ Encrypted Flow Data                  │ Webhook Events
             │ (RSA-2048 + AES-128-GCM)            │ (nfm_reply)
             ▼                                      ▼
┌─────────────────────────────┐      ┌──────────────────────────┐
│   Flow Endpoint (Data API)  │      │   Webhook Endpoint       │
│   POST /flows/endpoint/:id  │      │   POST /webhooks/whatsapp│
│                             │      │                          │
│   - Decrypt request         │      │   - Validate signature   │
│   - Process action          │      │   - Parse response_json  │
│   - Return encrypted data   │      │   - Forward to callback  │
│   - < 3s response time      │      │   - Store in database    │
└──────────────┬──────────────┘      └──────────┬───────────────┘
               │                                │
               │                                │
               ▼                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Application Layer                        │
│                                                                  │
│  ┌──────────────────────┐        ┌─────────────────────────┐   │
│  │ HandleFlowRequest    │        │ ProcessWebhook          │   │
│  │ UseCase              │        │ UseCase                 │   │
│  └──────────┬───────────┘        └───────────┬─────────────┘   │
│             │                                 │                 │
│             ▼                                 ▼                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Domain Layer (Business Logic)              │   │
│  │                                                          │   │
│  │  • FlowEngine - Navigation and data exchange           │   │
│  │  • Flow - Immutable Flow templates                     │   │
│  │  • FlowSession - User session tracking                 │   │
│  │  • FlowResponse - Completed Flow data                  │   │
│  │  • EncryptionService - RSA/AES with IV flip            │   │
│  └──────────────────────────┬───────────────────────────────┘   │
│                             │                                   │
└─────────────────────────────┼───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                          │
│                                                                  │
│  ┌──────────────────┐  ┌─────────────────┐  ┌───────────────┐  │
│  │   PostgreSQL     │  │   Express HTTP  │  │   Axios HTTP  │  │
│  │   Repositories   │  │   Server        │  │   Client      │  │
│  └──────────────────┘  └─────────────────┘  └───────────────┘  │
│                                                                  │
│  Database Tables:                                               │
│  • flows - Flow JSON templates                                 │
│  • flow_sessions - Active/completed sessions                   │
│  • flow_responses - Completed Flow data                        │
│  • webhook_events - Webhook audit trail                        │
└─────────────────────────────────────────────────────────────────┘

⁠Flow Interaction Sequence

User                WhatsApp          Flow Server         Database        Your System
  │                    │                    │                 │                │
  │ Click Flow Button  │                    │                 │                │
  ├───────────────────>│                    │                 │                │
  │                    │                    │                 │                │
  │                    │ POST /flows/endpoint (INIT)          │                │
  │                    ├───────────────────>│                 │                │
  │                    │                    │ Create Session  │                │
  │                    │                    ├────────────────>│                │
  │                    │                    │ Return INIT     │                │
  │                    │<───────────────────┤                 │                │
  │                    │                    │                 │                │
  │  Display Screen 1  │                    │                 │                │
  │<───────────────────┤                    │                 │                │
  │                    │                    │                 │                │
  │ Fill & Submit      │                    │                 │                │
  ├───────────────────>│                    │                 │                │
  │                    │ POST /flows/endpoint (data_exchange) │                │
  │                    ├───────────────────>│                 │                │
  │                    │                    │ Update Session  │                │
  │                    │                    ├────────────────>│                │
  │                    │                    │ Return Screen 2 │                │
  │                    │<───────────────────┤                 │                │
  │                    │                    │                 │                │
  │  Display Screen 2  │                    │                 │                │
  │<───────────────────┤                    │                 │                │
  │                    │                    │                 │                │
  │ Complete Flow      │                    │                 │                │
  ├───────────────────>│                    │                 │                │
  │                    │ POST /flows/endpoint (complete)      │                │
  │                    ├───────────────────>│                 │                │
  │                    │                    │ Mark Complete   │                │
  │                    │                    ├────────────────>│                │
  │                    │                    │                 │                │
  │                    │ POST /webhooks/whatsapp (nfm_reply)  │                │
  │                    ├───────────────────>│                 │                │
  │                    │                    │ Store Response  │                │
  │                    │                    ├────────────────>│                │
  │                    │                    │ Forward Data    │                │
  │                    │                    ├────────────────────────────────>│
  │                    │                    │                 │                │
  │  "Thank you!"      │                    │                 │                │
  │<───────────────────┤                    │                 │                │

⁠Encryption Flow (IV Flip Pattern)

WhatsApp Request                    Server Response
     │                                    │
     │  Encrypted with:                  │  Encrypted with:
     │  • AES key encrypted by RSA       │  • FLIPPED IV ⚠️
     │  • Normal IV                      │  • Same AES key
     │                                   │
     ▼                                   ▼
┌────────────────┐              ┌────────────────┐
│ Decrypt AES Key│              │ Flip IV Buffer │
│ with RSA       │              │ (reverse bytes)│
└───────┬────────┘              └────────┬───────┘
        │                                │
        ▼                                ▼
┌────────────────┐              ┌────────────────┐
│ Decrypt Payload│              │ Encrypt Payload│
│ with AES       │              │ with AES       │
│ (normal IV)    │              │ (flipped IV)   │
└───────┬────────┘              └────────┬───────┘
        │                                │
        ▼                                ▼
   Flow Data                      Encrypted Response

⁠🚀 Quick Start

⁠Prerequisites

Node.js >= 20.0.0
Docker & Docker Compose (recommended) or PostgreSQL 18+
WhatsApp Business Account with Flows enabled
Meta Developer Account for API credentials

⁠Option 1: Docker (Recommended)

# 1. Clone the repository
git clone https://github.com/guilhermejansen/whatsapp-flows-server.git
cd whatsapp-flows-server

# 2. Configure environment
cp .env.docker.example .env
nano .env  # Edit with your credentials

# 3. Start services
docker-compose up -d

# 4. Generate encryption keys
docker-compose exec app npm run generate-keys
# Copy output to .env

# 5. Restart application
docker-compose restart app

# 6. Register public key with Meta
docker-compose exec app npm run register-key

# 7. Verify health
curl http://localhost:3000/health

Your server is now running! 🎉

Configure WhatsApp Manager:

Flow Endpoint: https://your-domain.com/flows/endpoint/csat-feedback
Webhook URL: https://your-domain.com/webhooks/whatsapp

⁠Option 2: Local Development

# 1. Clone and install
git clone https://github.com/guilhermejansen/whatsapp-flows-server.git
cd whatsapp-flows-server
npm install

# 2. Setup PostgreSQL
createdb whatsapp_flows
npm run migrate

# 3. Generate keys
npm run generate-keys
# Copy output to .env

# 4. Configure environment
cp .env.example .env
nano .env  # Edit with your credentials

# 5. Register public key
npm run register-key

# 6. Start development server
npm run dev

⁠📦 Docker Deployment

⁠Multi-Architecture Support

Pre-built images available for AMD64 (Intel/AMD) and ARM64 (Apple Silicon, AWS Graviton):

# Pull latest version
docker pull setupautomatizado/whatsapp-flows-server:latest

# Or specific version
docker pull setupautomatizado/whatsapp-flows-server:1.0.0

⁠Production Deployment

⁠1. Server Setup

# Create directory
mkdir -p ~/whatsapp-flows-server-production
cd ~/whatsapp-flows-server-production

# Download compose file
curl -O https://raw.githubusercontent.com/guilhermejansen/whatsapp-flows-server/main/docker-compose.yml

# Configure environment
curl -O https://raw.githubusercontent.com/guilhermejansen/whatsapp-flows-server/main/.env.docker.example
cp .env.docker.example .env
nano .env

⁠2. SSL Setup (Nginx + Let's Encrypt)

# Install Nginx + Certbot
sudo apt update
sudo apt install nginx certbot python3-certbot-nginx -y

# Configure Nginx
sudo nano /etc/nginx/sites-available/whatsapp-flows-server

Nginx Configuration:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WhatsApp requires < 3s response
        proxy_connect_timeout 2s;
        proxy_send_timeout 2s;
        proxy_read_timeout 2s;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/whatsapp-flows-server /etc/nginx/sites-enabled/
sudo nginx -t

# Get SSL certificate
sudo certbot --nginx -d your-domain.com

# Restart Nginx
sudo systemctl restart nginx

⁠3. Start Application

# Start services
docker-compose up -d

# Generate keys
docker-compose exec app npm run generate-keys
# Add keys to .env

# Restart
docker-compose restart app

# Register public key
docker-compose exec app npm run register-key

# Verify
curl https://your-domain.com/health

⁠Available Commands

# View logs
docker-compose logs -f app

# Shell access
docker-compose exec app sh

# Database access
docker-compose exec postgres psql -U whatsapp_flow -d whatsapp_flows

# Run migrations manually
docker-compose exec app npm run migrate

# Backup database
docker-compose exec postgres pg_dump -U whatsapp_flow whatsapp_flows > backup.sql

# Stop services
docker-compose down

⁠🔧 Configuration

⁠Environment Variables

Variable	Description	Required	Example
`NODE_ENV`	Environment mode	✅	`production`
`PORT`	Server port	✅	`3000`
`DATABASE_URL`	PostgreSQL connection string	✅	`postgresql://user:pass@localhost:5432/db`
`PRIVATE_KEY`	RSA private key (PEM format)	✅	`-----BEGIN RSA PRIVATE KEY-----\n...`
`PUBLIC_KEY`	RSA public key (PEM format)	✅	`-----BEGIN PUBLIC KEY-----\n...`
`META_APP_SECRET`	Meta app secret	✅	`your_app_secret`
`META_VERIFY_TOKEN`	Webhook verify token	✅	`your_verify_token`
`META_ACCESS_TOKEN`	WhatsApp API access token	✅	`EAAB...`
`CALLBACK_WEBHOOK_URL`	Your callback URL for completed flows	✅	`https://yourapi.com/webhook`
`DEFAULT_FLOW_NAME`	Default flow when not specified	⚠️	`csat-feedback`
`FLOW_ENDPOINT_TIMEOUT`	Max response time (< 3000ms)	⚠️	`2500`
`CORS_ORIGINS`	Allowed CORS origins	⚠️	`https://app.com`
`API_TOKEN`	API authentication token	⚠️	Generated with `openssl rand -hex 32`

Legend: ✅ Required | ⚠️ Recommended

⁠Key Generation

# Generate RSA-2048 key pair
npm run generate-keys

# Validate keys
npm run validate-keys

# Register public key with Meta
npm run register-key

⁠🔐 Security

⁠Encryption Implementation

This server implements WhatsApp's mandatory IV flip pattern for encryption:

// Decryption (incoming from WhatsApp) - Normal IV
const iv = Buffer.from(initialVector, 'base64');
const decipher = crypto.createDecipheriv('aes-128-gcm', aesKey, iv);

// Encryption (outgoing to WhatsApp) - FLIPPED IV ⚠️
const iv = Buffer.from(initialVector, 'base64');
const flippedIV = Buffer.from(iv).reverse(); // Must reverse!
const cipher = crypto.createCipheriv('aes-128-gcm', aesKey, flippedIV);

Critical: If IV is not flipped, WhatsApp returns error 421.

⁠Security Best Practices

✅ Never commit private keys to Git
✅ Use environment variables for all secrets
✅ Rotate tokens every 3-6 months
✅ Enable HTTPS in production (required by WhatsApp)
✅ Validate webhooks with X-Hub-Signature-256
✅ Run as non-root user in Docker
✅ Keep dependencies updated via Dependabot

See SECURITY.md⁠ for vulnerability reporting.

⁠🛣️ API Reference

⁠Flow Endpoint (Data API)

Endpoint: POST /flows/endpoint/:flowName

Handles encrypted interactions during Flow execution.

Actions:

ping - Health check
INIT - Initialize Flow session
data_exchange - Process user input and navigate
navigate - Explicit screen navigation
complete - Mark Flow as completed

Headers:

Content-Type: application/json

Example Request (INIT):

{
  "version": "3.0",
  "action": "INIT",
  "flow_token": "unique_token_123",
  "encrypted_flow_data": "...",
  "encrypted_aes_key": "...",
  "initial_vector": "..."
}

Response: Encrypted Flow data with next screen

⁠Webhook Endpoint

Endpoint: POST /webhooks/whatsapp

Receives nfm_reply events when user completes Flow.

Headers:

Content-Type: application/json
X-Hub-Signature-256: sha256=...

Example Payload:

{
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "type": "interactive",
          "interactive": {
            "type": "nfm_reply",
            "nfm_reply": {
              "response_json": "{\"flow_token\":\"...\",\"data\":...}",
              "name": "flow_name"
            }
          }
        }]
      }
    }]
  }]
}

Important: response_json is a string, must be parsed with JSON.parse().

⁠Health Check

Endpoint: GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-01-27T12:00:00.000Z",
  "version": "1.0.0",
  "uptime": 3600,
  "database": "connected"
}

⁠Swagger Documentation

Interactive API docs available at /docs when server is running.

⁠📚 Documentation

⁠Official WhatsApp Flows Resources

⁠🧪 Development

⁠Project Structure

whatsapp-flow/
├── src/
│   ├── domain/              # Business entities and rules
│   │   ├── flows/           # Flow, FlowSession entities
│   │   ├── encryption/      # Encryption services
│   │   └── webhooks/        # Webhook events
│   ├── application/         # Use cases (business logic)
│   │   ├── dtos/            # Da

Tag summary

Recent tags

Content type

Image

Digest

sha256:b2006710a…

Size

85 MB

Last updated

11 months ago

docker pull setupautomatizado/whatsapp-flows-server