​
Environment Variables Reference

Complete guide to all environment variables needed to configure WhatsApp Team Inbox.

​
TL;DR - Essential Variables

Minimum required to run:
VariableGet FromExample
DATABASE_URLPostgreSQLpostgresql://user:pass@host:5432/db
WHATSAPP_ACCESS_TOKENMeta Business SuiteEAAxxxxx...
WHATSAPP_PHONE_NUMBER_IDWhatsApp API Setup123456789012345
WHATSAPP_BUSINESS_ACCOUNT_IDWhatsApp Accounts123456789012345
WHATSAPP_WEBHOOK_VERIFY_TOKENYou createopenssl rand -hex 16
JWT_SECRETGenerateopenssl rand -hex 32
JWT_REFRESH_SECRETGenerateopenssl rand -hex 32
ADMIN_EMAILYour emailadmin@company.com
ADMIN_PASSWORDStrong passwordMin 8 chars
CORS_ORIGINFrontend URLhttps://app.company.com
NEXT_PUBLIC_API_BASE_URLBackend URLhttps://api.company.com
NEXT_PUBLIC_WS_URLWebSocket URLwss://api.company.com
Quick generate secrets: 
openssl rand -hex 32  # For JWT secrets
openssl rand -hex 16  # For webhook token

​
Quick Setup

Copy the example file and customize: 
cp .env.example .env

​
Required Variables

These variables must be set for the application to function:

​
Database Configuration

​
POSTGRES_USER
string
required
PostgreSQL database usernameDefault: postgres
​
POSTGRES_PASSWORD
string
required
PostgreSQL database passwordSecurity: Use a strong password (16+ characters). Generate with:
openssl rand -base64 32
​
POSTGRES_DB
string
required
PostgreSQL database nameDefault: whatsapp_inbox
​
DATABASE_URL
string
required
Full PostgreSQL connection URLFormat: postgresql://user:password@host:port/databaseExample: postgresql://postgres:secretpass@postgres:5432/whatsapp_inbox

​
WhatsApp Business API

Get these credentials from Meta Business Suite. See WhatsApp Setup Guide for details.
​
WHATSAPP_API_URL
string
required
WhatsApp API endpoint URLDefault: https://graph.facebook.com/v21.0Note: v21.0 is the recommended version for 2025
​
WHATSAPP_ACCESS_TOKEN
string
required
Permanent access token from Meta Business SuiteHow to get:
  1. Go to Meta Business Suite
  2. Navigate to System Users
  3. Generate a permanent token with whatsapp_business_messaging permission
Security: Never commit this to version control
​
WHATSAPP_PHONE_NUMBER_ID
string
required
Your WhatsApp Business phone number IDFormat: 15-digit number (e.g., 123456789012345)Location: Meta Business Suite → WhatsApp → API Setup
​
WHATSAPP_BUSINESS_ACCOUNT_ID
string
required
Your WhatsApp Business Account IDFormat: 15-digit numberLocation: Meta Business Suite → Business Settings → WhatsApp Accounts
​
WHATSAPP_WEBHOOK_VERIFY_TOKEN
string
required
Webhook verification token (you create this)Generate with:
openssl rand -hex 16
Usage: Set the same token in Meta Business Suite webhook configuration

​
Security & Authentication

​
JWT_SECRET
string
required
Secret key for signing JWT access tokensGenerate with:
openssl rand -hex 32
Security: Must be at least 32 characters, use cryptographically secure random generation
​
JWT_REFRESH_SECRET
string
required
Secret key for signing JWT refresh tokensGenerate with:
openssl rand -hex 32
Note: Must be different from JWT_SECRET
​
JWT_EXPIRES_IN
string
default:"7d"
Access token expiration timeFormat: Use time units like 15m, 1h, 7d, 30dRecommended: 7d for web apps, 15m for high-security apps
​
JWT_REFRESH_EXPIRES_IN
string
default:"30d"
Refresh token expiration timeFormat: Use time units like 7d, 30d, 90dRecommended: 30d

​
Admin User

These credentials are used to create the initial admin account on first deployment.
​
ADMIN_EMAIL
string
required
Admin user email addressExample: admin@yourcompany.comNote: Change password immediately after first login
​
ADMIN_PASSWORD
string
required
Admin user initial passwordRequirements: Minimum 8 characters (16+ recommended)Security: Use a strong password generator
​
ADMIN_FIRST_NAME
string
default:"System"
Admin user first name
​
ADMIN_LAST_NAME
string
default:"Administrator"
Admin user last name

​
Application URLs

​
APP_URL
string
required
Frontend application URLDevelopment: http://localhost:3000Production: https://your-domain.com
​
CORS_ORIGIN
string
required
Allowed CORS origins (comma-separated for multiple)Development: http://localhost:3000Production: https://your-domain.com,https://app.your-domain.comSecurity: Never use * in production
​
NEXT_PUBLIC_API_BASE_URL
string
required
Backend API URL (frontend environment variable)Development: http://localhost:4000Production: https://api.your-domain.com
​
NEXT_PUBLIC_WS_URL
string
required
WebSocket server URL (frontend environment variable)Development: ws://localhost:4001Production: wss://api.your-domain.com

