​
Overview

This guide will get Team Inbox deployed and operational in about 30 minutes. We’ll use Railway for the simplest deployment experience.
Prerequisites:
  • WhatsApp Business API credentials ready (or follow WhatsApp Setup first)
  • GitHub account
  • Credit card for Railway (charges after free tier)

​
Deployment Steps

​
Step 1: Fork the Repository

1

Go to GitHub Repository

Navigate to: https://github.com/shadowpint/whatsapp-team-inbox-ui
2

Click Fork

Click the “Fork” button in the top-right corner
3

Create Fork

Keep default settings and click “Create fork”
You now have your own copy of the code

​
Step 2: Deploy to Railway

1

Sign up for Railway

Go to railway.app and sign up with GitHub
2

Create New Project

Click “New Project” → “Deploy from GitHub repo”
3

Select Your Fork

Choose the whatsapp-team-inbox repository you just forked
4

Wait for Build

Railway will automatically build and deploy. This takes 2-3 minutes.

​
Step 3: Add PostgreSQL Database

1

Add Database Service

In your Railway project, click “New” → “Database” → “Add PostgreSQL”
2

Wait for Provisioning

Database will be created automatically (30 seconds)
3

Copy Database URL

Click on the PostgreSQL service → “Connect” → Copy the connection URL

​
Step 4: Configure Environment Variables

1

Open Backend Service

In Railway, click on your backend service
2

Go to Variables Tab

Click “Variables” in the top menu
3

Add Required Variables

Add the following environment variables:

​
Essential Variables

# Database
DATABASE_URL=<paste-your-railway-postgresql-url>

# WhatsApp Business API
WHATSAPP_PHONE_NUMBER_ID=<your-phone-number-id>
WHATSAPP_ACCESS_TOKEN=<your-whatsapp-access-token>
WHATSAPP_BUSINESS_ACCOUNT_ID=<your-business-account-id>
WHATSAPP_WEBHOOK_VERIFY_TOKEN=<create-random-string>

# JWT Secret (generate random string)
JWT_SECRET=<generate-random-secure-string>

# App URLs
BACKEND_URL=https://your-backend.railway.app
FRONTEND_URL=https://your-frontend.railway.app

# Email (Optional - use Resend)
RESEND_API_KEY=<your-resend-api-key>
EMAIL_FROM=noreply@yourdomain.com

# Push Notifications (generate VAPID keys - see below)
VAPID_PUBLIC_KEY=<your-vapid-public-key>
VAPID_PRIVATE_KEY=<your-vapid-private-key>
VAPID_SUBJECT=mailto:admin@yourdomain.com
Option 1: Online Generator
Visit: https://vapidkeys.com/
Click "Generate Keys"
Copy public and private keys
Option 2: Using web-push npm package
npm install -g web-push
web-push generate-vapid-keys
Option 3: Use existing Node.js
npx web-push generate-vapid-keys
Option 1: Command line
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Option 2: Online generator Visit: https://generate-secret.vercel.app/32
Don’t have WhatsApp credentials yet?Follow our detailed guide: WhatsApp Business API SetupYou’ll need:
  • Phone Number ID (from Meta Business Suite)
  • Access Token (from App Dashboard)
  • Business Account ID (from App Dashboard)
  • Webhook Verify Token (create your own random string)

​
Step 5: Deploy Frontend

1

Add Frontend Service

In Railway project, click “New” → “GitHub Repo” → Select your fork again
2

Configure Build

Railway should auto-detect Next.js. If not:
  • Build Command: cd web && npm install && npm run build
  • Start Command: cd web && npm start
3

Add Frontend Environment Variables

In frontend service Variables tab:
NEXT_PUBLIC_API_URL=<your-backend-railway-url>
NEXT_PUBLIC_WS_URL=<your-backend-railway-url-with-ws-protocol>

​
Step 6: Run Database Migrations

1

Access Backend Service Shell

Click backend service → ”…” menu → “Shell”
2

Run Prisma Migration

npx prisma migrate deploy
3

Verify Success

You should see: “All migrations have been successfully applied”

​
Step 7: Create Admin User

1

Generate Password Hash

In backend shell, run:
node -e "const bcrypt = require('bcrypt'); console.log(bcrypt.hashSync('your-password', 10))"
2

Create User in Database

In Railway PostgreSQL service, click “Query” tab:
INSERT INTO "User" (id, email, name, password, role, "createdAt", "updatedAt")
VALUES (
  gen_random_uuid(),
  'admin@yourcompany.com',
  'Admin User',
  '<paste-hashed-password>',
  'ADMIN',
  NOW(),
  NOW()
);

​
Step 8: Configure WhatsApp Webhook

1

Get Your Backend URL

Copy your Railway backend URL: https://your-backend.railway.app
2

Go to Meta App Dashboard

Navigate to: developers.facebook.com/apps → Your App → WhatsApp → Configuration
3

Add Webhook

  • Callback URL: https://your-backend.railway.app/api/webhook/whatsapp
  • Verify Token: (the same WHATSAPP_WEBHOOK_VERIFY_TOKEN you set earlier)
  • Click “Verify and Save”
4

Subscribe to Messages

Under “Webhook fields”, enable:
  • ✅ messages
  • ✅ message_status

​
Step 9: Test Your Deployment

1

Open Frontend URL

Visit your Railway frontend URL in browser
2

Log In

Use the admin email and password you created
3

Send Test Message

Send a WhatsApp message to your business number from your personal phone
4

Verify Message Appears

Message should appear in Team Inbox within seconds
5

Reply from Inbox

Type a reply in Team Inbox and send
6

Confirm Receipt

Check your phone - you should receive the reply
✅ Congratulations! Your Team Inbox is now live!

​
Quick Deployment Checklist

Your own copy of the code on GitHub
Backend and frontend services deployed
Database service running and connected
All required credentials and secrets set
Prisma migrations applied successfully
First user account for logging in
Meta sending messages to your backend
End-to-end flow verified

​
Common Deployment Issues

If something isn’t working, check these common issues:

​
Issue: “Database connection failed”

Solution:
  • Verify DATABASE_URL is correctly set
  • Check PostgreSQL service is running in Railway
  • Ensure no typos in connection string

​
Issue: “WhatsApp webhook verification failed”

Solution:
  • Verify WHATSAPP_WEBHOOK_VERIFY_TOKEN matches in both:
    • Railway environment variables
    • Meta App Dashboard webhook settings
  • Check backend service is accessible (visit backend URL in browser)

​
Issue: “Messages not appearing in inbox”

Solution:
  • Check WhatsApp webhook is subscribed to “messages” field
  • Verify backend logs in Railway (look for webhook events)
  • Ensure WHATSAPP_PHONE_NUMBER_ID is correct
  • Check WebSocket connection (open browser dev tools → Network)

​
Issue: “Can’t log in”

Solution:
  • Verify admin user was created in database
  • Check password hash was generated correctly
  • Ensure JWT_SECRET is set in backend environment
  • Try creating user again with fresh password hash

​
Issue: “Push notifications not working”

Solution:
  • Verify VAPID keys are correctly set
  • Check service worker is registered (browser dev tools → Application → Service Workers)
  • Ensure HTTPS is enabled (Railway provides this automatically)
  • Test notification permission in browser settings

​
Next Steps

First Setup Guide

Configure your Team Inbox for daily use

Invite Team Members

Add your team to start collaborating

User Guide

Learn how to use Team Inbox effectively

Troubleshooting

Solve common deployment issues

​
Alternative Deployment Options

This guide used Railway for simplicity. For other deployment options:

Deploy to AWS

EC2 + RDS deployment guide

Deploy to DigitalOcean

Droplet + managed database

Self-Hosted

Deploy on your own servers

​
Get Help

Stuck on deployment? We’re here to help!