​
Optional Variables

​
Port Configuration

​
FRONTEND_PORT
number
default:"3000"
Port for Next.js frontend server
​
BACKEND_PORT
number
default:"4000"
Port for Express backend API
​
WS_PORT
number
default:"4001"
Port for WebSocket server
​
POSTGRES_PORT
number
default:"5432"
Port for PostgreSQL database
​
REDIS_PORT
number
default:"6379"
Port for Redis (if enabled)

​
Email Configuration (Resend)

Required for sending invitation emails, password resets, and notifications.
​
RESEND_API_KEY
string
Resend API key for sending emailsGet from: resend.com → Dashboard → API KeysExample: re_123abc456def789ghi012jkl345mno678Note: Free tier includes 100 emails/day (3,000/month)
​
FROM_EMAIL
string
default:"onboarding@resend.dev"
Email address to send fromDevelopment: Use default onboarding@resend.devProduction: Use verified domain noreply@yourdomain.comNote: Verify your domain in Resend dashboard for production use
​
FROM_NAME
string
default:"Team Inbox"
Display name for email senderExample: WhatsApp Team Inbox or Your Company Name

​
Push Notifications (Web Push)

Required for browser push notifications.
​
VAPID_PUBLIC_KEY
string
VAPID public key for Web PushGenerate with:
npx web-push generate-vapid-keys
​
VAPID_PRIVATE_KEY
string
VAPID private key for Web PushSecurity: Keep this secret, never expose to frontend
​
VAPID_SUBJECT
string
Contact URL or email for VAPIDFormat: mailto:admin@your-domain.com or https://your-domain.com

​
Redis (Optional)

Enables caching and session storage for improved performance.
​
REDIS_URL
string
Redis connection URLDocker Compose: redis://redis:6379External: redis://username:password@host:port
​
REDIS_PASSWORD
string
Redis authentication password (if required)

​
Monitoring & Logging

​
NODE_ENV
string
default:"production"
Application environmentOptions: development, production, test
​
LOG_LEVEL
string
default:"info"
Logging levelOptions: error, warn, info, debugProduction: Use info or warnDevelopment: Use debug
​
SENTRY_DSN
string
Sentry Data Source Name for error trackingGet from: Sentry.io project settings

​
Environment-Specific Configuration

​
Development (.env.development)

NODE_ENV=development
APP_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3000
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
NEXT_PUBLIC_WS_URL=ws://localhost:4001
LOG_LEVEL=debug

​
Production (.env.production)

NODE_ENV=production
APP_URL=https://your-domain.com
CORS_ORIGIN=https://your-domain.com
NEXT_PUBLIC_API_BASE_URL=https://api.your-domain.com
NEXT_PUBLIC_WS_URL=wss://api.your-domain.com
LOG_LEVEL=info

​
Security Best Practices

Never commit .env files to version control!Add to .gitignore:
.env
.env.local
.env.production
.env.*.local

​
Secret Generation

Generate strong secrets: 
# JWT secrets (256-bit)
openssl rand -hex 32

# Database password (base64)
openssl rand -base64 32

# Webhook verify token
openssl rand -hex 16

# VAPID keys
npx web-push generate-vapid-keys

​
Production Checklist

All required variables are set
Strong passwords (16+ characters)
Unique JWT secrets for access and refresh tokens
HTTPS URLs in production (https://, wss://)
Specific CORS origins (no wildcards)
Email service configured and verified
Push notification keys generated
Error tracking enabled (Sentry)
Log level appropriate for environment

​
Validation

Validate your environment configuration: 
# Check all required variables are set
docker-compose config

# Test database connection
docker-compose exec backend npm run db:check

# Verify WhatsApp API credentials
docker-compose exec backend npm run whatsapp:verify

​
Platform-Specific Setup

​
Railway

Environment variables are set in the Railway dashboard under Variables tab.

​
Vercel

Set environment variables in Project Settings → Environment Variables. Note: Prefix client-side variables with NEXT_PUBLIC_

​
Docker Compose

Variables are loaded from .env file in project root automatically.

​
Kubernetes

Use ConfigMaps for non-sensitive data and Secrets for sensitive data: 
apiVersion: v1
kind: Secret
metadata:
  name: whatsapp-inbox-secrets
type: Opaque
stringData:
  JWT_SECRET: your-secret-here
  WHATSAPP_ACCESS_TOKEN: your-token-here

​
Troubleshooting

​
Variables not loading

  1. Check file name is exactly .env
  2. Verify no spaces around = sign
  3. Restart Docker containers: docker-compose restart

​
Database connection failed

  1. Verify DATABASE_URL format is correct
  2. Check database credentials match
  3. Ensure database is running: docker-compose ps postgres

​
WhatsApp webhook not working

  1. Verify WHATSAPP_WEBHOOK_VERIFY_TOKEN matches Meta configuration
  2. Check WHATSAPP_ACCESS_TOKEN is valid
  3. Ensure webhook URL is publicly accessible

​
Next Steps

WhatsApp Setup

Configure WhatsApp Business API

Quick Start

Deploy with one-click installation

Going Live

Production deployment checklist

Troubleshooting

Common issues and solutions